Skip to content

Latest commit

 

History

History
73 lines (51 loc) · 4.05 KB

CONTRIBUTING.adoc

File metadata and controls

73 lines (51 loc) · 4.05 KB
Raw

Introduction

We gratefully accept contributions via pull requests.

Use the issue tracker to suggest feature requests, report bugs, and ask questions. This is also a great way to connect with the developers of the project as well as others who are interested in this solution.

Changing the code-base

Generally speaking, you should fork this repository, make changes in your own fork, and then submit a pull-request. This is often called the Fork-and-Pull model

  • All contributions to this project will be released under the inbound=outbound norm, that is, they are submitted under the projects main license.

  • By submitting a pull request or filing a bug, issue, or feature request, you agree to comply with this waiver of copyright interest. Details can be found in the LICENSE.

  • All new code should have associated unit tests that validate implemented features and the presence or lack of defects.

  • Additionally, the code should follow any stylistic and architectural guidelines prescribed by the project. In the absence of such guidelines, mimic the styles and patterns in the existing code-base.

Signoff and optionally Sign each Commit

As part of filing a pull request you agree to the DCO. Developer Certificate of Origin

A DCO is a lightweight way for a contributor to confirm that they wrote or otherwise have the right to submit code or documentation to a project.

To confirm that you agree to the DCO, you need to sign off your commits when sending us a pull request. Technically, this is done by supplying the -s/--signoff flag to git when committing:

$ git commit -s -m "add fix for the bug"

Optionally, you can also sign the commit with -S which also gives your commit a nice verified button on GitHub, but, it requires that you have a GPG keypair set up. For mor information, see Sign commit on GitHub with GPG key

$ git commit -s -S -m "add fix for the bug"

For the difference in signoff and signing, see Git signoff vs signing

Git History

In order to maintain a high software quality standard, we strongly prefer contributions to follow these rules:

  • We pay more attention to the quality of commit messages. In general, we share the view on how commit messages should be written with the Git project itself:

  • Make separate commits for logically separate changes. For example, pure formatting changes that do not affect software behaviour usually do not belong in the same commit as changes to program logic.

  • Describe your changes well. Do not just repeat in prose what is "obvious" from the code, but provide a rationale explaining why you believe your change is necessary.

  • Describe your changes in the imperative. Instead of writing "Fixes an issue with encoding" prefer "Fix an encoding issue". Think about it like the commit only does something if it is applied. This usually results in more concise commit messages.

  • We are picky about whitespaces. Trailing whitespace and duplicate blank lines are simply a superfluous annoyance, and most Git tools flag them red in the diff anyway.

If you have ever wondered how a "perfect" commit message is supposed to look like, just look at basically any of Jeff King’s commits in the Git project.

Thank you for reading and happy contributing!