2014/11/15 - Contributing to Qt
-
Upload
epics-qt-collaboration -
Category
Engineering
-
view
119 -
download
5
Transcript of 2014/11/15 - Contributing to Qt
![Page 1: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/1.jpg)
Contributing to Qt – hands on
James Turner
KDAB
![Page 2: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/2.jpg)
About me
● Giuseppe D'Angelo● Qt user since Qt 3● Joined KDAB in 2012● Qt Approver
● Ask me about Core, GUI, OpenGL...● “peppe” on the interwebs
![Page 3: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/3.jpg)
History
● Historically it has always been cumbersome (if not impossible) for 3rd parties to contribute to Qt
● No clear contribution model● No technical facilities for external contributors
![Page 4: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/4.jpg)
Qt Project
● In 2011 the Qt Project is born● A Governance Model is put in place to allow external contributions to drive Qt development
● Meritocratic● Inclusive● Fair● Transparent
![Page 5: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/5.jpg)
Benefits
● Drive Qt development toward one's needs● Richer, more stable releases● More opportunities for Qt experts● Overall: more broad Qt ecosystem
![Page 6: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/6.jpg)
Roles in the Qt Project
![Page 7: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/7.jpg)
Roles in the Qt Project
Ordinary users
![Page 8: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/8.jpg)
Roles in the Qt Project
Ordinary users
COOLCOOLGUYSGUYS
![Page 9: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/9.jpg)
Some numbers
● ~300 commits per week on average● ~60 of which (20%) not from Digia
![Page 10: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/10.jpg)
Some numbers: % of commits
![Page 11: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/11.jpg)
Some numbers: # commits
![Page 12: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/12.jpg)
Some numbers: # commits w/o Digia
![Page 13: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/13.jpg)
Let's begin
● One-time preliminary setup● Make a patch
![Page 14: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/14.jpg)
Setup
● Create a JIRA account bugreports.qt-project.org● Accept the CLA codereview.qt-project.org● Upload your SSH key
● Optionally: configure SSH for codereview.qt-project.org
![Page 15: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/15.jpg)
Contributor License Agreement
● Legal requirement to be able to push any code● The author retains copyright● Gives Digia authorization to relicense● Frees Qt Project / Digia from legal responsibilities● Different agreements available (for individuals or organizations)
![Page 16: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/16.jpg)
Almost there...
● Clone Qt from git
● either by cloning qt5.git and using the init-repository script● or just clone the modules you need. In this case, configure SSH / Gerrit as a remote
● Install the commit-hook● Build Qt
● Since we're modifying Qt, pass -developer-build
![Page 17: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/17.jpg)
Make a patch
● Which branch to pick?● Hack, hack, hack
● Coding style● Coding guidelines
● Commit● Push● Get feedback, improve, get it merged
![Page 18: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/18.jpg)
Which branch to pick?
● Qt now uses versioned branches● 5.3, 5.4, dev● When close to a release, 5.x.y created
● Target the closest branch (which is still open)● Bug fix against 5.3 series => 5.3● Destabilizing change => dev● New feature => dev
● Use common sense if in doubt (or ask)
![Page 19: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/19.jpg)
A word about Qt 4...
● No new features can go in Qt 4● Bug fixes can be applied to Qt 4 if and only if
● they don't apply to Qt 5, or● they do apply and they have already been fixed there
● Use the git-qt-cherry-pick script to ease the process
![Page 20: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/20.jpg)
Hack, hack, hack
● Let's make a patch!
![Page 21: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/21.jpg)
Coding style & guidelines
● They're extensively documented on the wiki● Long list of “dos and don'ts”
● Code style● API design● Commit messages● General rules about the project
● Again, privilege common sense
![Page 22: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/22.jpg)
Commit!
● It's git => it has no specific workflow● Easiest one: create a feature branch and commit in it
● git checkout -b featurebranch● # hack hack hack● git add file1 file2● git commit
● The commit-hook will automatically insert a Change-id below your commit message (leave it alone, it's for Gerrit)
![Page 23: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/23.jpg)
Push the patch for code review
git push gerrit HEAD:refs/for/targetbranch
![Page 24: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/24.jpg)
Getting the patch reviewed
![Page 25: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/25.jpg)
Getting the patch reviewed
● Find suitable people to review (and approve) the patch● git log, git blame● Add the maintainer(s) of the module● Ping people around on IRC / mailing list / JIRA
![Page 26: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/26.jpg)
Getting the patch reviewed
● Scoring system used● +2 “approved”● +1 “ok for me, but someone else must approve”● 0 ● -1 “not ok as-is, but if you improve it I'll accept it”● -2 “totally disagree with the feature or the given implementation”
● Scores don't sum up
![Page 27: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/27.jpg)
Oh no! Someone -1'd my patch
● Don't worry! Happens all the time● Extremely likely the same people also left comments about what to improve (and how to do it)
● E.g. “style violation” => read the style guide● “what happens if someone does this-and-that...”● “missing docs”
![Page 28: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/28.jpg)
Improve the patch
● Learn from the feedback ● Don't be afraid to ask for more information!
● Go back to the code● Fix the issues● Amend the commit and repush it
● git add file1 file2● git commit --amend● git push gerrit HEAD:refs/for/targetbranch
● Do not create a new commit
![Page 29: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/29.jpg)
Docs, tests
● Docs are mandatory for any new feature● Tests are almost mandatory for any new feature or bugfix
● Exceptions to be made on a case-by-case● Qt uses QTestLib for its own tests
● Each module has tests in tests/auto/module/subdir/class
![Page 30: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/30.jpg)
My patch got approved! What now?
● Press the “Stage” button on Gerrit and cross your fingers● Staging isn't automatic● Prevents problems in case of series of patches with dependencies
● The patch is now in the hands of the CI system
![Page 31: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/31.jpg)
Continuous Integration
● All patches landing in Qt must pass CI● They must build on all CI configurations (currently ~30)● On several of them, all the enforced tests must all pass
● Unfortunately a bunch of staged patches are tested all together● If any of them causes a failure, all of them will not pass● If you're positive your patch didn't cause the failure, stage again● Otherwise, fix the code and push again
![Page 32: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/32.jpg)
Success!
● The patch got merged
![Page 33: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/33.jpg)
Too complicated?
● If you suspect you have found a bug in Qt...● And you don't want to investigate how to fix it...● And you don't want to go through the whole contribution process...
![Page 34: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/34.jpg)
Got a Qt bug?
KDAB can fix it for you
fixmyqtbug.comfixmyqtbug.com
![Page 35: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/35.jpg)
Thank you!
● Other useful resources: ● qt-project.org/contribute
● includes all these instructions, guides, troubleshooting...● development mailing list● #qt-labs @ irc.freenode.net
![Page 36: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/36.jpg)
Questions?
![Page 37: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/37.jpg)
Thank you!
● Other useful resources: ● qt-project.org wiki
● includes all these instructions, guides, troubleshooting...● development mailing list● #qt-labs @ irc.freenode.org
![Page 38: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/38.jpg)
Thank you!
![Page 39: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/39.jpg)
How to contribute to QtHow to contribute to Qt
![Page 40: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/40.jpg)
About me
● Giuseppe D'Angelo● Qt user since Qt 3● Joined KDAB in 2012● Qt Approver
● Ask me about Core, GUI, OpenGL...● “peppe” on the interwebs
![Page 41: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/41.jpg)
How to contribute to Qt in 5 minutes (or less)
qt-project.org/contribute
Google => “contributing to Qt” => I feel lucky
![Page 42: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/42.jpg)
How to contribute to Qt in 7 steps
● Create an account on JIRA● Accept the CLA and upload your SSH key on Gerrit● Clone Qt from git
● Hack, hack, hack● Commit the result and push it to Gerrit● Get it approved● Click “Stage” and let your patch get merged
![Page 43: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/43.jpg)
● That's it!● You're now a Qt contributor
![Page 44: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/44.jpg)
Thank you!
![Page 45: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/45.jpg)
Some numbers: % of commits
![Page 46: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/46.jpg)
Some numbers: # of commits
![Page 47: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/47.jpg)
Some numbers: # commits w/o Digia
![Page 48: 2014/11/15 - Contributing to Qt](https://reader034.fdocuments.us/reader034/viewer/2022042816/5594ae841a28ab984b8b45a9/html5/thumbnails/48.jpg)
Some numbers
● ~300 commits per week on average● ~60 of which (20%) not from Digia