Gerrit/Tutorial/id

Tutorial ini berisi cara menggunakan Git dan Gerrit untuk pengembangan Wikimedia.


 * Jika Anda ingin menghemat waktu dan sudah memahami hal teknis, gunakan panduan cara yang sangat singkat sebagai gantinya:
 * Untuk pengguna ahli, memiliki dokumentasi tambahan.
 * Jika Anda hanya ingin mencoba-coba dengan Gerrit dan tidak ingin menulis tambalan untuk proyek perangkat lunak Wikimedia "asli", gunakan contoh uji Gerrit kami sebagai gantinya.

Dalam tutorial ini, perintah untuk masuk dimulai dengan tanda dolar di dalam kotak, seperti ini:. Jangan masukkan awalan. Jika sebuah perintah juga menyertakan variabel yang harus Anda ubah sendiri, maka variabel tersebut ditampilkan dengan warna merah:.

Apa itu Git?
Git adalah sebuah sistem pengendali versi terdistribusi sumber terbuka yang bebas. “Terdistribusi” berarti bahwa tidak ada salinan pusat dari repositori. Dengan Git, setelah Anda mengkloning repositori, Anda memiliki salinan kode yang berfungsi penuh, dengan semua cabang dan rilis yang ditandai di bagian milik Anda.

Apa itu Gerrit?
Gerrit adalah alat tinjauan kode kolaboratif berbasis web gratis yang terintegrasi dengan Git.

Pada dasarnya: Anda mengirimkan perubahan perangkat lunak yang Anda usulkan (sering disebut "patch", dalam bahasa Gerrit disebut "changeset") sebagai branch baru. Jika versi pertama ("patchset 1") belum sempurna, Anda dapat membuat lebih banyak perubahan ("mengubah") di cabang tersebut ("patchset 2", dll.). Setelah patchset menerima ulasan "+2", patch tersebut akan diterima dan digabungkan ke dalam cabang utama dari repositori kode (biasanya disebut "master"). "Merging" berarti bahwa perubahan Anda akan disertakan secara default ketika seseorang memeriksa atau mengunduh repositori kode yang Anda ubah.

Membuat akun pengembang Wikimedia
Jika Anda belum memiliki akun pengembang Wikimedia, buka wikitech.wikimedia.org dan buatlah akun. Nama pengguna dan kata sandi yang sama akan digunakan untuk masuk ke Gerrit di bawah ini.

Mengkonfigurasi Git
Instruksi ini menjelaskan cara menginstal Git sebagai alat baris perintah (jendela terminal). Jika Anda lebih memilih Antarmuka pengguna grafis (GUI) daripada baris perintah, silakan periksa daftar klien yang dikelola oleh proyek Git. Untuk petunjuk instalasi alternatif lihat dokumentasi resmi.

Font Awesome 5 brands linux.svg Linux

 * Gunakan alat manajemen paket perangkat lunak grafis dari distribusi Linux Anda untuk menginstal paket.
 * Jika git belum dikemas oleh distribusi Anda, maka silakan tanyakan di forum dukungan distribusi linux Anda.

Font Awesome 5 brands windows.svg Windows

 * Instal Git untuk Windows dari https://gitforwindows.org/. Ini akan memberi Anda Git, dan sebuah shell yang disebut "Git Bash" yang memungkinkan sebagian besar baris perintah dalam instruksi ini berfungsi di Windows.

Apple logo black.svg macOS

 * Instal pengelola paket Homebrew lalu jalankan perintah – langkah ini disarankan, karena memungkinkan pembaruan sederhana dan pemasangan paket lain dengan mudah.
 * Sebagai alternatif, Anda dapat menginstal Git for Mac yang berdiri sendiri.

Mengkonfigurasi Git
Sekarang setelah Anda menginstal Git, saatnya untuk mengonfigurasi informasi pribadi Anda. Anda seharusnya hanya perlu melakukan ini sekali saja. Anda juga dapat mengubah informasi pribadi Anda kapan saja dengan menjalankan perintah ini lagi.

Git melacak siapa yang membuat setiap komit dengan memeriksa nama dan surel pengguna. Selain itu, info ini digunakan untuk mengaitkan komit Anda dengan akun Gerrit Anda.

Masukkan dua perintah di bawah ini untuk mengatur nama pengguna dan alamat surel Anda. Ganti dengan nama pengguna Gerrit Anda sendiri dan ganti  dengan alamat email Anda sendiri:

Mengatur Kunci SSH di Gerrit
Kami menggunakan kunci SSH untuk membuat koneksi yang aman antara komputer Anda dan Gerrit. The Wikimedia Security Team recommends, as of August 2021, that users creating SSH Keys use the  type for optimum security and performance. Untuk memastikan apakah Anda perlu membuat kunci baru, mari periksa apakah kunci SSH sudah ada di sistem Anda. Jalankan perintah ini di terminal:

Perintah akan mencantumkan file yang ada di direktori (tersembunyi). Jika direktori sudah ada di sistem Anda dan jika output mencantumkan berkas bernama, maka Anda dapat langsung masuk ke #Salin kunci Publik SSH Anda.

Buat kunci SSH baru
Untuk menghasilkan kunci SSH baru, buka Git Bash, lalu masukkan perintah di bawah ini dan ganti dengan alamat surel Anda sendiri. Kita akan menggunakan pengaturan default, jadi ketika diminta untuk memasukkan file untuk menyimpan kunci, cukup tekan enter.

Masukkan frase sandi yang kuat dan unik dan tekan tombol [Enter].


 * Mengapa frasa sandi penting?


 * Kata sandi tidak terlalu aman.  If you use one that’s easy to remember, it’s easier to guess or brute-force. If you use one that’s random it’s hard to remember, so you might write the password down. Both are very bad. This is why you’re using ssh keys. But using an ssh key without a passphrase is basically the same as writing down that random password in a file on your computer. Anyone who gains access to your drive has gained access to every system you use that key with. That's why you also add a passphrase. To not enter a long passphrase every time you use the key, there’s a tool called . It can save your passphrase securely. If you use macOS or Linux, then your keys can be saved in the system’s keychain to make your life even easier. 

The  command will create 2 files in   directory:


 * : your private SSH key (for identification)
 * : your public SSH key

Copy your SSH Public key
Get the content of your public key file (e.g. ) to copy it to your clipboard:

One option is to open your public key file with your favorite text editor (Notepad, TextEdit, gedit, etc.). In the file chooser dialog of your text editor, you may need to turn on “View hidden files” to find the file, because the  directory is hidden. Sometimes the “View hidden files” option is available by right-clicking in the file chooser dialog.

Other options are:


 * On Linux, run and manually copy the output to the clipboard.
 * On Windows, you can open Git GUI, go to Help 🡒 Show Key, and then press "Copy To Clipboard" to copy your public key to your clipboard.
 * On macOS, you can run to copy the contents of the your public key file to your clipboard.

It’s important you copy your SSH Public key exactly as it is written, without adding any newlines or whitespace. Copy the full text, including the "ssh-ed25519" prefix, the key itself, and the email address suffix.

Add SSH Public key to your Gerrit account

 * Log into the web interface for Gerrit. The username and password for your Gerrit are the same as for your Wikimedia Developer account.
 * Click on your username in the top right corner, then choose "Settings".
 * Click "SSH Keys" in the menu on the left.
 * Paste your SSH Public Key into the corresponding field and click "ADD NEW SSH KEY".

Add SSH Private key to use with Git
Start the Git Bash command line.


 * Get ssh-agent running using
 * Be sure to use the accent, not the single quote  . (You could copy and paste from this page if you cannot easily enter this special character.) Note also that if you are using an alternative shell in Linux (for example the Fish shell), this command may not work; switching to Bash will fix the issue.
 * Be sure to use the accent, not the single quote  . (You could copy and paste from this page if you cannot easily enter this special character.) Note also that if you are using an alternative shell in Linux (for example the Fish shell), this command may not work; switching to Bash will fix the issue.


 * Add your private key to the agent. If you followed the steps above and your key has the default name, then the command is:


 * To permanently add the SSH key, use command:

For macOS see CodeX article.
 * Connect to the Gerrit server via  to check if everything works as expected. Replace  by your username as shown in your Gerrit settings:

An example Gerrit SSH connection success message looks like this:
 * Be mindful and compare that the "ed25519 key fingerprint" is the same as the SSH fingerprint for gerrit.wikimedia.org:29418. If it is the same, answer "Yes" to "Are you sure you want to continue connecting?". Then enter the passphrase for your key.
 * You should get a message "Welcome to Gerrit Code Review". The last line should show "Connection to gerrit.wikimedia.org closed."
 * If you run into problems, use (replace  by your username). The   will provide verbose output to help find problems. Then read Gerrit Troubleshooting.

Download code using Git
Let's practice by downloading (also called "cloning") the repository called "sandbox". Run the following on the Git Bash command line:

(Replace by your Gerrit username. And make sure the URL begins with   and not  ).

This will copy the entire history and the code base of the "sandbox" extension repository into your machine. You will have a working directory of the extension's main branch (usually also called "git master"). Enter the new directory (via the command ). Now you can look at the code and start editing it.

Prepare to work with Gerrit
Gerrit requires that your commit message must have a "change ID". They look like  starting with an I (capital i). Each time you amend a commit to improve an existing patch in Gerrit, this change ID stays the same, so Gerrit understands it as a new "patch set" to address the same code change.

There's a git add-on called git-review that adds a Change-ID line to your commits. Using git-review is recommended. It makes it easier to configure your Git clone, to submit a change or to fetch an existing one.

Installing git-review
Note that Wikimedia Gerrit requires git-review version 1.27 or later.

For more details, please see Gerrit/git-review#Installation.

Font Awesome 5 brands linux.svg Linux

 * Use the graphical software package management tool of your Linux distribution to install the  package.
 * If git-review has not been packaged by your distribution, check git-review for other options such as installing git-review by using the pip Python package installer.
 * If you use FreeBSD, install git-review through ports.

Font Awesome 5 brands windows.svg Windows

 * Please see git-review Windows.

Apple logo black.svg macOS

 * For OS X 10.11 El Capitan and later, follow Method 1.
 * On versions prior to 10.11, use the pip Python package installer by following Method 2.

Configuring git-review
Git's default remote host name is "origin". This name is also used by Wikimedia projects. We need to tell git-review to use that host. Replace with your Gerrit username:

Setting up git-review
After downloading ("cloning") a repository, you need to set it up for git-review. This will automatically happen the first time you try to submit a commit, but it's generally better to do it right after cloning. Make sure that you are in the directory of the project that you cloned (otherwise you will get an error "fatal: Not a git repository"). Then run this command:

Towards the end of the output, you should see something like this:

This may ask you for your git username, if it's different from the shell username you're using.

Submit a patch
Make sure that you cloned the code repository that you are interested in (see here).

Make sure that you are in the directory of the code repository (the command tells you where exactly you are).

Update the main development branch
Make sure that the main development branch (the branch created when you initially cloned the repository) is up to date:

However, note that some repositories use a different name for their main development branch (for example  instead of , or the   repository has a   instead of a   branch).

Create a branch
First, create a local branch for your new change. Replace below by a short but reasonably descriptive name (e.g.   if a corresponding  task exists for your changes, , or  ). Other people will also use this name to identify your branch.

This will create a new branch (called ) from the latest 'master' and check it out for you. In the example above, we called that new branch.

Make your changes
Make changes to your local code. Use your preferred text editor and modify a file. In the example below, we edit the file  and add a word.

Then close your text editor and check the changes you have made since the last commit, within the file(s) and within the directory:

displays your changes in unified diff format: Removed lines have a minus prefix and added lines have a plus  prefix. These changes are not yet "staged" (via ) for the next commit.

Stage your changes for a commit
Run to decide which of your changes should become part of your commit. It will display a list of all file(s) that you have changed within the directory. At this point, the output will display "no changes added to commit" as the last line.

Use  to make your changed file(s) become part of your next commit. In the example above we modified the file, so the command would be:

Any files you've changed that you have not passed to  will be ignored when running   in the next step.

Commit your staged changes
Once you are happy with the list of changes added via, you can turn these changes into a commit in your local repository by using

You will then be asked in your text editor to add a descriptive summary for your commit. You must follow the Commit message guidelines. This is what other people will see when looking at the history of changes in the code repository.

Save the commit message and close your text editor. A summary (the commit ID, your subject line, the files and lines changed) will be displayed.

Prepare to push your commit to Gerrit
Synchronize your changeset with any changes that may have occurred in the master branch while you've been working ("rebasing"). From within your branch, run:

Now you are ready to push your code to Gerrit for review. If you made several related commits, consider merging them into one single commit for review.

Push your commit to Gerrit
If you followed #Prepare to work with Gerrit above and installed  and ran , then the command to push changes to Gerrit is:

The  option tells git-review not to perform a rebase before submitting the change to Gerrit.

Upon success, you'll get a confirmation and a link to the changeset in Gerrit. In the example above, that link is: https://gerrit.wikimedia.org/r/#/c/sandbox/+/563720

Congratulations! Your patch is in Gerrit and hopefully will get reviewed soon!

View the Change / Next Steps
Open the link to your Gerrit changeset in a web browser.

Under "Files", after you clicked the down arrow at the very right of any file in the list, you can see a diff of your changes per file: The old lines are shown in red color and your new lines are shown in green color.

If your commit addresses a ticket in Phabricator, a comment will be automatically added in the Phabricator task if you followed the Commit message guidelines. If you did not, you could either fix your commit message (by creating an updated patchset), or manually add a comment on that Phabricator ticket which includes a link to your changeset in Gerrit.

Other common situations
Also see Gerrit Advanced usage if your situation is not covered here.

Squash several commits into one single commit via rebase
If you made several related commits to your local repository prior to wanting to submit for review, you should squash (merge) those commits into one single commit.

The  or   option allows you to change (rewrite) your commit history. For each commit, you can modify and change the commit message, add or remove files, or perform other modifications.

First you need to tell git how far back you want to pull. To get a list of all changes in your branch:

You can also limit the displayed list of recent changes. means pull the last three commits:

After you type this command, your text editor will display your commits in reverse order and a list of available commands:

Since we only want to send one commit to review, we will squash the last two commits into the first. Hence change all but the first "pick" to "squash":

pick aa8cf1d Adding method customFilterFunctionGetRiskyCountryCodeScore to GatewayAdapter. squash 38828e2 Adding $wgDonationInterfaceCustomFiltersFunctionsRiskyCountries to donationinterface.php squash be33007 Fix a typo

When you finished picking and squashing and saved the file, another file will open in your text editor to allow you get to edit and merge your commit messages. Be careful to only keep one of the Change-Id lines and have it be at bottom of the message after one empty line.

Your messages from your previous commits will automatically be placed in this message:

Remember to put your (updated) summary message in the commit. In this case the new summary message will be:

(mingle-fr-2012-69) Adding a custom filter for risky countries.

If all goes well, you should see a successful rebase message:

Afterwards, submit your patch for review:

You should see a message like this showing your git review went to Gerrit (in this example, to https://gerrit.wikimedia.org/r/7187):

Amending a change (your own or someone else's)
Sometimes, you might need to amend a submitted change. You can amend a change as long as the change hasn't been merged yet.

You can amend your own changes. To amend changes submitted by someone else, you need to be a member of Gerrit's Trusted-Contributors group. To become a member of Trusted-Contributors, find someone who is a member and ask them to add you. The group is viral in that members can add new members, use your powers responsibly.

Rebasing
Rebase to bring your local branch up to date with the remote. It's best to make rebase updates a separate patch, so that your code reviewers have an easy time seeing what changes you've made. Assuming you are using Gerrit, you can do this by clicking the "Rebase Change" button when viewing your patch in Gerrit's web interface.

Hard reset and checkout the change with this command: (BEWARE:  performs a hard reset that destroys all local changes. Stash or commit changes first which you wish to preserve!)

For example:

You can look in Gerrit to figure out the changenumber. It is the six digit number in the URL of your code review page.

Or, if you already have the change in a branch on your local repository, you can just check it out:

For example:

Make changes and push
Next, make some changes with your favorite text editor.

the files as needed, then commit the change (ensuring you are amending the commit):

Push the change:

The  is important here. It tells git-review to not rebase your change against master, which clutters diffs between patch set 1 and 2.

Push to a branch different than master
Above, the commit was pushed to the master branch. The branch name only appeared as the topic of the commit in the Gerrit UI. If you really want to push to a different branch than master, you have to push via.

Editing via the web-interface
If you're logged in to Gerrit, you can also create code changes directly within the web interface. This can be useful for making small patches, or for non-developers to contribute small fixes.


 * 1) Go to https://gerrit.wikimedia.org/r/admin/repos/ and choose the code repository that you want to edit.
 * 1) Select "Commands" in the sidebar
 * 1) Click "Create Change"
 * 1) Set branch to "master" (if you don't want to use master branch you can use the other branches available for that project)
 * 1) Set the topic to something of your choosing (e.g. "copy-edit" - must be all-one-string) (optional)
 * 1) Write a description ("commit summary") in the big text field by following message guidelines. (Example)
 * 1) Click "Create"
 * 1) In the upper right corner, click the "Edit" button
 * 1) Under "Files", click "ADD/OPEN/UPLOAD" button
 * 1) Type the folder/file path for the file you wish to edit (e.g. i18n/en.json) and click "Confirm"
 * 1) Find the line(s) you want to change, and change them.
 * 1) Click "Save"
 * 1) Click "Close"
 * 1) Click "Publish edit"
 * 1) Click "Mark as active" to remove the "Work in Progress" status from your code changes

Done!

If you need to change the commit message of an existing changeset, you can use these steps:


 * 1) Go to the changeset itself. Example URL: https://gerrit.wikimedia.org/r/c/1234567890 (replace the ID at the end)
 * 1) In the "Files" section, click "Commit message"
 * 1) In the upper right corner, click the "Edit" button
 * 1) Make changes to the commit summary.
 * 1) In the upper right corner, click "Save"
 * 1) In the upper right corner, click "Close"
 * 1) In the upper right corner, click "Publish edit"

Gerrit & Vagrant
MediaWiki-Vagrant is a portable MediaWiki development environment and is readily usable with git-review and gerrit. After installing MediaWiki-Vagrant use  to navigate to your extensions folder. Then follow the instructions above on submitting a patch via gerrit.

How code is reviewed in Gerrit
Code review is an essential part of our contribution workflow. The principle is basic: any patch must be reviewed by others before being merged.

This means that your code will need reviewers. Check our advice for getting reviews.

Review before merge
It's important to us to have a review-before-merge workflow for MediaWiki core and also for any extension we deploy. We will also offer that option to any extension author who wants it for their extension. The one exception is localisation and internationalisation commits, which will be able to be pushed without review.

Who can review? Gerrit project owners
After creating a Developer account, anyone can comment on commits and express criticism and approvals. Anyone can give a nonbinding "+1" to any commit. However, for any given repository ("Gerrit project"), only a small group of people will have the ability to approve code within Gerrit and merge it into the repository. This superapproval is a "+2" even though that's a misleading name, because two +1 approvals DO NOT add up to a +2. These people are "Gerrit project owners".

How to comment on, review, and merge code in Gerrit




Anyone can comment on code in Gerrit.

Viewing and commenting on code
If you know the changeset you want to look at (URL will look like https://gerrit.wikimedia.org/r/#/c/23939/), go to that. Otherwise, use the search box. You can search by author ("Owner"), Gerrit project, branch, changesets you've starred, etc. The Gerrit search documentation covers all of the different search operators you can use. This should only be set if the assignee has agreed. It will report a red or green mark depending on whether the build passes. It'll show up in their Gerrit dashboard. You can double-click on a line and then press the C key to comment on that line, then click "Save" to save the draft comment. Then, at the top of the page click the "Reply" button to publish your comment. These numbers are nonbinding, won't cause merges or rejections, and have no formal effect on the code review. This action removes the diff from the list to review, but leaves it in Gerrit for archival purposes. See T48148 for an example.
 * Make sure that you have a developer account.
 * Log in to Gerrit.
 * The changeset has a few fields, links and buttons:
 * Assignee. An optional field to make a single person responsible for handling reviewing the changeset.
 * Reviewers. 'jenkins-bot' is the autoreviewer that auto-verifies anything that passes the Jenkins tests.
 * The "Add reviewer" button under Reviewers: in the upper left corner manually request review from someone.
 * Under Files, Expand All opens the diff for each file below.
 * Reply adds your comments to a changeset, including an overall comment and/or inline comments you added (see above).
 * If, upon code review, you approve, use "Code-Review: " under "Reply"; otherwise, use "Code-Review:  " to disapprove.
 * Abandon (you'll see this if you wrote this diff).
 * The "Only Comments" switch allows to hide reviews by non-human bots.

Comparing patch sets
Every time you amend your commit and submit it for review, a new patch set is created. You can compare the different patch sets like this:

On the right of the screen under Patch Set, the latest patch set is preselected. Adjust the selected patch sets to your needs.
 * Under Files, select either Expand All or choose a specific file listed to open that file.
 * On the left side under Patch Set, Base is preselected.

Formally reviewing and merging or rejecting code
If you are one of the Gerrit project owners, you'll also see:


 * Abandon button


 * under Reply, additional Code-Review options to +2 (approve) or -2 (veto) a diff, and a Post button (publish your comment and merge diff into the branch, in 1 step)


 * Submit button (merge -- only useful if you or someone else has already given a +2 approval to the diff, but not merged it)

And once you've merged something into the example Gerrit project you'll see it in https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/extensions/examples/.

If you merged a commit that references a task in Phabricator and that commit is supposed to fix that task completely, please go to that task and change its status to "Resolved" (via the Add Action… 🡒 Change Status dropdown). Also reference the merge ID if gerritbot has not already posted it in that task.

Troubleshooting
For problems and how to solve them, see.