Qt for Python/Development Getting Started: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(note that section might be outdate)
 
(22 intermediate revisions by 5 users not shown)
Line 1: Line 1:
[[Category:Qt for Python]]


[[Category:PySide]]
== Overview ==
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 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 [http://wiki.qt.io/Main_Page Qt Project Wiki].


= Getting Started with PySide Development =
=== Branch status ===


If you're new to PySide Development, this page is for you! This page is intended to help you get setup and running as a new developer.
* 5.15: Bug-fixing only (Commercial LTS, last OSS was 5.15.2)
* 6.5: Cherry-pick mode, Bug fixing only
* dev: Current development


== Overview ==
== 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.


The PySide project is supported by the developers who use PySide. This means that anyone who shares an interest in PySide can join the community, participate in its decision making processes, and contribute to PySide development. This page will summarize the key points around how you contribute to PySide, but since PySide follows the same development process as the Qt project, it's in your best interest to read the [http://wiki.qt.io/Main_Page Qt Project Wiki]. For simplicity purposes, much of that wiki page will be summarized here so you can get started faster.
== Contributing Patches ==


== Reporting Bugs ==
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.
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]].


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. Since PySide is developer supported, bugs get fixed when developers contribute fixes for them.
The [http://account.qt.io Qt Account] can be used for the bug tracker ''JIRA'' and ''Gerrit'' with some configuration:


== Getting and Building the Source ==
* Verify the '''JIRA account'''
** Go to [https://bugreports.qt.io bugreports.qt.io] and try to log in, potentially fill out more details
* Configure the '''Gerrit account'''
** Go to [https://codereview.qt-project.org 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'''


PySide is split into two packages: Shiboken and PySide. Shiboken is a code generator that is used to generate the C++ code needed by PySide to wrap Qt classes. Shiboken can also be used to wrap other C++ classes. The repositories for both Shiboken and PySide are located on gitorious.org:
=== Configuring local directories for Gerrit ===


* Shiboken: http://code.qt.io/cgit/pyside/shiboken.git/tree/
After cloning the project's repository:
* PySide: http://code.qt.io/cgit/pyside/pyside.git/tree/
* PySide2: http://code.qt.io/cgit/pyside/pyside-setup.git/tree/


Instructions on building are available for [[Building_PySide_on_Linux | Linux]], [[Building_PySide_on_Windows | Windows]], and [[Building_PySide_on_Mac_OS_X | OS X]]. You'll almost certainly want to use a debug build during development.
git clone --recursive https://codereview.qt-project.org/pyside/pyside-setup pyside


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


This section might be partly outdated because it was written for PySide 1. See [[Qt Contribution Guidelines]].
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:


Because PySide is a Qt project, all patches must be submitted through Qt's Gerrit code integration system at https://codereview.qt.io 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.
git remote add gerrit ssh://codereview.qt-project.org/pyside/pyside-setup


A bug tracker (JIRA) account is needed before a Gerrit account can be created:
=== Commits ===


* '''JIRA account'''
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".
*# Go to [https://bugreports.qt.io bugreports.qt.io] and click on '''Sign Up'''
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
*# Fill out the details
and it will merge the change into 6.2 branch (pushing to dev).
* '''Gerrit account'''
*# 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
*#* '''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 ===


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:
<syntaxhighlight>
Fix X problem


<code>
Here we add an explanation of the problem and
$ git remote add gerrit ssh://codereview.qt.io/pyside/<project>
the solution
</code>


where <project> is either pyside or shiboken.
Pick-to: 6.2
Fixes: PYSIDE-99999
</syntaxhighlight>


=== Pushing changes to Gerrit ===
=== Pushing changes to Gerrit ===
Line 58: Line 72:
After you have committed your changes locally, you can push them to Gerrit like this:
After you have committed your changes locally, you can push them to Gerrit like this:


<code>
  git push gerrit HEAD:refs/for/<branch>
  $ git push gerrit HEAD:refs/for/master
 
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
(<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.