< Infrastructure
Revision as of 03:06, 11 February 2020 by Ngraham (talk | contribs) (Add stub of new GitLab documentation. More to come later)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

GitLab is KDE's patch review system. This page is intended to serve as a general-purpose introduction to the most important aspects: submitting and reviewing patches. It should not take long before you are happily using Phabricator.

Dialog-information.png
Information
The KDE community does not yet use GitLab for bug reporting. This is planned, but not yet completed. In the meantime, please submit bug reports only using https://bugs.kde.org.


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 patch. 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.


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.

Dialog-information.png
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

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:

Find the project.png

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

Click the Fork button.png

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

Choose the fork namespace.png

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:

Click the Clone button.png

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.

Copy the URL.png


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 push to your fork

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

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 above. 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:

Merge Request info.png

In the Description section, write at least one sentence describing your change and why it is necessary, adding more details if needed. For patches 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.

In the section below, it is very important that you make sure all three checkboxes are checked:

Check all checkboxes!.png

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

Submit Merge Request.png


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!


Content is available under Creative Commons License SA 4.0 unless otherwise noted.