162 lines
5.4 KiB
ReStructuredText
162 lines
5.4 KiB
ReStructuredText
:title: Getting Started
|
|
|
|
.. _getting_started:
|
|
|
|
Getting Started
|
|
###############
|
|
|
|
The OpenDev Workflow
|
|
====================
|
|
|
|
The OpenDev workflow is centered around Gerrit, which uses the concept of
|
|
**changes** rather than Pull Requests. To propose a change to a git
|
|
repository, you start by cloning the repository you're interested in, then
|
|
create a branch to work in. You curate a commit on that branch, then propose
|
|
it to Gerrit using the **git-review** tool:
|
|
|
|
.. image:: images/code_review.png
|
|
:width: 700 px
|
|
|
|
At that point, the proposed change is picked up by our Continuous Integration
|
|
tool, Zuul, which runs **check tests** on it. The change is available for
|
|
review by human reviewers. Those automated and human checks may result in
|
|
you having to amend the proposed commit, then propose it again with git-review.
|
|
Once the change is approved by both Zuul and the human reviewers, Zuul picks
|
|
it up again and runs **gate tests** on it before finally merging it.
|
|
|
|
Setting up your Gerrit account
|
|
==============================
|
|
|
|
Get a single sign-on OpenID
|
|
---------------------------
|
|
|
|
Gerrit is currently using *Ubuntu One* as a SSO provider. You'll therefore
|
|
need a `Ubuntu One account <https://login.ubuntu.com/+login>`_ to use it.
|
|
This account will also allow you to use `Launchpad <https://launchpad.net>`_,
|
|
which some projects on OpenDev use as a bug tracker.
|
|
|
|
Select a Gerrit username and upload your SSH key
|
|
------------------------------------------------
|
|
|
|
Visit https://review.opendev.org/ and click the ``Sign In`` link
|
|
at the top-right corner of the page. Log in with your Ubuntu One
|
|
OpenID.
|
|
|
|
The first time you sign into OpenDev's Gerrit site, you will be
|
|
prompted to "Select a unique username:". You can enter your
|
|
Ubuntu One username here, or something else if you want. Type
|
|
carefully, as once set it cannot be changed.
|
|
|
|
At that point you can already review proposed changes. To propose you
|
|
own changes, you need to first upload your SSH key to Gerrit. This is done
|
|
by visiting the `SSH Public Keys section of your Gerrit settings
|
|
<https://review.opendev.org/#/settings/ssh-keys>`_.
|
|
|
|
Configure your local git environment
|
|
------------------------------------
|
|
|
|
Ensure that you have run these steps to let git know about your email
|
|
address::
|
|
|
|
git config --global user.name "Firstname Lastname"
|
|
git config --global user.email "your_email@youremail.com"
|
|
|
|
To check your git configuration::
|
|
|
|
git config --list
|
|
|
|
You'll want to make sure that the ``user.email`` you specify matches
|
|
at least one you've provided to Gerrit. By default this is taken
|
|
from your OpenID login the first time you authenticate, but you can
|
|
also change it or add more addresses through the `Contact
|
|
Information <https://review.opendev.org/#/settings/contact>`_ page
|
|
at any point in the future.
|
|
|
|
Install the git-review utility
|
|
------------------------------
|
|
|
|
``git-review`` is a git subcommand tool that handles all the details of
|
|
working with Gerrit. You can learn more about git-review by reading its
|
|
`documentation <https://docs.openstack.org/infra/git-review/>`_.
|
|
|
|
The git-review package is available on all major Linux distributions,
|
|
so you can use your local package management tooling (apt-get, dnf, yum,
|
|
zypper, pacman...) to install it directly. For example, on Debian/Ubuntu::
|
|
|
|
apt-get install git-review
|
|
|
|
On Mac OS X, or most other Unix-like systems, you may install it with
|
|
`pip <https://pip.readthedocs.org/en/latest/installing.html>`_::
|
|
|
|
pip install git-review
|
|
|
|
Git-review assumes that your Gerrit username is the same as the current
|
|
running user on your operating system. If you are using different usernames
|
|
and would like to avoid getting prompted, you should configure git to use
|
|
your Gerrit username, as follows::
|
|
|
|
git config --global gitreview.username yourgerritusername
|
|
|
|
|
|
Proposing a change
|
|
==================
|
|
|
|
Clone and prepare the git repository
|
|
------------------------------------
|
|
|
|
Clone a repository in the usual way, for example::
|
|
|
|
git clone https://opendev.org/<namespace>/<projectname>
|
|
cd <projectname>
|
|
|
|
Then ask git-review to configure your repository to know about Gerrit::
|
|
|
|
git review -s
|
|
|
|
Feel free to check any unknown host key fingerprints against the
|
|
:ref:`gerrit-ssh-host-keys`, and if you get an error about a missing
|
|
contributor license agreement, see the Developer's Guide section on the
|
|
:ref:`openstack-individual-contributor-license-agreement`.
|
|
|
|
Create a change in a topic branch
|
|
---------------------------------
|
|
|
|
Create a `topic branch
|
|
<https://git-scm.com/book/en/Git-Branching-Branching-Workflows#_topic_branch>`_
|
|
to hold your work and switch to it::
|
|
|
|
git checkout -b TOPIC-BRANCH
|
|
|
|
Then modify files, and create a git commit as usual, for example using::
|
|
|
|
git commit -a
|
|
|
|
Submit a Change for Review
|
|
--------------------------
|
|
|
|
Now that your commit is ready, all you need to do is to send it to Gerrit
|
|
for code review::
|
|
|
|
git review
|
|
|
|
Updating a Change
|
|
-----------------
|
|
|
|
If the code review process suggests additional changes, make and amend
|
|
the changes to the existing commit. Leave the existing Change-Id:
|
|
footer in the commit message as-is, so that Gerrit knows this is an
|
|
updated patchset for an existing change::
|
|
|
|
git commit -a --amend
|
|
git review
|
|
|
|
Next steps
|
|
==========
|
|
|
|
We have a tutorial: :ref:`sandbox`. If this is your first time
|
|
contributing to a project hosted by OpenDev, we strongly suggest you
|
|
follow this tutorial.
|
|
|
|
You'll find a lot more details about how to use Gerrit and Zuul in our
|
|
:ref:`developer_manual`.
|