diff --git a/doc/source/developers.rst b/doc/source/developers.rst
index 24ba315..1f88780 100644
--- a/doc/source/developers.rst
+++ b/doc/source/developers.rst
@@ -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
diff --git a/doc/source/gettingstarted.rst b/doc/source/gettingstarted.rst
new file mode 100644
index 0000000..6b93b2f
--- /dev/null
+++ b/doc/source/gettingstarted.rst
@@ -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`.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index c6ddba2..3d0028d 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -27,6 +27,7 @@ any project hosted in the OpenDev infrastructure.
.. toctree::
:maxdepth: 2
+ gettingstarted
developers
irc
core