Contributing to Towncrier#
Want to contribute to this project? Great! We’d love to hear from you!
As a developer and user, you probably have some questions about our project and how to contribute. In this article, we try to answer these and give you some recommendations.
Ways to communicate and contribute#
There are several options to contribute to this project:
Open a new topic on our GitHub Discussions page.
Tell us about your ideas or ask questions there. Discuss with us the next Towncrier release.
Help or comment on our GitHub issues tracker.
There are certainly many issues where you can help with your expertise. Or you would like to share your ideas with us.
Open a new issue using GitHub issues tracker.
If you found a bug or have a new cool feature, describe your findings. Try to be as descriptive as possible to help us understand your issue.
Check out the Libera
#twistedIRC channel or Twisted Gitter.
If you prefer to discuss some topics personally, you may find the IRC or Gitter channels interesting. They are bridged.
Modify the code.
If you would love to see the new feature in the next release, this is probably the best way.
Modifying the code#
The source code is managed using Git and is hosted on GitHub:
We recommend the following workflow:
Fork our project on GitHub.
Clone your forked Git repository (replace
GITHUB_USERwith your account name on GitHub):
$ git clone email@example.com:GITHUB_USER/towncrier.git
Prepare a pull request:
Create a new branch with:
$ git checkout -b <BRANCH_NAME>
Write your test cases and run the complete test suite, see the section Running the test suite for details.
Document any user-facing changes in one of the
/docs/files. Use one sentence per line.
Create a news fragment in
src/towncrier/newsfragments/describing the changes and containing information that is of interest to end-users. Use one sentence per line here, too. You can use the
towncrierCLI to create them; for example
towncrier create 1234.bugfix
Use one of the following types:
featurefor new features
docfor improvements to documentation
removalfor deprecations and removals
miscfor everything else that is linked but not shown in our
NEWS.rstfile. Use this for pull requests that don’t affect end-users and leave them empty.
Create a pull request. Describe in the pull request what you did and why. If you have open questions, ask. (optional) Allow team members to edit the code on your PR.
Wait for feedback. If you receive any comments, address these.
After your pull request is merged, delete your branch.
Running the test suite#
The following list contains some ways how to run the test suite:
To install this project into a virtualenv along with the dependencies necessary to run the tests and build the documentation:
$ pip install -e .[dev]
To run the tests, use
$ trial towncrier
To investigate and debug errors, use the
trialcommand like this:
$ trial -b towncrier
This will invoke a PDB session. If you press
cit will continue running the test suite until it runs into an error.
To run all tests against all supported versions, install nox and use:
You may want to add the
--no-error-on-missing-interpretersoption to avoid errors when a specific Python interpreter version couldn’t be found.
To get a complete list of the available targets, run:
$ nox -l
To run only a specific test only, use the
towncrier.test.FILE.CLASS.METHODsyntax, for example:
$ nox -e tests -- towncrier.test.test_project.InvocationTests.test_version
To run some quality checks before you create the pull request, we recommend using this call:
$ nox -e pre_commit check_newsfragment
Or enable pre-commit as a git hook:
$ pip install pre-commit $ pre-commit install
Please note: If the test suite works in nox, but doesn’t by calling
trial, it could be that you’ve got GPG-signing active for git commits which
fails with our dummy test commits.