Merge Requests#

To submit any changes, be it code, documentation updates or artwork we use merge requests. See our development guide for context. In order to submit any merge request you need an account on the code hosting platform the project is maintained on (see repositories).

Below are some guidelines on how to structure your contribution. The most important rule is though: if unsure publish your changes and get in touch. The projects maintainers will the provide further help.

Git commits#

Each merge request consists of one or more git commits. The commits should be in a recipe style order (rather than a work log). See here for an explanation of the difference. The advantage is that the code stays bisectable and individual bits can be cherry-picked or reverted making it easier for the maintainers to apply your changes (or parts of it).

If you are contributing a code change make sure that each commit compiles. This again helps bisectability.

Commit Messages#

Please make sure each git commit of the merge request has a descriptive commit message. This helps reviewer to figure out what this is about. The general layout is as follows:

identifier: Summary of the changes

Details of the change. This can have multiple lines but should line break at
80 characters. Try to be concise.

Closes: https://repo.example.com/…/1234
Closes: https://repo.example.com/…/1235
Signed-off-by: <youremail@example.com>

Note the empty line between the summary and the so called body of the commit message. If the commit fixes a reported issue, put the full URL to the issue after the summary. For details on how to draft a good commit message check the Openstack guide.

If a bug isn’t fully fixed but things are improved you can use Helps: instead of Closes:. If a bug fixes a regression consider adding a Fixes: line to inicate which commit is fixed. A simple way to create a Fixes: line is via:

git log -1 --pretty=format:'Fixes: %h ("%s")%n'

Developer’s Certificate of Origin#

By making a contribution to a project, you state that you’re allowed to make the contribution and that the project has the right to distribute it under its license. This happens by adding a Signed-off-by: line with your email address to each commit. By doing so you agree to the Developer Certificate of Origin 1.1:

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.