Skip to content

Latest commit

 

History

History
85 lines (67 loc) · 3.59 KB

CONTRIBUTING.md

File metadata and controls

85 lines (67 loc) · 3.59 KB
Raw

Contributing Guidelines

Firstly, thank you for wanting to contribute to this project! If you're unsure on how to start contributing, please refer to the GitHub documentation on opening a pull request with forks.

There are plans to create a mdBook that explains the ideas and theory behind quantr in more detail. The maintainers' advice is to wait for the completion of this book before contributing.

How to contribute

Quantr uses the Gitflow strategy, for version control with git. Below is the general outline of this strategy,

  • fork this repository;
  • from the newly forked repository, create a new branch from the dev branch and prefix it's name with feat- or fix-, if adding a feature or fixing a bug respectively;
  • implement your changes in your newly created branch with a series of descriptive commits;
  • when finished with implementing your changes, make sure to add your name to the list of contributers in CONTRIBUTERS.md;
  • merge the dev branch into your created branch (to make sure it's up-to-date with latest changes) and resolve any conflicts; then
  • open a pull request to merge into this repositories dev branch, filling out the template provided.

Before submitting your pull request, make sure that your branch:

  • passes all tests by running cargo test;
  • is formatted with cargo fmt;
  • has additional unit testing to test your new code (if applicable); and
  • has signed off on all commits with your name and email, for example Emmy Noether <emmy.noether@rings.com>. Your name and email should be on its own line and placed at the end of the commit. By doing so, you are agreeing to the terms and conditions outlined in the Developer Certificate of Origin which can be found in COPYRIGHT.txt.

When a pull request is opened, a template should appear that shows the above as checklist (that should be ticked off), in addition to questions that the contributor should answer

What is a descriptive commit?

This is only specified to help maintain a well-documented repository, and help the maintainers review the pull request.

What the maintainers would appreciate are commits with:

  • one sentence titles, and less than 50 characters;
  • a space between title and paragraph; and
  • a paragraph hard-wrapped at 72 characters explaining the reasons for the commit.

Each commit should give justification to the changes and the edits that the commit induces. These justifications should not be what and where (as GitHub can clearly answer these), but help the reviewer in understanding how the commit achieves the goal of the overall pull request.

Do I need to sign off with my name and email address?

Yes. By doing so, you are agreeing to the Developer Certificate of Origin terms and conditions as outlined in COPYRIGHT.txt.

GitHub verified signatures will be reserved for the maintainers; so any contributions that aren't from maintainers will not be verified, but nevertheless very welcome!

Why all the guidelines?

Even though these are only 'guidelines' and are not strict rules to follow, we hope in doing so will ease the reviewing of pull requests for the maintainers; and more importantly create a well-documented repository.