Qt Contribution Guidelines: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(restore missing line)
(adding https://lists.qt-project.org reference)
 
(28 intermediate revisions by 18 users not shown)
Line 3: Line 3:
__TOC__
__TOC__


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.
We have a community around the development of the Qt libraries, Qt related tools and add-ons called the Qt Project. 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.


[[File:Qt_Contribution_Process.png]]
[[File:Qt_Contribution_Process.png]]


== Creating Changes for Inclusion Into Qt ==
==Creating Changes for Inclusion Into Qt==


When you intend to make changes, you need git clones [[Setting up Gerrit|configured for use with Gerrit]]. This mostly supersedes the more user-oriented instructions for [[Get The Source|getting the Qt source code]] and setting up your local working environment to build Qt.
When you intend to make changes, you need git clones [[Setting up Gerrit|configured for use with Gerrit]]. This mostly supersedes the more user-oriented instructions for [[Get The Source|getting the Qt source code]] and setting up your local working environment to build Qt.
Line 14: Line 14:


There are some steps you need to follow only once:
There are some steps you need to follow only once:
# [http://bugreports.qt.io Create an account] on the Qt Project bug tracker (Jira). This will be the same login information you will use in the [http://codereview.qt-project.org Gerrit code review system]. Even though the account credentials are shared, you still need to complete the account details on the [http://codereview.qt-project.org Gerrit code review system]. See the next step.
 
# Login on and set up [http://codereview.qt-project.org/#settings,contact your Gerrit account] by adding your full name, email address, and public SSH key.
#[https://login.qt.io/register Create a Qt account]. This login is used by both the [http://bugreports.qt.io JIRA bug tracker] and the [http://codereview.qt-project.org Gerrit code review system].
# Review and agree to the Qt Project's contribution agreement in Gerrit. You only need to do this once, unless the license changes. If your company has a corporate contribution agreement, ask the owner of the according Gerrit user group to add your account to this group.
#[[Setting up Gerrit#How to get started - Gerrit registration|Set up the Gerrit account]]. Even though the account credentials are shared, you still need to complete the account details in Gerrit.
# Clone Qt from [http://code.qt.io the read-only mirror].
#[[Building Qt 6 from Git|Get the Qt source code and make sure you can build it]].  
#* Qt 4: Add a git remote called "gerrit" in your cloned repository, which points to the Qt 4 project on <tt>codereview.qt-project.org</tt>.
#*When you run the <tt>init-repository</tt> script, provide your Gerrit username to the --codereview-username option. When you run configure specify [[Building_Qt_6_from_Git#Developer_Builds|-developer-build]].
#* Qt 5: When you run the <tt>init-repository</tt> script, provide your Gerrit username to the --codereview-user option.


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:
# Push you changes to remote "gerrit" to the branch <tt>refs/for/master</tt>, if <tt>master</tt> is the branch you are targeting.
 
# The [[Early Warning System]] (EWS) will quickly kick in and check your patch. Please act upon the reports and push updates to the patch.
#Make your change(s) to a local branch. Example:
# '''Add relevant reviewers to your change(s).''' If you don't do this, your change may go unnoticed. To find possible reviewers, you can:
##<tt>git checkout -b my-fix origin/dev</tt>
#* examine the Git history with 'git log' and/or 'git blame',
##... make changes ...
#* see the [[Maintainers|Maintainer chart]],
##<tt>git commit -a</tt>
#* ask on IRC, or
##*Each commit should have '''only''' one self-contained change. Modify existing commits by using the <tt>--amend</tt> switch when committing.
#* ask on relevant mailing lists like development@qt-project.org or qt-creator@qt-project.org, etc.
##*The [[Commit Policy]] contains relevant information.
# Wait for reviews, and actively partake in the review of your change(s).
#Push your change(s). There are two ways to do this (replace "dev" with the appropriate branch name):
#* If your contribution is deemed to not align with the project's vision or goals, you should abandon the change at this point.
#*via git push: <tt>git push gerrit HEAD:refs/for/dev</tt>
#* If your contribution is deemed unready, you need to fix it up according to the reviews.
#*via the git-gpush script (Git-gpush-scripts):  <tt>git gpush --branch dev</tt>
# 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.
#The [[Early Warning System]] (EWS) will quickly kick in and check your patch. Please act upon the reports and push updates to the patch.
#* To determine if the branch is covered by the CI system, you may check [http://testresults.qt.io/ci/ the CI logs] ; if the project/branch can be found at this link, it is covered by CI.
#'''Add relevant reviewers to your change(s).''' If you don't do this, your change may go unnoticed. To find possible reviewers, you can:
#* If the [[Public Autotest Infrastructure|continuous integration (CI)]] system rejects your patch, you need to fix the issues so it passes the project's build and autotest systems.
#*examine the Git history with 'git log' and/or 'git blame',
# When CI is successful, your changes are automatically included and added to the official Qt repository.
#*see the [[Maintainers|Maintainer chart]],
#*ask on [[Online Communities#IRC channels|IRC]], or
#*[https://lists.qt-project.org subscribe] and ask on relevant mailing lists like [mailto:development@qt-project.org development@qt-project.org] or [mailto:qt-creator@qt-project.org qt-creator@qt-project.org], etc.
#Wait for [[Review Policy|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. Note that [[Gerrit Introduction#Updating a Contribution With New Code|the process]] is very different from GitHub.
#Once approved, integrate your patch. Depending on the particular branch's and/or repository's configuration, you either ''stage'' the change for integration, or you directly ''submit'' it to the target branch.
#*Usually, you are responsible for the integration of your own changes. The reviewers will do that only in exceptional cases.
#*If the [[CI Overview|continuous integration (CI) system]] rejects your patch, you need to fix the issues so it passes the project's build and autotest systems.
#**The CI often fails for reasons unrelated to a particular patch. Make sure to re-stage the change when the integration log indicates such a case.
#When CI is successful, your changes are automatically included into the official Qt repository.


See [[Gerrit Caveats and Hints]] to avoid common traps.
See [[Gerrit Caveats and Hints]] to avoid common traps.


== Style, Conventions and Principles ==
See [[Building Qt 5 from Git]] for a full description of how to clone, configure and build Qt5 from git on different platforms. Though that page repeats a few topics mentioned on the current one, it focuses more on details around building Qt.
 
When you start an entirely new project or import an existing one from elsewhere, you need to [[Requesting New Repositories|request a new repository]].
 
===A Shortcut ...===
 
If you have only a minor contribution to make and find the process out of proportion for that, you may simply attach a patch to a [https://bugreports.qt.io bug report]. However, the more of the necessary steps you defer to the code's maintainers, the less likely is your contribution to be integrated in a timely manner.
 
==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 [http://techbase.kde.org/Policies/Library_Code_Policy 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.
For development of the Qt framework we follow the framework's [[Qt Coding Style]] and we stick to our established [[Coding Conventions]]. The [https://community.kde.org/Policies/Library_Code_Policy 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 [http://doc.qt.digia.com/qtcreator-extending/coding-style.html 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.
Qt Creator uses its own [https://doc-snapshots.qt.io/qtcreator-extending/coding-style.html 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]].
In addition, conventions for writing good user interface messages texts that play well with Qt Linguist can be found under [[UI Text Conventions]].
Line 49: Line 66:
Our [[API Design Principles]] aim for perfection.
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.
Note that Qt is an open source library, and must therefore 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]].
Please follow the [[Commit Policy]].
Line 55: Line 72:
Verify that your commits have correct author information, including your name and email address as it is registered in Gerrit.
Verify that your commits have correct author information, including your name and email address as it is registered in Gerrit.


== Localization to Other Languages ==
==Localization to Other Languages==


The process of contributing translations is described in [[Qt Localization]].
The process of contributing translations is described in [[Qt Localization]].


== Developer's Lounge ==
==Developer's Lounge==


If you have any questions about the development of Qt, feel free to join the <tt>#qt-labs</tt> IRC channel on <tt>irc.freenode.net</tt> and the [http://lists.qt.io/mailman/listinfo/development Qt development mailing list] Qt Creator development, join <tt>#qt-creator on irc.freenode.net</tt> and the [http://lists.qt.io/mailman/listinfo/qt-creator Qt Creator mailing list].
If you have any questions about the development of Qt, feel free to join the <tt>#qt-labs</tt> IRC channel on <tt>irc.libera.chat</tt> and the [http://lists.qt-project.org/mailman/listinfo/development Qt development mailing list]. For questions relating to Qt Creator development, join <tt>#qt-creator on irc.libera.chat</tt> and the [http://lists.qt-project.org/mailman/listinfo/qt-creator Qt Creator mailing list].


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

Latest revision as of 15:12, 17 August 2023


We have a community around the development of the Qt libraries, Qt related tools and add-ons called the Qt Project. 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.
  2. Set up the Gerrit account. Even though the account credentials are shared, you still need to complete the account details in Gerrit.
  3. Get the Qt source code and make sure you can build it.
    • When you run the init-repository script, provide your Gerrit username to the --codereview-username option. When you run configure specify -developer-build.

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

  1. Make your change(s) to a local branch. Example:
    1. git checkout -b my-fix origin/dev
    2. ... make changes ...
    3. git commit -a
      • Each commit should have only one self-contained change. Modify existing commits by using the --amend switch when committing.
      • The Commit Policy contains relevant information.
  2. Push your change(s). There are two ways to do this (replace "dev" with the appropriate branch name):
    • via git push: git push gerrit HEAD:refs/for/dev
    • via the git-gpush script (Git-gpush-scripts): git gpush --branch dev
  3. The Early Warning System (EWS) will quickly kick in and check your patch. Please act upon the reports and push updates to the patch.
  4. Add relevant reviewers to your change(s). If you don't do this, your change may go unnoticed. To find possible reviewers, you can:
  5. 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. Note that the process is very different from GitHub.
  6. Once approved, integrate your patch. Depending on the particular branch's and/or repository's configuration, you either stage the change for integration, or you directly submit it to the target branch.
    • Usually, you are responsible for the integration of your own changes. The reviewers will do that only in exceptional cases.
    • 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.
      • The CI often fails for reasons unrelated to a particular patch. Make sure to re-stage the change when the integration log indicates such a case.
  7. When CI is successful, your changes are automatically included into the official Qt repository.

See Gerrit Caveats and Hints to avoid common traps.

See Building Qt 5 from Git for a full description of how to clone, configure and build Qt5 from git on different platforms. Though that page repeats a few topics mentioned on the current one, it focuses more on details around building Qt.

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

A Shortcut ...

If you have only a minor contribution to make and find the process out of proportion for that, you may simply attach a patch to a bug report. However, the more of the necessary steps you defer to the code's maintainers, the less likely is your contribution to be integrated in a timely manner.

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 therefore 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.libera.chat and the Qt development mailing list. For questions relating to Qt Creator development, join #qt-creator on irc.libera.chat and the Qt Creator mailing list.

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