From 1ca0419bce0cd7278e866771e34422eb2640229f Mon Sep 17 00:00:00 2001 From: Thierry Carrez Date: Mon, 30 Mar 2020 15:51:12 +0200 Subject: [PATCH] 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 --- doc/source/developers.rst | 225 +++++++--------------------------- doc/source/gettingstarted.rst | 156 +++++++++++++++++++++++ doc/source/index.rst | 1 + 3 files changed, 201 insertions(+), 181 deletions(-) create mode 100644 doc/source/gettingstarted.rst 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 -`_, 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 `_. -Upload your public SSH key -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You'll also want to `upload an SSH key to Gerrit -`_ 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 `_ 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 -`_ 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 `_:: - - pip install git-review - -If you run into trouble, you can refer to the `git-review documentation -`_. - -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// - -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 - 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 `_ 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 -`_ -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 `_ 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 `_ to use it. +This account will also allow you to use `Launchpad `_, +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 +`_. + +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 `_ 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 `_. + +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 `_:: + + 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// + cd + +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 +`_ +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