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. If you have Qt's standard commit-hooks set up, the Early Warning System will offer you some advice on this (and Gerrit will run the same script with more checks). 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 (following generic Git commit message guidelines)
      1. Use the commit subject to describe the cure (what the commit does), not the symptoms or disease (the bug/issue it fixes). Avoid variants of

         Fix <title of JIRA bug>
         

         .
      2. Tell why you changed something unless it is completely self-evident; this is particularly important for reverts.
      3. Make the commit self-contained, so people do not have to research the historical context to make sense of it. Conversely, do not add unnecessary trivia.
      4. Use the Qt commit template. Follow the summary + description message style and use footers to reference JIRA issues, collaborators, etc.
   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 dev and include a Pick-to footer, listing released versions back to the lowest applicable branch from which a release is still planned, that your change is relevant to.
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.

For more information, see: https://quips-qt-io.herokuapp.com/quip-0017-Change-log-creation.html

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.