Revision as of 13:02, 12 October 2020

KDE uses a GitLab instance at https://invent.kde.org for code review (as well as hosting and other important collaboration tasks). This page is intended to serve as a general-purpose introduction to the most important aspects: submitting and reviewing Merge Requests.

Information

The KDE community does not generally use GitLab for bug reporting. Please continue to submit bug reports on https://bugs.kde.org. Task management is transitioning to Invent/GitLab but most projects still use https://phabricator.kde.org for now.

Workflow

The sanest and easiest way to submit code to KDE is by following a typical feature branch workflow: keep your master branch synchronized with the origin repository, and make all changes on separate branches. Each Merge Request needs its own private, temporary branch. Once your Merge Request has been merged, delete the feature branch, and make another new branch for the next Merge Request. In this way, you can be working on multiple changes at once without them colliding with one another because each one lives on its own branch.

Logging in

Navigate to https://invent.kde.org/users/sign_in and log in using the username and password for your KDE Identity account. If you don't have one, you can sign up for one here.

Setting up git

You will need to set up git to use you account details to help identify your work:

git config user.name <Your Real Name>
git config user.email <Your identity.kde.org email>

(You can set it up globally with --global)

Submitting a merge request

Contributing to KDE code using GitLab involves submitting a Merge Request. A Merge Request is a request to merge some of your code into the project's permanent source code repo. Here's how:

Build the project from source and make your change

First you need to check out the project, compile it from source, and make some changes that you would like to submit to KDE! Instructions for doing this can be found at Get Involved/development. You will wind up with a checkout of the project at ~/kde/src/[the project name] with some local changes applied to it.

Information

If you prefer a different organizational structure for source code on your machine, you can of course check out the local copy of your KDE repos wherever you want. However for the purposes of this documentation, we will assume that they are located inside ~/kde/src/

Fork the project

Note

If you have commit access, you can prefix your branches with "work/" and push them directly to origin without having to fork, and safely ignore this section.

Once you have made some local changes that you would like to submit to KDE, you need to create a personal fork of the project and push your changes to the forked copy.

Navigate to https://invent.kde.org/kde and locate the project. If it is not visible in the list, you can use the search field. Once you find the project, click on it:

On the project's page, click on the "Fork" button in the top-right corner of the screen:

This will take you to a page asking you what namespace you want to create the project under. Click on yourself:

After a moment, the system will finish creating the fork and take you to the page for your fork. On that page, click on the blue "Clone" button in the top-right corner:

In the pop-up that appears, click on the "copy" button to the right of the upper text field. This will copy the URL for the fork onto your clipboard.

Add the fork to your source checkout

Next, open your terminal app and navigate to the location where the project's repo lives (i.e. ~/kde/src/[the project name]).

You need to add your fork as a remote to the existing repo:

git remote add fork [the URL you copied to your clipboard]

Run git remote -v. You should see something like this:

$ git remote -v
fork [email protected]:ngraham/kid3.git (fetch)
fork [email protected]:ngraham/kid3.git (push)
origin https://invent.kde.org/kde/kid3.git (fetch)
origin https://invent.kde.org/kde/kid3.git (push)

This means you have two remotes set up for your repo: "origin" points to the original repo, and "fork" points to your fork of it.

Make a branch and commit

Now that you have your fork set up, it's time to create a branch to track your work and make a commit.

git checkout -b my_awesome_feature
git add [the files you changed]
git commit

Note

If you have commit access and are pushing a branch directly to origin, remember to prefix your branch with "work/". Branches with this prefix can be force-pushed to, and keywords like BUG: are not evaluated

Write a good commit message

With Gitlab, once a merge request is merged, the first commit in the merge request will wind up in the Git history, so it is very important that the first commit in the merge request be formatted properly.

Please follow commit message best practices: write a descriptive title in the form of an imperative sentence (e.g. "Fix button disappearing when view is changed") and on the next line, write at least one sentence describing your change and why it is necessary, adding more details if necessary.

If your patch is intended to fix a Bugzilla ticket, include the following on its own line:

BUG: 385942

(The number should be just the Bugzilla ticket number, not the full URL)

For example a commit message might read:

Close memory leak in GC

The GC was doing a bad job and leaking memory. Explicitly call delete where necessary.

BUG: 385942

Here is more information about other special messages that interact with Bugzilla tickets.

Note

These keywords will only work if the email address in your ~/.config/git/config file matches the email address used for your https://bugs.kde.org account (See this page for more information).

Note

If a merge request has only a single commit in it, then this commit will be added to the immutable git history with no opportunity to change it from the web interface before merging. This is different from Phabricator, in which the patch's title and summary are transformed into a commit message, overwriting the underlying commit message itself. So it is very important to format your commit message well. The web interface can only be used to rewrite a commit message when a merge request has at least two commits, and they are squashed when merging, and the person doing the merging writes a new commit message in the process of squashing.

Push to your fork

At this point you have a branch in your local repo called "my_awesome_feature" (Hopefully in reality it is named something a bit more appropriate!) that has a commit on it with your work. Now push it to your fork:

git push fork my_awesome_feature

This will produce a message somewhat like this:

$ git push fork my_awesome_feature
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 4 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 303 bytes | 303.00 KiB/s, done.
Total 3 (delta 2), reused 0 (delta 0)
remote: This commit is available for viewing at:
remote: https://invent.kde.org/ngraham/kid3/commit/23a702439f494806cf3cfe14f212df58a0075bba
remote: 
remote: To create a merge request for my_awesome_feature, visit:
remote:   https://invent.kde.org/ngraham/kid3/merge_requests/new?merge_request%5Bsource_branch%5D=my_awesome_feature
remote: 
To invent.kde.org:ngraham/kid3.git
 * [new branch]        my_awesome_feature -> my_awesome_feature

Create the Merge Request

Notice the "To create a merge request for my_awesome_feature..." message in the output of the push command (explained in the previous section). You can copy-and-paste the URL shown below it into a web browser. On some terminal apps, such as Konsole and Yakuake, you can ctrl+click on the link to go right there!

You will be taken to a web page that looks like this:

In the Description section, write at least one sentence describing your change and why it is necessary, adding more details if needed. For Merge Requests that change something about the appearance or user interface, it's customary to include a screenshot of how the interface looks after your change has been applied. Bonus points for including a "Before" image too, so reviewers can easily compare them.

If your patch is intended to fix a Bugzilla ticket, include the ticket number at the bottom of the description as follows:

BUG: 385942

As soon as the Merge Request is created, the Bugzilla ticket is notified that a relevant Merge Request has been started.

Note

The BUG: keyword must be added both in the Merge Request description, to notify the bug ticket of the Merge Request creation, and in the message of the first commit (as explained in Infrastructure/GitLab#Write_a_good_commit_message), to close the bug ticket once the Merge Request is merged.

In the section below, check all the checkboxes:

Once you're done with that, click the "Submit Merge Request" button!

What happens next?

After you've submitted your Merge Request, KDE developers who work with the software in question will review it and provide feedback. This can often take a few days. However, if nobody has responded after a week, it's likely that the review was overlooked (sorry about that!) and it's appropriate to make a comment saying, "Ping!" or something to that effect.

Once the Merge Request is accepted, KDE Developers will merge it for you!

Making changes to a Merge Request

Oftentimes, reviewers will request changes before the Merge Request can be merged. To accomplish this, you make the requested changes locally, then create a new commit including your changes. First, stage all changed files:

git add -u

Now make a new commit with the staged files:

git commit

Then push the local branch with the new commit on it up to the remote branch:

git push fork

Rebasing a Merge Request

When other changes have been made to the project's source code repo since you submitted your merge request, you will need to rebase the Merge Request to incorporate those changes. Here's how you do so:

# First, make sure you are on the branch for your merge request
git fetch
git pull --rebase origin master

At this point, there may be merge conflicts. If there are, git will tell you which files have conflicts. Open each file and resolve the conflict by exiting the contents to keep only the appropriate change. Then run git add [file path] on each conflicted file once all the conflicts have been resolved.

Now, you need to overwrite the version of the Merge Request on your remote branch with the version on your local branch. To do this, you have to force-push:

git push --force fork

Testing someone else's Merge Request

First you'll need a development environment set up. If you haven't done that yet, it's time to do so. Follow the instructions on Get_Involved/development#Set_up_your_development_environment. It is also advisable to set up the git mr tool, which makes testing Merge Requests a breeze. Here's how to install it, depending on your operating system:

Arch / Manjaro

yay -S git-mr

Debian/Ubuntu/KDE Neon

sudo apt install git-extras

Fedora

sudo dnf install git-extras

OpenSUSE

sudo zypper install git-mr

Check out the Merge Request and compile the software

First check out or enter the source repository for the software that's being patched. For example, let's say you want to test a Merge Request for Okular. If you've never built it before, check it out and build it once first:

kdesrc-build okular

Now go to its source directory:

cd ~/kde/src/okular

Find the Merge Request's ID. For example, for https://invent.kde.org/kde/okular/merge_requests/80, the ID is 80.

...and apply the Merge Request:

git mr 80

Now it's time to compile and run the software to make sure that the Merge Request does what it says it does and doesn't cause any regressions! Compile the patched source code:

kdesrc-build okular --no-src --resume-from okular

Those arguments will tell kdesrc-build to not update the source code and to not build any dependencies.

If it didn't compile, that's reason alone to reject the Merge Request! Go to the web page for the Merge Request and report your findings.

Perform QA

If it did compile, then it's time to perform QA, because it's important to thoroughly test Merge Requests to ensure that bad code and regressions don't slip in. This is the entire purpose of having a review infrastructure; it is very important.

First make sure the unit tests all pass:

cd ~kde/build/kde/applications/okular
ctest

If any tests fail, report this through a comment on the Merge Request's web page.

Does everything all still work for you? If not, return to the web page and request changes, writing a detailed comment explaining what didn't work. It is permissible to do this even if you have not been specified as a reviewer! Anyone can reject a Merge Request on the grounds that it does not work, does not do what it says it does, or causes regressions.

Next, try to break the Merge Request. Here are some ideas:

Remove the program's configuration file (~/.config/<program name>rc ) and re-open it
Try the program with a HiDPI scale factor (or without one) or with a different default font size
If it's a new feature, feed it unexpected input
Test related functionality

A good Merge Request will handle corner cases and variations in configuration. The price of configurability is vigilant testing! We owe it to our users to test using many configurations, not just the defaults or our personal settings.

Perform code review

Note

Need a section on code review here, preferably written by a core KDE developer or another very experienced developer

Engage with the author and other reviewers

After you have run the program and evaluated the Merge Request, it's time to leave some review comments on the webpage. If you have been specified as a reviewer, or are a member of a group that has been specified as a reviewer, it is permissible to Accept the Merge Request. But keep in mind that reviewing involves responsibility: you are giving a thumbs-up to code that will be run potentially by millions of people. If you accept and land a Merge Request that causes regressions, you will be expected to help fix it if the original author cannot or has disappeared. It's important to take the reviewer role seriously.

Advanced topics

Using work branches instead of forks

If you have a developer account, you don't need to use forks to submit merge requests. Instead, you can make sure your branch names begin with "work/" and push them straight to the main repo. These branches can be force-pushed to as if they were forks. By convention, it is recommended to add your KDE username to the branch, so the final name would end up looking like "work/ngraham/my-awesome-feature."

Curating your merge request commit history

The squash-based workflow assumes that the commit history in your merge request is not important to preserve and it is okay to combine all of the commits into one when the merge request is merged. This is the case when the merge request has lots of tiny commits in it with messages like "Fix this thing" and "Respond to review comments" and "Apply 1 suggestion".

However there are cases where you want to curate the history of your merge request and keep the commits exactly as they are when merging. For example, perhaps you are working on a large feature that consists of multiple logically separable components that nonetheless all live in the same source repo, or perhaps you are first doing some code refactoring, then you add a backend feature, then finally you add a front-end user interface for it.

For this workflow, you should make a separate commit in your branch for each logically separable part of the proposed changes. Then do not check the "squash commits" checkbox when submitting a merge request, and specifically mention in the merge request description that you would like reviewers to review individual commits separately and not squash when merging.

If you need to later make changes, do not add new commits; instead, combine the new changes with one of the existing commits using git's interactive rebasing feature. To learn how to do this, see https://git-rebase.io/

Switching the target branch of a Merge Request

Sometimes you will submit a merge request that is targeting the master branch, but will later be asked to target the stable branch instead because it is a bugfix. Or perhaps you have targeted the stable branch but the commit is considered too invasive and you are asked to target the master branch instead. In either of these circumstances, you will need to re-target your Merge Request. Here's how:

git checkout [the local branch for your merge request]
git fetch
git rebase -i origin/[the name of the remote branch you want to target; for example release/19.12]

This will open a text editor showing a list of commits, each on a separate line. Delete all of the lines of text except for the ones corresponding to new commits you have added as part of your merge request. Next, fix any merge conflicts if there are any.

Then force-push the branch up to gitlab again:

git push --force fork

Finally, edit the merge request by clicking the "Edit" button in the top-right corner of the page and choose the desired different target branch:

Note that after merging a Merge Request to the stable branch, you are expected to merge that branch back to master afterwards:

git checkout release/19.12
git pull
git checkout master
git pull
git merge -s recursive -Xours release/19.12
git push

Warning

If at any time you feel nervous or run into trouble, ask your reviewers for help. This can be tricky, and undoing bad merges is a pain in the neck.

Pushing commits to somebody else's fork

Sometimes someone will say "hey let's work on my branch together." So you will be pushing commits not to origin, and not to your fork, but to someone else's fork. Let's say you want to work on joliveira's "gsoc2019_numberFormat" branch.

First you would need to add the URL for his fork as a remote:

$ cd ~/kde/src/okular
$ git remote add joliveira_fork [email protected]:joliveira/okular.git
$ git remote -v
aacid_fork [email protected]:aacid/okular.git (fetch)
aacid_fork [email protected]:aacid/okular.git (push)
joliveira_fork [email protected]:joliveira/okular.git (fetch)
joliveira_fork [email protected]:joliveira/okular.git (push)
origin https://invent.kde.org/kde/okular.git (fetch)
origin https://invent.kde.org/kde/okular.git (push)

Notice how there are now multiple forks set up as remotes.

Next, you need to fetch all the repo metadata from the new remote:

git fetch joliveira_fork

This will download the list of branches. The next step is to switch to the one you want to collaborate on:

git checkout --track joliveira_fork/gsoc2019_numberFormat

This will create a local branch named "gsoc2019_numberFormat" from the contents of the remote branch joliveira_fork/gsoc2019_numberFormat and that also "tracks" it. This means that if someone else pushes changes to a remote version of that branch, you can run git pull --rebase while on your local "gsoc2019_numberFormat" branch to bring it up to date.

Next, make your changes, add and commit. Then push the changes to the remote joliveira_fork remote:

git push joliveira_fork gsoc2019_numberFormat

Generating "eternal" URLs to commits or objects in a repository

History has taught that no system used by KDE around the code repositories stays forever. Quickgit, CGit, Phabricator & Co. came and at one point were replaced again. Sadly also taking with them the service-specific URLs (and host names).

To give documentation, blog posts, commit messages and other long-living documents a way to reference commits or objects in the repository like directories or files, at given branches or at given tags, the service commits.kde.org exists. It maps and forwards URLs to the respective current service URLs.

The pattern for URLs to commits is this:

https://commits.kde.org/<repo-id>/<commit-id>

Example:

https://commits.kde.org/kcoreaddons/d2f4d353327b322ee6bfcc303169190ae44393f0

The pattern for URLs to objects is like this:

https://commits.kde.org/<repo-id>[?[path=<pathToFileOrDirectory]&[branch=<branch>|tag=<tag>]]

<path> should be without a leading /. It defaults to the top-level directory if not set. Either a branch or tag can be passed at which the objects should be shown. It defaults to the main branch (master usually).

Examples:

https://commits.kde.org/kcoreaddons?path=src   # points to src/ directory in master branch
https://commits.kde.org/kcoreaddons?path=README.md&tag=v5.0.0   # points to README.md file at tag v5.0.0
https://commits.kde.org/kdelibs?path=kdecore/tests&branch=KDE/3.5   # points to kdecore/tests directory in branch KDE/3.5

There currently is no service to generate commit.kde.org URLs from URLs for the actual system. This has to be done manually.

Submitting a merge request using the command line

If you would prefer to avoid the web UI and submit a merge request entirely from the command line, you can! When you are pushing your branch, add -o merge_request.create -o merge_request.target=[target branch here] to the git push command.