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. Make the new/changed code follow the coding style and coding conventions.
3. For GUI code, follow the style guide , the Qt Creator translation hints and avoid internationalization mistakes.
4. Ensure your change compiles and works on all platforms, also when Qt is built in a namespace. The CI system rejects broken changes.
5. Verify that there are no regressions in the unit tests (see Qt Autotest Environment for more info).
6. Write new unit tests for the bugs you fixed or functionality you added.
7. 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. ;)
8. 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. Fix the coding style only in exactly the lines which contain the functional changes, and fix comments 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, collaborators, etc. and consider the generic Git commit message guidelines.
   3. Commit often. Use git gui (or tig) 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
9. 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.
   Exception: There is no forward-merging from the LTS branch. Applicable changes must be integrated into the current stable branch first, and then be cherry-picked to the LTS branch (or the associated release branch).
10. Review your changes before you push to Gerrit. git gpush --list[-online], git log [--stat] [--summary] [-p] @{u}.. and gitk are your friends.
11. Pay attention to what git and Gerrit are telling you. If something unusual happens, don't shrug it off.

Next, follow the Review Policy.

Change Log

If the change is significant and affects many users, compatibility, or is a noteworthy feature, you must add a ChangeLog entry. You may add more than one ChangeLog entry, each in a separate paragraph, if there are several ways the change affects users. Conversely, do not add ChangeLog entries that are not relevant to users.

• A [ChangeLog] entry may span multiple lines and ends with an empty line.
• It starts with a sequence of tags, each in square brackets, the first of which is [ChangeLog].
  • Iff the Git repository contains multiple modules, use the module name as a tag to indicate the area of the change, e.g. [QtCore].
  • Optionally specify a class or subtopic as an additional tag, e.g. [QtNetwork][QSslSocket].
  • Other common tags are:
    • [General]
    • [Important Behavior Changes]
    • [Platform Specific Changes]
    • [Windows]
    • [OS X]
    • [Linux/XCB]
• After the tags, describe how the change impacts users of the relevant component.
  • Try to integrate the ChangeLog entry into the surrounding commit message to avoid redundancy.
  • If the change resolves a security issue, summarise the issue and mention any relevant CVE or kindred identifiers.
  • 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.
• 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).

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.