Split "Getting started" from "Developer's Guide"
Now that the Developer's Guide is directly linked to from the opendev.org webpage, start with a brief introduction of the steps necessary to interact with it, rather than comprehensive (and intimidating) reference documentation. Change-Id: If9244c1819ab38676466d821be0b5104b6852c47
This commit is contained in:
Thierry Carrez
parent
24b31654a4
commit
1ca0419bce
@ -5,30 +5,25 @@
|
||||
Developer's Guide
|
||||
#################
|
||||
|
||||
Quick Reference
|
||||
===============
|
||||
.. image:: images/code_review.png
|
||||
:width: 700 px
|
||||
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
The goal of this document is to walk you through the concepts and
|
||||
specifics that should be understood while contributing to projects
|
||||
hosted in the OpenDev infrastructure.
|
||||
|
||||
Development on OpenDev requires at minimum an account on the OpenDev
|
||||
Gerrit Code Review System. **Effective** Development in hosted
|
||||
projects also requires interacting with other developers in IRC
|
||||
channels on Freenode. It is recommended to start by getting set up on
|
||||
IRC so that one can ask questions if one encounters issues with other
|
||||
phases of account setup.
|
||||
Accounts creation
|
||||
=================
|
||||
|
||||
The steps necessary to create a Gerrit account are described in
|
||||
:ref:`getting_started`. Only extra recommended steps will be described here.
|
||||
|
||||
IRC Account
|
||||
-----------
|
||||
|
||||
Most projects hosted on OpenDev use the Freenode IRC network for
|
||||
real-time communication.
|
||||
While development on OpenDev only requires an account on the OpenDev
|
||||
Gerrit Code Review System, **effective** development in OpenDev hosted
|
||||
projects often requires interacting with other developers in IRC
|
||||
channels on Freenode. It is recommended to start by getting set up on
|
||||
IRC so that one can ask questions if one encounters issues with other
|
||||
phases of account setup.
|
||||
|
||||
If you do not know how to connect to Freenode, the `Connecting to Freenode`_
|
||||
document will help.
|
||||
@ -40,170 +35,26 @@ to only allow people to join who are using a Registered Nick. Registering
|
||||
a Nick also prevents someone else from taking a Nick that people come to
|
||||
know you by.
|
||||
|
||||
You can find the OpenDev community in the ``#opendev`` IRC channel on Freenode.
|
||||
|
||||
For further information about the use of IRC in OpenStack, see
|
||||
:ref:`irc-guide`.
|
||||
|
||||
.. _Connecting to Freenode: http://freenode.net/kb/answer/chat
|
||||
.. _Register your IRC Nick: http://freenode.net/kb/answer/registration
|
||||
|
||||
Account Setup
|
||||
-------------
|
||||
|
||||
Prior to contributing to an OpenDev source code repository a few
|
||||
steps need to be completed. This document covers the steps that get
|
||||
you started, such as creating a few accounts on required websites,
|
||||
signing a contributor license agreement, uploading an ssh key, and
|
||||
installing git-review.
|
||||
Extra Gerrit account setup steps
|
||||
--------------------------------
|
||||
|
||||
Get a single sign-on OpenID
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You'll need a `Ubuntu One account
|
||||
<https://login.ubuntu.com/+login>`_, since this is how the Web
|
||||
interface for the Gerrit Code Review system will identify you. This
|
||||
is also useful for automatically crediting bug fixes to you on
|
||||
Launchpad when you address them with your code commits.
|
||||
|
||||
Log into Gerrit
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
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. This is the username
|
||||
you will eventually use to submit changes to Gerrit and to perform
|
||||
authenticated queries through its API.
|
||||
|
||||
Because the OpenDev's Gerrit deployment uses Ubuntu One
|
||||
OpenID single sign-on, you won't need a separate password for
|
||||
Gerrit, and once you log in to any service relying on that OpenID
|
||||
provider such as Launchpad or a variety of OpenDev community
|
||||
systems (review, storyboard, wiki), you won't have to enter your
|
||||
password for the others.
|
||||
|
||||
Sign the appropriate Individual Contributor License Agreement
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
OpenStack Individual Contributor License Agreement
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Projects that are part of OpenStack project require signing the
|
||||
Individual Contributor License Agreement, see `these detailed
|
||||
instructions
|
||||
<https://docs.openstack.org/contributors/common/setup-gerrit.html#individual-contributor-license-agreement>`_.
|
||||
|
||||
Upload your public SSH key
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You'll also want to `upload an SSH key to Gerrit
|
||||
<https://review.opendev.org/#/settings/ssh-keys>`_ while you're at
|
||||
it, so that you'll be able to commit changes for review later. This is
|
||||
separate from adding a key to Launchpad (which you can do if you
|
||||
like, but is not required for contributing to OpenStack).
|
||||
|
||||
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
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
We recommend using the ``git-review`` tool which is a git subcommand
|
||||
that handles all the details of working with Gerrit, the code review
|
||||
system used in OpenStack development. Before you start work, make
|
||||
sure you have git-review installed on your system.
|
||||
|
||||
On Ubuntu Precise (12.04) and later, git-review is included in the
|
||||
distribution, so install it as any other package::
|
||||
|
||||
apt-get install git-review
|
||||
|
||||
On Fedora, git-review is included into the distribution, so install it as any
|
||||
other package::
|
||||
|
||||
dnf install git-review
|
||||
|
||||
On Red Hat Enterprise Linux, you must first enable the `EPEL
|
||||
<https://fedoraproject.org/wiki/EPEL>`_ repository, then install it as
|
||||
any other package::
|
||||
|
||||
yum install git-review
|
||||
|
||||
On openSUSE, git-review is included in the distribution, so
|
||||
install it as any other package::
|
||||
|
||||
zypper in git-review
|
||||
|
||||
On Arch Linux, git-review is included into the distribution, so
|
||||
install it as any other package::
|
||||
|
||||
pacman -S 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
|
||||
|
||||
If you run into trouble, you can refer to the `git-review documentation
|
||||
<https://docs.openstack.org/infra/git-review/>`_.
|
||||
|
||||
All of git-review's interactions with Gerrit are sequences of normal
|
||||
git commands. If you want to know more about what it's doing, just
|
||||
add -v to the options and it will print out all of the commands it's
|
||||
running.
|
||||
|
||||
Starting Work on a New Project
|
||||
------------------------------
|
||||
|
||||
Clone a repository in the usual way, for example::
|
||||
|
||||
git clone https://opendev.org/<namespace>/<projectname>
|
||||
|
||||
You may want to ask git-review to configure your repository to know
|
||||
about Gerrit at this point. If you don't, it will do so the first
|
||||
time you submit a change for review, but you probably want to do
|
||||
this ahead of time so the Gerrit Change-Id commit hook gets
|
||||
installed. To do so::
|
||||
|
||||
cd <projectname>
|
||||
git review -s
|
||||
|
||||
Git-review checks that you can log in to Gerrit with your ssh key. It
|
||||
assumes that your Gerrit/Launchpad user name is the same as the
|
||||
current running user. If that doesn't work, it asks for your
|
||||
Gerrit/Launchpad user name. You can avoid that question by
|
||||
configuring git to use your Gerrit username, as follows::
|
||||
|
||||
git config --global gitreview.username yourgerritusername
|
||||
|
||||
If you don't remember your Gerrit user name go to the `settings page
|
||||
on gerrit <https://review.opendev.org/#/settings/>`_ to check it out
|
||||
(it's not your email address).
|
||||
|
||||
.. Note:: You can verify the SSH host keys for review.opendev.org
|
||||
on https://review.opendev.org/#/settings/ssh-keys
|
||||
|
||||
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.
|
||||
|
||||
Accessing Gerrit over HTTPS
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -325,32 +176,44 @@ status of a specification. For more information, see `the Blueprints wiki page
|
||||
View all approved project team's specifications at
|
||||
https://specs.openstack.org/.
|
||||
|
||||
Starting a Change
|
||||
Starting a change
|
||||
-----------------
|
||||
|
||||
Once your local repository is set up as above, you must use the
|
||||
following workflow.
|
||||
The :ref:`getting_started` page explains how to originally clone and prepare
|
||||
a git repository. This only has to be done once, as you can reuse the cloned
|
||||
repository for multiple changes.
|
||||
|
||||
Make sure you have the latest upstream changes::
|
||||
Before creating your topic branch, just make sure you have the latest
|
||||
upstream changes::
|
||||
|
||||
git remote update
|
||||
git checkout master
|
||||
git pull --ff-only origin master
|
||||
|
||||
Create a `topic branch
|
||||
<https://git-scm.com/book/en/Git-Branching-Branching-Workflows#_topic_branch>`_
|
||||
to hold your work and switch to it. If you are working on a
|
||||
blueprint, name your topic branch ``bp/BLUEPRINT`` where BLUEPRINT is
|
||||
the name of a blueprint in Launchpad (for example,
|
||||
``bp/authentication``). The general convention when working on bugs
|
||||
is to name the branch ``bug/BUG-NUMBER`` (for example,
|
||||
``bug/1234567``). Otherwise, give it a meaningful name because it will
|
||||
show up as the topic for your change in Gerrit::
|
||||
|
||||
Git branch names
|
||||
----------------
|
||||
|
||||
You may pick any name for your git branch names. By default, it will
|
||||
be reused as the topic for your change in Gerrit::
|
||||
|
||||
git checkout -b TOPIC-BRANCH
|
||||
|
||||
Committing a Change
|
||||
-------------------
|
||||
Best practices recommend, if you are working on a specific blueprint, to
|
||||
name your topic branch ``bp/BLUEPRINT`` where BLUEPRINT is
|
||||
the name of a blueprint in Launchpad (for example,
|
||||
``bp/authentication``). The general convention when working on bugs
|
||||
is to name the branch ``bug/BUG-NUMBER`` (for example,
|
||||
``bug/1234567``).
|
||||
|
||||
If you want to use a different gerrit topic name from the git branch name,
|
||||
you can use the following command to submit your change::
|
||||
|
||||
git review -t TOPIC
|
||||
|
||||
|
||||
Committing changes
|
||||
------------------
|
||||
|
||||
`Git commit messages
|
||||
<https://wiki.openstack.org/wiki/GitCommitMessages>`_ should start
|
||||
|
||||
156
doc/source/gettingstarted.rst
Normal file
156
doc/source/gettingstarted.rst
Normal file
@ -0,0 +1,156 @@
|
||||
: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
|
||||
|
||||
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`.
|
||||
@ -27,6 +27,7 @@ any project hosted in the OpenDev infrastructure.
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
gettingstarted
|
||||
developers
|
||||
irc
|
||||
core
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user