Qt for Python/Development Getting Started: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
(12 intermediate revisions by 3 users not shown)
Line 2: Line 2:


== Overview ==
== Overview ==
The Qt for Python (PySide2) project is supported by [https://qt.io The Qt Company] and the developers who use Qt for Python.
The Qt for Python (PySide) project is supported by [https://qt.io The Qt Company] and the developers who use Qt for Python.
This means that anyone who shares an interest in the project can join the community, participate in its decision making processes, and contribute to its development.
This means that anyone who shares an interest in the project can join the community, participate in its decision making processes, and contribute to its development.
This page will summarize the key points around how you can contribute to the project.
This page will summarize the key points around how you can contribute to the project.
Line 9: Line 9:
=== Branch status ===
=== Branch status ===


* 5.12: Cherry-pick mode
* 5.15: Bug-fixing only (Commercial LTS, last OSS was 5.15.2)
* 5.13: Bug-fixing only
* 6.5: Cherry-pick mode, Bug fixing only
* 5.14: Bug-fixing only
* dev: Current development
* 5.15: Open Development
* dev: refer to 5.15


== Reporting Bugs ==
== Reporting Bugs ==
Line 20: Line 18:
== Contributing Patches ==
== Contributing Patches ==


Because PySide2 is a Qt project, all patches must be submitted through [https://codereview.qt.io Qt's Gerrit code integration system].
Because PySide is a Qt project, contributors need a [http://account.qt.io Qt Account] and need to agree to the ''Qt Contributor Agreement''
(see [[Qt_Contribution_Guidelines | Qt Contribution Guidelines]] ). All patches must be submitted
through [https://codereview.qt-project.org/ Qt's Gerrit code review and integration system].
Make sure you go through [https://wiki.qt.io/Gerrit_Introduction Gerrit's introduction page] before starting contributing.
Make sure you go through [https://wiki.qt.io/Gerrit_Introduction Gerrit's introduction page] before starting contributing.
All developers need a user account on Gerrit and to agree to the Qt Contributor Agreement. Patches submitted via the bug tracked, mailing list, or pull requests cannot be accepted.
Patches submitted via the bug tracker, mailing list, or pull requests cannot be accepted (unless they are trivial, less than 10 lines).
We also recommend to have a look at the [[Commit_Policy | CommitPolicy]], the [[Qt_Coding_Style | Coding Style]]
and the [[Coding_Conventions | Coding Conventions]].


A bug tracker (JIRA) account is needed before a Gerrit account can be created:
The [http://account.qt.io Qt Account] can be used for the bug tracker ''JIRA'' and ''Gerrit'' with some configuration:


* '''JIRA account'''
* Verify the '''JIRA account'''
** Go to [https://bugreports.qt.io bugreports.qt.io] and click on '''Sign Up'''
** Go to [https://bugreports.qt.io bugreports.qt.io] and try to log in, potentially fill out more details
** Fill out the details
* Configure the '''Gerrit account'''
* '''Gerrit account'''
** Go to [https://codereview.qt-project.org codereview.qt-project.org] and click on '''Sign In'''
** Go to [https://codereview.qt-project.org codereview.qt-project.org] and click on '''Sign In'''
** Login with the username/password you created with JIRA
** Login with the username/password of the ''Qt Account''
*** '''NOTE:''' Gerrit usernames are case-sensitive, but JIRA usernames are not. If you attempt to log into Gerrit with different capitalizations, you will end up with multiple accounts.
*** '''NOTE:''' Gerrit usernames are case-sensitive, but JIRA usernames are not. If you attempt to log into Gerrit with different capitalizations, you will end up with multiple accounts.
** Enter your '''full name''' and click '''Save Changes'''
** Enter your '''full name''' and click '''Save Changes'''
Line 45: Line 46:


be sure you are on the desired branch you want to contribute.
be sure you are on the desired branch you want to contribute.
Most of the work is being done under '''5.15''', but you can submit patches to 5.14 and dev
branches.


Please follow the [[Setting-up-Gerrit | Qt Setting up Gerrit]] instructions, particularly the Local Setup and Configuring Git sections. Add a gerrit remote to local project directory with:
Please follow the [[Setting-up-Gerrit | Qt Setting up Gerrit]] instructions, particularly the Local Setup and Configuring Git sections. Add a gerrit remote to local project directory with:


  git remote add gerrit ssh://codereview.qt-project.org/pyside/pyside-setup
  git remote add gerrit ssh://codereview.qt-project.org/pyside/pyside-setup
=== Commits ===
If you are fixing an issue or adding a feature, remember to include a reference in at the end of the message if your patch "Fixes" something or it's related to a "Task-number".
Additionally, don't forget to add the "Pick-to: 6.2" at minimum to get the contribution in the next PySide6 release. The following commit message fixes the issue PYSIDE-99999
and it will merge the change into 6.2 branch (pushing to dev).
<syntaxhighlight>
Fix X problem
Here we add an explanation of the problem and
the solution
Pick-to: 6.2
Fixes: PYSIDE-99999
</syntaxhighlight>


=== Pushing changes to Gerrit ===
=== Pushing changes to Gerrit ===
Line 59: Line 75:


where '''<branch>''' is the branch you were working at the moment of doing changes in the code.
where '''<branch>''' is the branch you were working at the moment of doing changes in the code.
'''Important:''' in most cases you should only use '''dev'''


'''Don't forget''' to '''Add Reviewers'''
'''Don't forget''' to '''Add Reviewers'''
You can click on the left menu of your patch the option "Add Reviewers" and add the word "pyside2", that will include the developers of the project so they can look at it.
You can click on the left menu of your patch the option "Add Reviewers" and add the word "pyside", that will include the developers of the project so they can look at it.
If you want to add someone directly, ask in the many chat platform the project has who to add for a specific path.
If you want to add someone directly, ask in the many chat platform the project has who to add for a specific path.
=== Files location ===
This cases assumed you already entered the '''pyside-setup''' git directory:
* If you are fixing a bug, it's probable that you already now the location for the typesystem
(<span style="font-family: monospace;background-color: #cecfd5;display: inline; border-radius: 4px;padding: 3px;">sources/pyside6/PySide6/<QtModule>/typesystem_<name>.xml</span>), and glue code (<span style="font-family: monospace;background-color: #cecfd5;display: inline; border-radius: 4px;padding: 3px;">sources/pyside6/PySide6/glue</span>), so your contribution should probably be there.
* Issues related to the build process would be probably located inside the scripts directory called <span style="font-family: monospace;background-color: #cecfd5;display: inline; border-radius: 4px;padding: 3px;">build_scripts/</span>
* If you want to add a new example, please place them in the <span style="font-family: monospace;background-color: #cecfd5;display: inline; border-radius: 4px;padding: 3px;">examples/</span> directory.
* To update the documentation (not the API pages), adding written tutorials, changing typos, or details from the general, you should look into <span style="font-family: monospace;background-color: #cecfd5;display: inline; border-radius: 4px;padding: 3px;">sources/pyside6/doc</span> for PySide, and <span style="font-family: monospace;background-color: #cecfd5;display: inline; border-radius: 4px;padding: 3px;">sources/shiboken2/doc</span> for the Shiboken one. We use Sphinx for the docs, so please read https://doc.qt.io/qtforpython/gettingstarted.html#building-the-documentation carefully.
* Modifying the API pages from the documentation is a bit more tricky:
** We use <span style="font-family: monospace;background-color: #cecfd5;display: inline; border-radius: 4px;padding: 3px;">qdoc</span> to generate WebXML files that we later modify and use.
** The code snippets you see time to time in C++ comes from Qt. What we need to do is to copy those files from Qt/C++ and edit them locally. You can check many of them in <span style="font-family: monospace;background-color: #cecfd5;display: inline; border-radius: 4px;padding: 3px;">sources/pyside6/doc/codesnippets</span>. If the specific class you want to modify is there, it's just a matter of modifying the file and submit a patch, otherwise, you would need to look for the specific snippet file in Qt/C++'s repositories and copy it over, then translate it.
Check the Qt Release wiki pages, e.g.: https://wiki.qt.io/Qt_6.2_Release to see if a certain branch is still in development for features, otherwise you can ask in the different chat services the team has.

Latest revision as of 22:03, 12 April 2023


Overview

The Qt for Python (PySide) project is supported by The Qt Company and the developers who use Qt for Python. This means that anyone who shares an interest in the project can join the community, participate in its decision making processes, and contribute to its development. This page will summarize the key points around how you can contribute to the project. Qt for Python follows the same development process as the Qt project, it's in your best interest to read the Qt Project Wiki.

Branch status

  • 5.15: Bug-fixing only (Commercial LTS, last OSS was 5.15.2)
  • 6.5: Cherry-pick mode, Bug fixing only
  • dev: Current development

Reporting Bugs

Bugs should be reported to the Qt bug tracker at https://bugreports.qt.io/browse/PYSIDE Please include details on how to reproduce your problem and consider contributing a fix for it.

Contributing Patches

Because PySide is a Qt project, contributors need a Qt Account and need to agree to the Qt Contributor Agreement (see Qt Contribution Guidelines ). All patches must be submitted through Qt's Gerrit code review and integration system. Make sure you go through Gerrit's introduction page before starting contributing. Patches submitted via the bug tracker, mailing list, or pull requests cannot be accepted (unless they are trivial, less than 10 lines). We also recommend to have a look at the CommitPolicy, the Coding Style and the Coding Conventions.

The Qt Account can be used for the bug tracker JIRA and Gerrit with some configuration:

  • Verify the JIRA account
  • Configure the Gerrit account
    • Go to codereview.qt-project.org and click on Sign In
    • Login with the username/password of the Qt Account
      • NOTE: Gerrit usernames are case-sensitive, but JIRA usernames are not. If you attempt to log into Gerrit with different capitalizations, you will end up with multiple accounts.
    • Enter your full name and click Save Changes
    • Skip the SSH part for now and scroll all the way down and click "New Contributor Agreement"
      • Select Individual or Corporate, then scroll down and type I AGREE then submit
      • To check if your agreement was submitted, click on Settings then Agreements

Configuring local directories for Gerrit

After cloning the project's repository:

git clone --recursive https://codereview.qt-project.org/pyside/pyside-setup pyside

be sure you are on the desired branch you want to contribute.

Please follow the Qt Setting up Gerrit instructions, particularly the Local Setup and Configuring Git sections. Add a gerrit remote to local project directory with:

git remote add gerrit ssh://codereview.qt-project.org/pyside/pyside-setup

Commits

If you are fixing an issue or adding a feature, remember to include a reference in at the end of the message if your patch "Fixes" something or it's related to a "Task-number". Additionally, don't forget to add the "Pick-to: 6.2" at minimum to get the contribution in the next PySide6 release. The following commit message fixes the issue PYSIDE-99999 and it will merge the change into 6.2 branch (pushing to dev).


Fix X problem

Here we add an explanation of the problem and
the solution

Pick-to: 6.2
Fixes: PYSIDE-99999

Pushing changes to Gerrit

After you have committed your changes locally, you can push them to Gerrit like this:

git push gerrit HEAD:refs/for/<branch>

where <branch> is the branch you were working at the moment of doing changes in the code.

Important: in most cases you should only use dev

Don't forget to Add Reviewers You can click on the left menu of your patch the option "Add Reviewers" and add the word "pyside", that will include the developers of the project so they can look at it. If you want to add someone directly, ask in the many chat platform the project has who to add for a specific path.

Files location

This cases assumed you already entered the pyside-setup git directory:

  • If you are fixing a bug, it's probable that you already now the location for the typesystem

(sources/pyside6/PySide6/<QtModule>/typesystem_<name>.xml), and glue code (sources/pyside6/PySide6/glue), so your contribution should probably be there.

  • Issues related to the build process would be probably located inside the scripts directory called build_scripts/
  • If you want to add a new example, please place them in the examples/ directory.
  • To update the documentation (not the API pages), adding written tutorials, changing typos, or details from the general, you should look into sources/pyside6/doc for PySide, and sources/shiboken2/doc for the Shiboken one. We use Sphinx for the docs, so please read https://doc.qt.io/qtforpython/gettingstarted.html#building-the-documentation carefully.
  • Modifying the API pages from the documentation is a bit more tricky:
    • We use qdoc to generate WebXML files that we later modify and use.
    • The code snippets you see time to time in C++ comes from Qt. What we need to do is to copy those files from Qt/C++ and edit them locally. You can check many of them in sources/pyside6/doc/codesnippets. If the specific class you want to modify is there, it's just a matter of modifying the file and submit a patch, otherwise, you would need to look for the specific snippet file in Qt/C++'s repositories and copy it over, then translate it.

Check the Qt Release wiki pages, e.g.: https://wiki.qt.io/Qt_6.2_Release to see if a certain branch is still in development for features, otherwise you can ask in the different chat services the team has.