=================
Cloning the code into a local workspace can happen via HTTP or SSH.
-Make sure your Gerrit settings are up to date with correct SSH and GPG keys.
-In the project's Gerrit instance, we can see the HTTP and SSH commands for
-cloning any particular repo after browsing for a project. From the left side
-menu, select Projects->List->Select any project or use the filter->General.
+#. Make sure your Gerrit settings are up to date with correct SSH and GPG keys.
+
+#. In the project's Gerrit instance, we can see the HTTP and SSH commands. From
+ the left side menu, select Projects->List->Select any project->General.
+
+#. Copy the desired clone command and paste it in your terminal.
SSH Clone
---------
The SSH clone option will not appear if the settings are not updated with
the correct SSH keys.
-For example:
+#. Browse for the project's General information.
+
+#. Click on the ssh tab.
-.. code-block:: bash
+#. Clone desired repo. For example:
- git clone ssh://jwagantall@gerrit.onap.org:29418/aaf/inno
+ .. code-block:: bash
-Since we are constantly working on uploading new code into the
-repositories, we recommend to use SSH clones since the remotes for
-pushing code get configured appropriately.
+ git clone ssh://USERNAME@gerrit.linuxfoundation.org:29418/releng/docs
+
+ .. note::
+
+ Since we are constantly working on uploading new code into the
+ repositories, we recommend to use SSH clones since the remotes for
+ pushing code get configured appropriately.
Anonymous HTTP Clone
--------------------
Recommended if the intention is to view code and not make any contributions:
-For example:
-.. code-block:: bash
+#. Browse the project and click ``Gerneal``
+
+#. Click ``anonymous http`` tab.
+
+#. Clone desired repo. For example:
+
+ .. code-block:: bash
- git clone https://gerrit.linuxfoundation.org/releng/docs
+ git clone https://gerrit.linuxfoundation.org/releng/docs
Authenticated HTTP Clone
------------------------
This works everywhere, even behind a proxy or a firewall.
-For example:
-.. code-block:: bash
+#. Get the password by clicking on the username on the top right->Settings->
+ HTTP Password->Generate Password
- git clone https://USERNAME@gerrit.onap.org/r/a/aaf/inno
+#. Browse for the project and click ``General``.
-This command will request a username and password. The username needs to match
-the one set up in the Profile under Settings. Use the password from the Settings
-under HTTP Password->Generate Password.
+#. Click ``http`` tab.
+
+#. Clone desired repo. For example:
+
+ .. code-block:: bash
+
+ git clone https://USERNAME@gerrit.linuxfoundation.org/infra/a/releng/docs
+
+#. Follow the user/password prompts.
.. note::
a hook for adding a new Change-Id as part of the footer of any new commit to
be able to post in Gerrit.
-This command is under Projects->List->Select any project or use the filter->
-General->Clone with commit-msg hook.
+#. Browse for the project and click ``General``.
+
+#. Click ``Clone with commit-msg hook``. For example:
+
+ .. literalinclude:: _static/commit-hook.example
+ :language: bash
+
+ .. note::
+
+ The hook implementation is intelligent at inserting the Change-Id line before
+ any Signed-off-by or Acked-by lines placed at the end of the commit message by
+ the author, but if no lines are present then it will insert a blank line, and
+ add the Change-Id at the bottom of the message.
+
+ If a Change-Id line is already present in the message footer, the script will do
+ nothing, leaving the existing Change-Id unmodified. This permits amending an existing
+ commit, or allows the user to insert the Change-Id manually after copying it from
+ an existing change viewed on the web.
+
+#. (Optional). To prevent the Change-Id addition, set gerrit.createChangeId to false in the
+ git config.
+
+Push patches to Gerrit
+======================
+
+Linux Foundation Release Engineers manage patches to the source code
+comprising their work on Gerrit servers using a client tool called
+`git-review <https://docs.openstack.org/infra/git-review/>`_.
+
+#. Install this tool either using the local package management system (ie, yum,
+ apt-get, zypper, etc.) or preferably using pip within a virtualenv:
+
+ .. code-block:: bash
+
+ pip install git-review
+
+#. Flatten all changes to a single git commit. Once the change is ready
+ for review, commit it locally with the '-s' argument:
+
+ .. code-block:: bash
+
+ git commit -s
+
+Pushing using git review
+------------------------
+
+#. After making the signed local commit, submit the change to Gerrit for review,
+ optionally specifying a topic with the '-t' argument in the following command:
+
+ .. code-block:: bash
+
+ git review -t my_topic
+
+Pushing using git push
+----------------------
+
+This is a more specific command.
+
+#. Use the following command:
+
+ .. code-block:: bash
+
+ git push <remote> HEAD:refs/for/master
+
+.. note::
+
+ Where <remote> is the current branch’s remote (or origin, if no remote
+ configuration exists for the current branch).
+
+.. note::
+
+ Notice the word "for" is explicitly intending to perform the push into Gerrit.
+ Using "heads" instead, will attempt to make the a push into the repository bypassing
+ Gerrit which can come in handy for some isolated cases (when having force push rights).
+ Another variable commonly used is "refs/changes/<gerrit-number>" which is an explicit
+ way of making an update to an exisiting gerrit. In such case, is best to let gerrit handle
+ this via Change-Id in the commit text.
+
+ More options for this command: `git-push https://git-scm.com/docs/git-push`_.
+
+Push output
+-----------
+
+The output of this command will, when successful, include a link to a
+web page where peers will then perform the review. For example:
+
+.. literalinclude:: _static/push-success.example
+ :language: bash
+
+Update an existing patch
+========================
+
+#. On your machine, open a shell and switch to the directory containing the repository. Then
+ download the patch you want to update:
+
+ .. code-block:: bash
+
+ git review -d ${change_number}
+
+ (Optional) View information on the latest changes made to that patch:
+ To view the edited files, run
+
+ .. code-block:: bash
+
+ git show
+
+#. To view a listing of the edited files and the number of lines in those files, run:
+
+ .. code-block:: bash
+
+ git show --stat
+
+#. Make the necessary changes to the patch’s files and commit your changes using:
+
+ .. code-block:: bash
+
+ git commit -a --amend
+
+#. Update the current patch description and then save the commit request.
+
+ .. note::
+
+ If you feel as though you added enough work on the patch, add your name in
+ the footer with a line like Co-Authored-By: First Last <email>.
-The hook will edit any commit message adding a "Change-Id:" line in the footer.
+#. Submit your files for review:
-The hook implementation is intelligent at inserting the Change-Id line before
-any Signed-off-by or Acked-by lines placed at the end of the commit message by
-the author, but if no lines are present then it will insert a blank line, and
-add the Change-Id at the bottom of the message.
+ .. code-block:: bash
-If a Change-Id line is already present in the message footer, the script will do
-nothing, leaving the existing Change-Id unmodified. This permits amending an existing
-commit, or allows the user to insert the Change-Id manually after copying it from
-an existing change viewed on the web.
+ git review
-To prevent the Change-Id addition, set gerrit.createChangeId to false in the
-git config.
+You will receive 2 emails from Gerrit Code Review: the first indicating that a build
+to incorporate your changes has started; and the second indicating the creation of the
+build.
Setting up Gerrit
=================
Code Review / releng / docs.git / commitdiff