Skip to content

Latest commit

 

History

History
103 lines (73 loc) · 3.17 KB

CONTRIBUTING.rst

File metadata and controls

103 lines (73 loc) · 3.17 KB
Raw

Contributing

We love pull requests from everyone. By participating in this project, you agree to abide by the contributor covenant suggested code of conduct.

We Use Github Flow, So All Code Changes Happen Through Pull Requests

Pull requests are the best way to propose changes to the codebase (we use Github Flow). We actively welcome your pull requests:

  1. Fork the repo and create your branch from main.
  2. If you’ve added code that should be tested, add tests.
  3. If you’ve changed APIs, update the documentation.
  4. Ensure the test suite passes.
  5. Make sure your code lints.
  6. Issue that pull request!
  7. (optional) Add a release note if necessary.

Commit Style

A sample good commit is:

fileName: Thing I did
Some subHeading things

So this change was to do that thing I thought was good. Also there was this
other person who thought so too, so then I ate a sandwich and we got the code
done. I am writing this but really, honestly, two people did this.


Co-authored-by: Joel Doe <[email protected]>

A good commit should have:

  • The name of the file, or the topic or the subject you have changed or the namespace or the functionality you have added something:
  • A line describing something:
  • An (optional) subheading with more details
  • An (optional) paragraph or essay on why the change was done and anything else you want to share with the devs.
  • Co-authorship IS MANDATORY if applicable.

Automated Styles

A pre-commit job is setup on CI to enforce consistent styles, so it is best to set it up locally as well (using pipx for isolation):

# Run before committing
pipx run pre-commit run --all-files
# Or install the git hook to enforce this
pipx run pre-commit install

Changelog management

We use reST for the changelog fragments, and they are stored under changelog.d

  • Use pull requests to number the snippets
  • Build a final variant with: towncrier build --version 0.6.3 --date "$(date -u +%Y-%m-%d)"
  • Supported categories are:
  • feat
  • api
  • bugfix
  • misc

Here are some sample use cases:

towncrier create -c "Fancy new feature but with a PR attached" +new_thing.added.rst
towncrier create -c "Require C++17 only" 1.misc.rst

The generated files can be modified later as well.