diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..30c591e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,118 @@ +# Contributing to the www.aboutcode.org website + +Thank you so much for being so interested in contributing to AboutCode. We +welcome enthusiastic contributors like you who can make our project better, +and we're willing to lend a helping hand if you have questions or need +guidance along the way. That being said, here are a few +resources to help you get started. + + By contributing to this AboutCode project, you agree: + - To the [Developer Certificate of Origin](http://developercertificate.org/). + - That your Contributions to AboutCode are licensed under Apache-2.0. + +## Do Your Homework + +Before adding a contribution or create a new issue, take a look at the project’s +[README](https://github.com/aboutcode-org/www.aboutcode.org/blob/main/README.md) +and browse existing [issues](https://github.com/aboutcode-org/www.aboutcode.org/issues) +to develop some understanding of the project and confirm whether a given +issue/feature has previously been discussed. + +## Ways to Contribute + +Contributing to the codebase is not the only way to add value to AboutCode or +join our community. Below are some examples to get involved: + +### First Timers + +You are here to help, but you're a new contributor! No worries, we always +welcome new contributors. We maintain some +`good first issues `_ +and encourage new contributors to work on those issues for a smooth start. + +**"Can I work on this issue?"** + +You do not need our permission to work on an open issue. +A good start is to present your understanding of the problem/bug and how you +would fix it. Providing some code using a pull request will come handy, +but being able to explain a solution is always a good start. +Make sure to read through this page and follow the recommendations. + +**"Is this issue open?"** + +Unless closed, yes it is open. + +### Report Issues + +- Report a new [bug](https://github.com/aboutcode-org/www.aboutcode.org/issues>); +please make your bug report as specific as possible. +- Create a new [issue](https://github.com/aboutcode-org/www.aboutcode.org/issues) + to request a feature, submit a feedback, or ask a question. +- Make sure to check existing [issues](https://github.com/aboutcode-org/www.aboutcode.org/issues]) to confirm whether a given issue or a question has previously + been discussed. + +### Code Contributions + +Code is contributed to the codebase using **pull requests**. +A pull request should always be attached to an existing issue. +When there is no existing issues, start by an [issue](https://github.com/aboutcode-org/www.aboutcode.org/issues). +to discuss potential solutions and implementation details before writing any code. + +We use several conventions to ensure code quality regarding format, testing, +and attribution. + +**Make sure to follow those conventions before submitting your code:** + +1. **Code validation** + + We use `PEP8 `_ conventions. + A command is available to automatically format your code:: + + make valid + +2. **Unit tests** + + We write tests, a lot of tests, thousands of tests. + When fixing bugs or adding new features, you should add tests too. + You can run the test suite with:: + + make test + +3. **Commit messages and Developer Certificate of Origin** + +Follow the instructions at [Writing good Commit Messages](https://aboutcode.readthedocs.io/en/latest/contributing/writing_good_commit_messages.html) + + **You must include a "Signed-off-by" to your commit messages**:: + + Signed-off-by: Philippe Ombredanne + +4. **Your code is now ready to be pushed as a PR** + +Pull requests that are not passing the automated integration tests are +unlikely to be reviewed. Focus on making all the "Checks" to pass before +asking for a code review. + +### Documentation Improvements + +Documentation is a critical aspect of any project that is usually neglected or +overlooked. We value any suggestions to improve +`DejaCode documentation `_. + +Our documentation is treated like code. Make sure to check our +`writing guidelines `_to help guide new users. + +### Other Ways + +You want to contribute to other aspects of the an AboutCode project, and you +can't find what you're looking for! You can always discuss new topics, ask +questions, and interact with us and other community members on +[Gitter](https://gitter.im/aboutcode-org/discuss) + +### Helpful Resources +For more details on how to add quality contributions to our codebase and +documentation +- Check this free resource about [how to contribute to an open source project on github](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github) +- Follow [this wiki page](https://aboutcode.readthedocs.io/en/latest/contributing/writing_good_commit_messages.html) + on how to write good commit messages +- [Pro Git book](https://git-scm.com/book/en/v2) +- [How to write a good bug report](https://www.softwaretestinghelp.com/how-to-write-good-bug-report/)