From: C.J. Collier Date: Fri, 16 Feb 2018 21:55:55 +0000 (-0800) Subject: Documentation on the topic of pushing patches X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=commitdiff_plain;h=15ec5369c5862f0bcf3119e6661e233c940aabbf;p=releng%2Fdocs.git Documentation on the topic of pushing patches docs/gerrit.rst - How to push a new patch [RELENG-557] - How to update an existing patch [RELENG-558] Change-Id: I84522e25c9f5f65a063f782bfe27b64cf80fd616 Signed-off-by: C.J. Collier Co-Authored-By: Jessica Wagantall --- diff --git a/docs/_static/commit-hook.example b/docs/_static/commit-hook.example new file mode 100644 index 0000000..32df5f0 --- /dev/null +++ b/docs/_static/commit-hook.example @@ -0,0 +1,2 @@ + git clone ssh://USERNAME@gerrit.linuxfoundation.org:29418/releng/docs + scp -p -P 29418 USERNAME@gerrit.linuxfoundation.org:hooks/commit-msg docs/.git/hooks/ diff --git a/docs/_static/push-success.example b/docs/_static/push-success.example new file mode 100644 index 0000000..f35fbd8 --- /dev/null +++ b/docs/_static/push-success.example @@ -0,0 +1,8 @@ + (releng) cjac@probook0:/usr/src/git/lf/gerrit.linuxfoundation.org/releng/docs$ git review + remote: Processing changes: updated: 1, refs: 1, done + remote: + remote: Updated Changes: + remote: https://gerrit.linuxfoundation.org/infra/7404 documentation on the topic of git-review + remote: + To ssh://gerrit.linuxfoundation.org:29418/releng/docs.git + * [new branch] HEAD -> refs/publish/master/git-review-docs diff --git a/docs/gerrit.rst b/docs/gerrit.rst index b8843c0..c3c1765 100644 --- a/docs/gerrit.rst +++ b/docs/gerrit.rst @@ -19,11 +19,13 @@ How to clone code ================= 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 --------- @@ -43,39 +45,56 @@ In such case, use HTTPS. 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:: @@ -93,23 +112,140 @@ Both SSH and HTTP clone options have a clone with commit-msg hook which adds 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 `_. + +#. 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 HEAD:refs/for/master + +.. note:: + + Where 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/" 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 . -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 =================