diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 69c121a5..845c687c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. +Contributions are welcome, and they are greatly appreciated! Every little helps, and credit will always be given. You can contribute in many ways: @@ -8,9 +8,7 @@ You can contribute in many ways: ### Report Bugs -Report bugs at [on our issue tracker][bug-tracker]. - -If you are reporting a bug, please include: +Report bugs to [our issue page][gh-issues]. If you are reporting a bug, please include: - Your operating system name and version. - Any details about your local setup that might be helpful in troubleshooting. @@ -30,78 +28,90 @@ Django Codemod could always use more documentation, whether as part of the offic ### Submit Feedback -The best way to send feedback is [to file an issue on Github][bug-tracker]. - -If you are proposing a feature: +The best way to send feedback [our issue page][gh-issues] on GitHub. If you are proposing a feature: - Explain in detail how it would work. - Keep the scope as narrow as possible, to make it easier to implement. -- Remember that this is a volunteer-driven project, and that contributions are welcome :) +- Remember that this is a volunteer-driven project, and that contributions are welcome 😊 ## Get Started! -Ready to contribute? Here's how to set up `django-codemod` -for local development. +Ready to contribute? Here's how to set yourself up for local development. + +1. Fork the repo on GitHub. + +2. Clone your fork locally: -1. Fork the `django-codemod` repo on GitHub. + ```shell + $ git clone git@github.com:your_name_here/django-codemod.git + ``` -2. Clone your fork locally: +3. Install the project dependencies with [Poetry](https://python-poetry.org): - ```shell - $ git clone git@github.com:your_name_here/django-codemod.git - ``` + ```shell + $ poetry install + ``` -3. Make sure you have [Poetry] installed, and from the root of the project run: +4. Create a branch for local development: - ```shell - $ poetry install - ``` + ```shell + $ git checkout -b name-of-your-bugfix-or-feature + ``` -This will install all the needed dependencies for development in an isolated environment. + Now you can make your changes locally. -4. Create a branch for local development: +5. When you're done making changes, check that your changes pass our tests: - ```shell - $ git checkout -b name-of-your-bugfix-or-feature - ``` + ```shell + $ poetry run pytest + ``` - Now you can make your changes locally. +6. Linting is done through [pre-commit](https://pre-commit.com). Provided you have the tool installed globally, you can run them all as one-off: -5. When you're done making changes, check that your the tests are passing: + ```shell + $ pre-commit run -a + ``` - ```shell - $ poetry run pytest - ``` + Or better, install the hooks once and have them run automatically each time you commit: - Please write tests for any new feature or bug fix, we aim to keep 100% code coverage. + ```shell + $ pre-commit install + ``` -6. Commit your changes and push your branch to GitHub: +7. Commit your changes and push your branch to GitHub: - ```shell - $ git add . - $ git commit -m "feat(something): your detailed description of your changes" - $ git push origin name-of-your-bugfix-or-feature - ``` + ```shell + $ git add . + $ git commit -m "feat(something): your detailed description of your changes" + $ git push origin name-of-your-bugfix-or-feature + ``` - Note: the commit message should follow [the conventional commits guidelines][conv-commits], this is to enable the automation of releases. We run [`commitlint` on CI][commitlint] which will validate the commit messages. + Note: the commit message should follow [the conventional commits](https://www.conventionalcommits.org). We run [`commitlint` on CI](https://github.com/marketplace/actions/commit-linter) to validate it, and if you've installed pre-commit hooks at the previous step, the message will be checked at commit time. -7. Submit a pull request through the GitHub website. +8. Submit a pull request through the GitHub website or using the GitHub CLI (if you have it installed): + + ```shell + $ gh pr create --fill + ``` ## Pull Request Guidelines -When you submit a pull request, check that it meets these guidelines: +We like to have the pull request open as soon as possible, that's a great place to discuss any piece of work, even unfinished. You can use draft pull request if it's still a work in progress. Here are a few guidelines to follow: + +1. Include tests for feature or bug fixes. +2. Update the documentation for significant features. +3. Ensure tests are passing on CI. + +## Tips + +To run a subset of tests: -1. The pull request should include tests. -2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst. -3. The pull request should work for Python 3.6, 3.7, 3.8 and 3.9. Check the build on Github and make sure that the tests pass for all supported Python versions. +```shell +$ pytest tests +``` -## Deploying +## Making a new release -The deployment should be automated and can be triggered from the Semantic Release workflow in Github. The next version will be based on [the commit logs][commit-log-parsing]. This is done by [python-semantic-release][psr] via a Github action. +The deployment should be automated and can be triggered from the Semantic Release workflow in GitHub. The next version will be based on [the commit logs](https://python-semantic-release.readthedocs.io/en/latest/commit-log-parsing.html#commit-log-parsing). This is done by [python-semantic-release](https://python-semantic-release.readthedocs.io/en/latest/index.html) via a GitHub action. -[bug-tracker]: https://github.com/browniebroke/django-codemod/issues -[poetry]: https://python-poetry.org/ -[conv-commits]: https://www.conventionalcommits.org -[commitlint]: https://github.com/marketplace/actions/commit-linter -[commit-log-parsing]: https://python-semantic-release.readthedocs.io/en/latest/commit-log-parsing.html#commit-log-parsing -[psr]: https://python-semantic-release.readthedocs.io +[gh-issues]: https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/issues