Note that you don't need to know all of the
CONTRIBUTING.md – it is there to
help you with things as you go, and make things easier, not harder.
Skim through it, and when you will be doing something that relevant section
will apply to, just go back to it and read in more detail about what is the
best course of action. You don't even need to memorize the section – after all,
it still will be there next time you might need it.
Provide version information (you can find version numbers in menu
Settings → About):
OS: qTox version: Commit hash: toxcore: Qt:
Provide steps to reproduce the problem, it will be easier to pinpoint the fault.
Screenshots! A screenshot is worth a thousand words. Just upload it. (How?)
Before you start contributing, first decide for a specific topic you want to work on. Pull requests, which are spanning multiple topics (e.g. "general qTox code cleanup") or introduce fundamental architectural changes are rare and require additional attention and maintenance. Please also read the following simple rules we need to keep qTox a "smooth experience" for everybody involved.
xxx fixupare not needed and rejected during review.
Fixes #4134.. Here is an example.
PR = Pull request
Ideally for simple PRs (most of them):
git commit --amend path/to/file)
masterbefore submitting the PR
For complex PRs (big refactoring, etc):
It's important to keep amount of changes in the PR small, since smaller PRs are
easier to review and merging them is quicker. PR diff shouldn't exceed
changed lines, unless it has to.
Open a Terminal and do the following steps: ```bash
git clone email@example.com:/qTox.git
git remote add upstream https://github.com/qTox/qTox.git
git branch master --set-upstream-to=upstream/master
You're now all set to create your first pull request! Hooray! :) Still in Terminal, do the following steps to actually create the pull request: ```bash # Fetch from the "upstream" repository: git fetch upstream master:master # Checkout a local branch on up-to-date "master" and give it a sane name, e.g.: git checkout -b feat/brandnew-feature master
Now do your changes and commit them by your heart's desire. When you think you're ready to push for the first time, do the following:
# Push to the new upstream branch and link it for synchronization git push -u origin feat/brandnew-feature # From now on, you can simply… git push # ...to your brand new pull request.
That's it! Happy contributing!
Usually you want to avoid conflicts and they should be rare. If conflicts appear anyway, they are usually easy enough to solve quickly and safely. However, if you find yourself in a situation with large amounts of merge conflicts, this is an indication that you're doing something wrong and you should change your strategy. Still… you probably don't want to throw away and lose all your valuable work. So don't worry, there's a way to get out of that mess. The basic idea is to divide the conflicts into smaller – easier to solve – chunks and probably several (topic) branches. Here's a little "Rule of Thumb" list to get out of it:
In addition it helps to regularly keep rebasing on the upstream repository's recent master branch. If you don't have the upstream remote in your repo, add it as described in How to open a pull request.
# If not on PR branch, check it out: git checkout my/pr-branch # Now fetch master ALWAYS from upstream repo git fetch upstream master:master # Last, rebase PR branch onto master… git rebase -i master # …and, if everything's clear, force push to YOUR repo (your "origin" Git remote) git push -f
git rebase <target_branch_name>, don't do
git pull. Then you can start fixing the conflicts. Here is a good explanation.
We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to generate the qTox change log using clog-cli.
Each commit message consists of a header and a body. The header has a special format that includes a type, a scope and a subject:
<type>(<scope>): <subject> <BLANK LINE> <body>
The header is mandatory and the body is optional. The scope of the header is also optional.
The header must be a short (72 characters or less) summary of the changes made.
Must be one of the following:
If the commit reverts a previous commit, it should begin with
followed by the header of the reverted commit. In the body it should say:
reverts commit <hash>., where the hash is the SHA of the commit being
The scope could be anything specifying place of the commit change. Note that "place" doesn't necessarily mean location in source code.
audio– change affects audio
video– change affects video
settings– change affects qTox settings
tray– change affects tray icon
l10n– translation update
i18n– something has been made translatable
build– change affects build system / scripts, e.g.
travis– change affects Travis CI
CONTRIBUTING– change to the contributing guidelines
Since people were abusing length of the scope, it's limited to 12 characters. If you're running into the limit, you're doing it wrong.
The subject contains succinct description of the change:
A properly formed git commit subject line should always be able to complete the following sentence:
If applied, this commit will your subject line here
Wrap the body at 72 characters whenever possible (for example, don't modify long links to follow this rule). Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.
The body contains (in order of appearance):
Include every section of the body that is relevant for your commit.
Breaking changes should start with the phrase
BREAKING CHANGE: with a
space or two newlines. The rest of the commit message is then used for this.
reviewable.io is being used to review changes that land in qTox.
How to review:
Reviewablebutton in pull request.
LGTMbutton in Reviewable.
Publishto make comments visible on GitHub.
When responding to review:
Reviewablebutton in pull request.
Publishbutton to make response visible on GitHub.
The easiest way is to use
test-pr.sh script to get PR merged on top of
master. E.g. to get pull request
That should create branches named
test1234 is what you
would want to test. If script fails to merge branch because of conflicts, fret
not, it doesn't need testing until PR author fixes merge conflicts. You might
want to leave a comment on the PR saying that it needs a rebase :smile:
As for testing itself, there's a nice entry on the wiki: https://github.com/qTox/qTox/wiki/Testing
Not a requirement, just a friendly tip. :wink:
It's nice when commits are being GPG-signed. Github has a few articles about configuring & signing.
And tl;dr version:
gpg --gen-key gpg --send-keys <your generated key ID> git config --global commit.gpgsign true
Windows' unbeaten beauty and clarity:
Symbols that should be forbidden for filenames under Windows: