Commit Policy

These are the general rules for creating and pushing commits to any shared Qt repositories. As usual at Qt, none of these rules is set in stone, but you will be subject of public reprimand if you violate them without good reason.

1. If you add new functions/classes:
   1. Ensure everything is documented properly.
   2. Follow the API Design Principles. Discuss and verify the names of functions/classes with other Qt developers (conduct API reviews).
2. If you're fixing a bug, add the relevant task numbers using the "Task-number" field mentioned in the commit template.
3. All code should follow the Coding Conventions.
4. For GUI code, follow the style guide , the Qt Creator translation hints and avoid internationalization mistakes.
5. Ensure your change compiles and works on all platforms, also when Qt is built in a namespace. The CI system rejects broken changes.
6. Verify that there are no regressions in the unit tests (see Public Autotest Infrastructure for more info).
7. Write new unit tests for the bugs you fixed or functionality you added.
8. Make your new/changed code follow the coding style.
9. Produce commits which facilitate reviews and contribute to a useful history which can be read, searched, annotated and cherry-picked. In particular:
   1. Make atomic commits. That means that each commit should contain exactly one self-contained change - do not mix unrelated changes, and do not create inconsistent states. Never "hide" unrelated fixes in bigger commits. Make coding style fixes only in exactly the lines which contain the functional changes, and comment fixes only when they relate to the change - the rest is for a separate commit.
   2. Write descriptive commit messages. Make them self-contained, so people do not have to research the historical context to make sense of them. Conversely, do not put unnecessary trivia into them. Tell why you changed something unless it is completely self-evident; this is particularly important for reverts. Use the Qt commit template. Follow the summary + description message style and use footers to reference JIRA issues, reviewers, etc. and consider the generic Git commit message guidelines.
   3. Commit often. Use git gui and git rebase -i extensively to get your unpublished history into shape. Note that pushing to your private clone does not count as publishing and is a perfectly valid way to solicit an early review or to make a backup of a work in progress. Further reading: Understanding the Git Workflow
   4. Avoid unnecessary merges. Use git pull —rebase unless you have an unpushed "proper" merge. Our Gerrit permits only trusted Merge Masters to push merge commits.
10. Do not commit anything you do not understand. "Somehow it suddenly works" is not acceptable. Reverting when a proper fix would be possible is admitting defeat. ;)
11. Review your changes before you push to Gerrit. git log [--stat] [--summary] [-p] @{u}.. and gitk are your friends.
12. Make sure to follow the Branch Guidelines. Submit against the lowest applicable branch from which a release is still planned. Cherry-picks ("backports") are strongly discouraged (use the -x option if you still do), while forward-merging to more recent branches happens "automatically" on a regular basis.
13. Peer review is strongly encouraged. Do not approve your own changes. Discuss objections.
    • If there is no candidate for a review yet, introduce somebody to the code.
    • Maintainer privilege: A maintainer may approve his own change to the code he maintains if
      1. at least one review (+1) from somebody else is present, and
      2. nobody else who could approve (+2) the change can be produced within reasonable time
14. Do not ignore/fight the Early Warning System. Justify each override.
15. And most importantly: use your brain.

Change Log

If the change is significant and affects many users, compatibility, or is a noteworthy feature, you must add a ChangeLog tag. Conversely, do not add ChangeLog entries that are not relevant to users.

• A [ChangeLog] entry can be multiple lines long and ends with an empty newline.
• Try to integrate the changelog entry into the surrounding commit message to avoid redundancy.
• If the Git repository contains multiple modules, use the module name to indicate the area of the change e.g. [QtCore].
• Optionally specify a class or subtopic [QtNetwork][QSslSocket]
• Other common tags are:
  • [General]
  • [Important Behavior Changes]
  • [Platform Specific Changes]
  • [Windows]
  • [OS X]
  • [Linux/XCB]
• In summary the entry should look like this:

  [ChangeLog][module][class/topic] description of the really important
  change that was just made (on several lines).

  • The description should use either simple past ("Fixed …") or be explicit about referring to the current state ("… does now …").
  • Make sure the entry is reasonably self-contained. If you fail to formulate a meaningful description, it's probably not useful information to start with.

Additional notes

• When you commit translations, use "make commit-ts" instead of "git commit" to keep the line number information out of the committed files.
• For non-native English speakers who'd like any written English (code comments and documentation in general) to be reviewed, feel free to add one of the people listed under the Approvers and Editors section here.