Skip to content

Latest commit

 

History

History
238 lines (178 loc) · 9.08 KB

CONTRIBUTING.md

File metadata and controls

238 lines (178 loc) · 9.08 KB

The Wavestack project welcomes all contributions.

Please make sure that you adhere to the following requirements:

  • Git commits are signed
  • Commit messages adhere to the guidelines detailed below
  • You agree to the Developer Certificate of Origin (DCO) and include a suitable sign-off in the git commit message

Getting started

The handbook is created using Hugo, which is an open-source static site generator that takes Markdown as input. We use the Docsy theme that has been specifically designed for technical documentation.

If you have not used Hugo or Docsy before, we recommend to familiarise yourself with the following articles:

The specific Markdown dialect used by Hugo is CommonMark as implemented by the goldmark library. The CommonMark project provides a full specification of the markup language and a handy tutorial for learning it. These can be found on:

Contributions are accepted via [git][git]. Everything you ever wanted to know about git (and more!) can be found on:

and we would recommend to read at least the following:

Editor Setup

You can use editorconfig to automatically configure a subset of editor settings to defaults defined for this project.

Editorconfig comes already pre-installed for a number of environments or can be easily added as a plugin.

Code of Conduct

We would like our community to remain open and welcoming to everyone and kindly ask you to adhere to the CNCF Code of Conduct.

Developer Certificate of Origin (DCO)

By contributing to this project you are agreeing to the Developer Certificate of Origin (DCO) which is a document created by the Linux Foundation that is:

a per-commit sign-off made by a contributor stating that they agree to the terms published at https://developercertificate.org/ for that particular contribution.

We therefore require you to include a sign-off in every commit, by which you certify that your contribution adheres to the rules of the DCO:

Signed-off-by: Jane Doe <[email protected]>

The sign-off line can be automatically added to the commit message if you call git commit with -s.

Scope of changes

When contributing or planning a change, you should make sure that the feature you are working on addresses an actual need and is in line with the direction of this project.

Whilst many of your changes will be small, you might still want to discuss them with the maintainers or your colleagues before you start your work to ensure that your contribution is likely to get accepted.

We also encourage you to keep commits and merge requests small as they will be easier to review as a result.

Commits

Each commit in the history of the project tells a story. At best they express the evolution of a feature in semantically distinct units in a way that can be easily followed. Strive for breaking up your commits into units that can be applied or reverted independently.

Keep in mind that the git log serves as permanent record of your contribution and by breaking up larger changes into smaller steps you make it easier for everyone to follow along and understand your changes.

Merge requests

Merge requests are easiest to review if they are small and focused on a single problem or feature. Be kind to your reviewers and create a new merge request for every semantically different change you want to make.

Strive for making every merge request useful in its own right. If a commit introduces a bugfix or feature that has value outside the scope of the specific merge request you are working on then it should be in a separate MR as that allows it to be merged faster and deployed independently.

Sometimes your work is not yet finished, but you still want to gather initial feedback. You can create a draft merge request in that situation by adding [Draft] at the beginning of the merge request title. Doing so prevents it from being merged accidentally, while simultaneously allowing others to leave comments and reviews.

Commit message guidelines

Git commit messages tell a similar story to your merge requests or commits. But while the commits themselves focus on the how of changes, commit messages elaborate on the why and their context.

Peter Hutterer motivates this well:

Re-establishing the context of a piece of code is wasteful. We can’t avoid it completely, so our efforts should go to reducing it [as much] as possible. Commit messages can do exactly that and as a result, a commit message shows whether a developer is a good collaborator.

One of the most important aspects of well written commit messages is that, once messages are of consistently high quality, they will actually be read often. That is, they will become another important tool in toolbox. A tool that can be used to understand the context of every single line of code you find in the code base.

A typical commit message has two parts:

Summary

Commit body, that can span several lines...
...
...
...

Chris Beams defined seven rules of a great commit message:

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

and even provides an example of a good commit message:

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

See:
- #456
- https://www.example.com/some/relevant/link

Signed-off-by: Jane Doe <[email protected]>

If you like to learn more about this, you can read the following articles: