Contribution & PR‐submission guidelines

Contribution Guidelines

1. All commits need a sign-off by the author (except for drafts) If additional reviewers gave their ack, a proper attribution header may be added.

2. Commit messages should explain what's really done here and their headlines need a short an precise subject. See history for examples.

   Keep in mind that history is also a piece of documentation.

3. Once release is out, bugfixes should be submitted separately, against the affected release branch(es) as well as master (so multiple pull requests)

4. If new functions or types are introduced, these should be documented in-code, so we can generate docs directly from the code :)

5. Use pull request tags if you can - if we need some more, just ask.

PR policy

In order to make review easier, and also make the git history a good documentation, that's easily understandable even a decade later, we need to add some bureaucratic policies:

1. each commits needs to be signed-off by the author or the submitter

2. commit messages should be made of a headline (separated by a blank line) and message body

3. headlines should be prefixed with the area that's changed (see existing commits), eg.:

   • "README.md: <....>"
   • "dix: rpcbuf: <...>"
   • "doc: <...>"

4. if the changed area is one of the DIX'es (hw/*), the "hw: " prefix should be skipped (eg. just "xfree86: ..." or "xnest: ...")

5. the message body should give a more detailed description what had been done and why (unless it's really obvious)

6. each individual commit should be self-contained (thus, not breaking anything, if it's applied alone, w/o subsequent ones of the same PR)

7. in order to ease review, individual commits should be small and simple to understand. eg. each individual commit shall only do one specific topic. if a topic is more complex and can be done in separate smaller steps, it should be splitted into several subsequent ones.

8. formatting changes should be separated from functional changes (except for lines that are touched by the functional change anyways)

9. refactoring changes (eg. renaming functions/variables/types, etc) should be separate commits

Branches

1. Usual development (new features, cleanups, ...) go against the master branch.

2. The maint-* branches are reserved for bugfixes only (that's where the bugfix releases are made from).

3. Bugfixes finally need to be applied to (affected) maintenance branches as well as master. The PRs should mention whether the fix needs to be ported to other branches (optimally, they should link each other)

4. if the submitter cannot create all the PRs for the separate branches himself, he should at least leave a note in the PR message (not the commit messages) to the reviewers, so the core team can take appropriate actions