Skip to content

Latest commit

 

History

History
131 lines (90 loc) · 10.6 KB

CONTRIBUTING.md

File metadata and controls

131 lines (90 loc) · 10.6 KB
Raw

Contributing to WinkNLP

Thank you for taking time to contribute. We are delighted to receive contributions from the community. For wink-nlp every contribution matters — whether you are reporting a bug, posting a question or suggestion, submitting a pull request or updating the documentation.

This document will guide you through the contribution process and guidelines.

Getting Started

If you spot a bug/issue and the same has not yet been reported, raise a new issue or consider fixing it and sending a PR. If you have questions and/or suggestions, post them at our discussions. New features may also be discussed there; eventually you may consider developing the same and sending a PR.

How to send a PR?

  1. Fork the repository from github
  2. Develop your code changes
  3. Capture the logic in comments
  4. Ensure that the API is properly documented
  5. Ensure proper linting
  6. Write test cases to cover each and every change and/or new feature
  7. Review security and performance
  8. Run the entire test suite
  9. Make sure coverage either stays at the current levels or improves; note minimum acceptable level is ≥99.5%
  10. Commit your changes in compliance with commit guidelines
  11. Push to your fork
  12. Sign the CLA if you are contributing for the first time

After completing the above steps, you are ready to submit the pull request.

Code of Conduct

By contributing, you are expected to uphold wink’s code of conduct. In essence, each one of us should:

  1. respect fellow contributors, irrespective of their level of experience, race, religion, gender, sexual orientation, and age;
  2. collaborate constructively;
  3. never engage in any form of offense, harassment, insult, personal attack, provocation and/or use of inappropriate language;

Development Guidelines

WinkNLP is a developer-friendly Natural Language Processing (NLP) library, whose API is designed specifically to make development of NLP solutions easier and faster. Do take out some time in understanding the structure of APIs, before attempting any enhancements.

In winkNLP, we prefer functions and closures over objects/classes.

Like artisans, we too need a toolset and process to create beautiful software. The process is orchestrated by Travis CI in accordance with the configuration files present in the repository. The details are outlined below:

Linting

Well defined linting rules or coding standards help us in making code more consistent and avoid bugs. ESLint enforces these rules automatically. These rules are defined in a configuration file named .eslintrc.json, which is located at the root of the repository. These rules cover basic formatting, naming conventions, limits of code complexity, and many more; please refer to the configuration file for further details.

We recommend using a suitable ESLint plugin/add-on for the code editor. Use script npm run pretest at command line to run linting on the entire code.

Documenting

We believe that the documentation must not only explain the API but also narrate the story of logic, algorithms and references used. WinkNLP uses the JSDoc standard for API documentation. It is inspired by Literate-Programming Standards for documenting the logic using docker; the npm run sourcedocs script generates a well formatted code documentation in HTML.

Testing

Test cases should cover each and every feature and/or change; use of standard test heuristics such as equivalence partition, boundary values, empty/null value, and decision tree is recommended to write effective test cases.

WinkNLP requires a test coverage of at least ≥99.5% and aims for 100%. Any new contribution must maintain the existing test coverage level. We use Chai, Mocha and Istanbul, Coveralls to run tests and determine coverage.

Use script npm run test at command line to run the entire test suite and obtain test coverage report.

Performance Considerations

It is important to maintain the performance of winkNLP, whenever a change is made and/or a new feature is added. We use the benchmark package to measure performance in tokens per second for the entire NLP pipeline. Use script npm run perf at command line to measure performance.

Security Considerations

Our security review/testing is inspired from the recommendations in OWASP's NodeJS Security Cheat Sheet that are applicable to winkNLP — since it is a library used by developers to create NLP web/mobile/CLI apps/tools, only Platform Security specific recommendations apply. We follow the guidelines outlined below:

  1. Stay away from using any external package — winkNLP has 0 external dependency.
  2. Use ESLint as a Static Analysis Security Testing (SAST) tool.
  3. Never use eval() function.
  4. Avoid prototype pollution by using objects created via Object.create( null ).
  5. Perform input validation with defined default behavior.
  6. Use tools like regexploit to detect potential ReDoS apart from reviewing regexes using regex 101 on Chrome browser (Latest stable version), Node.js (LTS version).

Committing

We follow commit guidelines from Google's Angular Project, whose documentation is licensed under CC BY 4.0. See important excerpts for quick reference below:

Commit Message Format

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The header is mandatory and the scope of the header is optional. Any line of the commit message should not be longer than 100 characters!

Type should be one of the following:

  • build: Changes that affect the build system or external dependencies
  • ci: Changes to our CI configuration files and scripts
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • test: Adding missing tests or correcting existing tests
  • revert: When you have to revert to an older commit. Ths subject should be the header of the old commit and the body should contain This reverts commit <hash>. Use the git revert command to accomplish this.

Scope specifies the place of the commit change. You can use * when the change affects more than a single scope.

Subject must contain a crisp description of the change and it must (a) use the imperative, present tense: "change" not "changed" nor "changes", (b) not capitalize the first letter, and (c) not use period (.) at the end.

Body just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change.

Footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit closes. Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.

Versioning

WinkNLP follows semantic versioning for every release.

Governance

This section outlines winkNLP’s governance guidelines:

  1. This is a project of Graype Systems Private Limited (Graype), which is a micro-size company incorporated in India.
  2. The project team consists of 3-core members, including a technical lead.
  3. The project welcomes contributions from the community. For winkNLP every contribution matters — whether it is reporting a bug/issue, posting a question/suggestion, submitting a pull request or updating the documentation.
  4. Everyone is entitled to state their opinion and may present their arguments. There is an effort to achieve consensus but in absence of obvious consensus, the technical lead has the final say in decision making. It roughly matches a standard BDFL (Benevolent Dictator For Life) style project.
  5. WinkNLP is licensed under the terms of the MIT license; therefore there are no limitations on forking and developing it further separately.
  6. The technical lead has commit and administrative rights on the project's organization and repository at Github. Therefore the technical lead can make changes and accept changes — typically pull requests submitted by others. These changes may include changes to the process and contribution requirements.
  7. Graype offers commercial support and/or services around the project.
  8. The key roles are (a) User — who uses or has used the package; (b) Contributor — who has reported one or more issues, participated in one or more discussions OR sent one or more PRs; (c) Core Team Member as stated above and (d) Technical Lead.
  9. Core team members are Prateek Saxena, Rachna Chakraborty and Sanjaya Kumar Saxena (Technical Lead).
  10. Current opportunities to participate are outlined in the roadmap.
  11. Every PR must comply with our development guidelines before they can be accepted/merged.
  12. Participation requires adherence to our code of conduct.

Contributor License Agreement (CLA)

The CLA is for your protection as well as the protection of Graype and it’s licensees; it does not change your rights to use your own Contributions for any other purpose. Our CLA is a short and easy to understand agreement and can be signed using a simple click-through form. Please sign our Contributor License Agreement (CLA) before sending pull requests. It's a quick process, we promise!