Difference between revisions of "Qt Contribution Guidelines"

From Qt Wiki
Jump to: navigation, search
(Link commit template)
(clarify cla process.)
Line 27: Line 27:
# ... make changes ...
# ... make changes ...
# <tt>git commit -a</tt>
# <tt>git commit -a</tt>
#* See [http://code.qt.io/cgit/qt/qt5.git/tree/.commit-template default commit template] for instructions on formatting the commit message
#* See default commit template for instructions on formatting the commit message
Then there are steps you need to follow for each patch you contribute:
Then there are steps you need to follow for each patch you contribute:

Revision as of 12:18, 16 January 2017

We have a community around the development of the Qt libraries, Qt related tools and add-ons. These guidelines will introduce you to the tools and mechanics as well as to the philosophies behind the development of Qt. You will learn how to set up your development environment for working on the library itself and how to submit code/documentation for inclusion.

Qt Contribution Process.png

Creating Changes for Inclusion Into Qt

When you intend to make changes, you need git clones configured for use with Gerrit. This mostly supersedes the more user-oriented instructions for getting the Qt source code and setting up your local working environment to build Qt.

The Gerrit tutorial describes in detail how our version of Gerrit works for the Qt Project. Here is the short version.

There are some steps you need to follow only once:

  1. Create a Qt account. This login is used by both the JIRA bug tracker and the Gerrit code review system. Even though the account credentials are shared, you still need to complete the account details in Gerrit. See the next step.
  2. Login on and set up your Gerrit account by adding your full name, email address, and public SSH key.
  3. Review and agree to the Qt Project's contribution license agreement (CLA) in Gerrit. You need to do this only once, unless the license changes.
    • If your company has a corporate contribution agreement, ask the admin of your company's Gerrit user group to add your account to this group.
    • More details about the CLA can be found here.
  4. Clone Qt from the read-only mirror.
  5. When you run the init-repository script, provide your Gerrit username to the --codereview-user option.

Then you make your change to a local dev branch. Example:

  1. git branch 5.6 my-fix
  2. git checkout my-fix
  3. ... make changes ...
  4. git commit -a
    • See default commit template for instructions on formatting the commit message

Then there are steps you need to follow for each patch you contribute:

  1. Push your changes to remote "gerrit" to the branch refs/for/target-branch.
    • Example: git push gerrit HEAD:refs/for/dev
    • Example: git push gerrit HEAD:refs/for/5.6
  2. The Early Warning System (EWS) will quickly kick in and check your patch. Please act upon the reports and push updates to the patch.
  3. Add relevant reviewers to your change(s). If you don't do this, your change may go unnoticed. To find possible reviewers, you can:
    • examine the Git history with 'git log' and/or 'git blame',
    • see the Maintainer chart,
    • ask on IRC, or
    • ask on relevant mailing lists like development@qt-project.org or qt-creator@qt-project.org, etc.
  4. Wait for reviews, and actively partake in the review of your change(s).
    • If your contribution is deemed to not align with the project's vision or goals, you should abandon the change at this point.
    • If your contribution is deemed unready, you need to fix it up according to the reviews.
  5. Submit your patch. If your contribution satisfies the technical requirements, then you or the Approver are able to submit the patch into the staging branch, or directly into the target branch, if there's no CI system on that particular branch and/or repository.
    • To determine if the branch is covered by the CI system, you may check the CI logs ; if the project/branch can be found at this link, it is covered by CI.
    • If the continuous integration (CI) system rejects your patch, you need to fix the issues so it passes the project's build and autotest systems.
  6. When CI is successful, your changes are automatically included and added to the official Qt repository.

See Gerrit Caveats and Hints to avoid common traps.

When you start an entirely new project or import an existing one from elsewhere, you need to request a new repository.

Style, Conventions and Principles

For development of the Qt framework we follow the framework's Qt Coding Style and we stick to our established Coding Conventions. The KDE Library Code Policy is based on Qt's, so much is shared with Qt's. You can find more information there that isn't in Qt pages.

Qt Creator uses its own Qt Creator Specific Coding Style & Conventions. It is similar to the Qt framework's coding style and conventions, but there are some differences and additions.

In addition, conventions for writing good user interface messages texts that play well with Qt Linguist can be found under UI Text Conventions.

Our API Design Principles aim for perfection.

Note that Qt is an open source library, and must therfore be compilable in its completeness using freely available tools and libraries. This means that you should not contribute code that uses any kind of private APIs.

Please follow the Commit Policy.

Verify that your commits have correct author information, including your name and email address as it is registered in Gerrit.

Localization to Other Languages

The process of contributing translations is described in Qt Localization.

Developer's Lounge

If you have any questions about the development of Qt, feel free to join the #qt-labs IRC channel on irc.freenode.net and the Qt development mailing list Qt Creator development, join #qt-creator on irc.freenode.net and the Qt Creator mailing list.

For a full list of IRC channels of interest to Qt developers, Online Communities.