Skip to content

Latest commit

 

History

History
149 lines (89 loc) · 4.61 KB

CONTRIBUTING.rst

File metadata and controls

149 lines (89 loc) · 4.61 KB
Raw

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 #twisted IRC 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:

https://github.com/twisted/towncrier
[email protected]:twisted/towncrier.git

We recommend the following workflow:

  1. Fork our project on GitHub.

  2. Clone your forked Git repository (replace GITHUB_USER with your account name on GitHub):

    $ git clone [email protected]:GITHUB_USER/towncrier.git

  3. Prepare a pull request:

    1. Create a new branch with:

      $ git checkout -b <BRANCH_NAME>

    2. Write your test cases and run the complete test suite, see the section Running the test suite for details.

    3. Document any user-facing changes in one of the /docs/ files. Please use one sentence per line.

    4. Create a newsfragment in src/towncrier/newsfragments/ describing the changes and containing information that is of interest to end-users. Please use one sentence per line here, too.

    5. 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.

  4. Wait for feedback. If you receive any comments, address these.

  5. After your pull request is merged, delete your branch.

Running the test suite

We use the twisted.trial module and nox to run tests against all supported Python versions and operating systems.

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 like so:

    $ trial towncrier

  • To investigate and debug errors, use the trial command like this:

    $ trial -b towncrier

    This will invoke a PDB session. If you press c it will continue running the test suite until it runs into an error.

  • To run all tests against all supported versions, install nox and use:

    $ nox

    You may want to add the --no-error-on-missing-interpreters option 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.METHOD syntax, 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.