doc: change bash to console refs
Also: fixed trailing whitespaces. Also: integrated comment change suggestions from GA Change-Id: I41f7052d9895e0c61ad0e76be989ea6161f9ed83 Signed-off-by: L.S. Cook <leonax.cook@intel.com>
This commit is contained in:
parent
c98560f783
commit
1f901bd491
1 changed files with 72 additions and 67 deletions
|
@ -4,16 +4,15 @@ Gerrit Recommended Practices
|
|||
############################
|
||||
|
||||
This document presents some best practices to help you use Gerrit more effectively.
|
||||
The intent is to provide you information about submitting content in an easier way.
|
||||
Use the recommended practices to reduce your troubleshooting time and improve your participation
|
||||
within the community.
|
||||
The intent is to show how content can be submitted easily. Use the recommended practices
|
||||
to reduce your troubleshooting time and improve participation in the community.
|
||||
|
||||
Browsing the Git Tree
|
||||
*********************
|
||||
|
||||
Visit `Gerrit`_, then select :menuselection:`Projects --> List --> SELECT-PROJECT --> Branches`.
|
||||
Select the branch that interests you, click on :guilabel:`gitweb` located on the right hand side.
|
||||
Now, :program:`gitweb` loads your selection on the Git web interface and redirects you.
|
||||
Select the branch that interests you, click on :guilabel:`gitweb` located on the right-hand side.
|
||||
Now, :program:`gitweb` loads your selection on the Git web interface and redirects appropriately.
|
||||
|
||||
.. _Gerrit: http://oic-review.01.org/gerrit/
|
||||
|
||||
|
@ -27,9 +26,9 @@ Select :guilabel:`Watched Projects` and then add any projects that interest you.
|
|||
Commit Messages
|
||||
***************
|
||||
|
||||
Gerrit follows the Git commit message format.
|
||||
Ensure the headers are at the bottom and don't contain blank lines between one another.
|
||||
The following example shows the format and content expected in a commit message:::
|
||||
Gerrit follows the Git commit message format. Ensure the headers are at the bottom
|
||||
and don't contain blank lines between one another. The following example shows the
|
||||
format and content expected in a commit message:::
|
||||
|
||||
Subsystem: Brief one line description.
|
||||
|
||||
|
@ -43,11 +42,11 @@ The following example shows the format and content expected in a commit message:
|
|||
The Gerrit server provides a precommit hook to autogenerate the Change-Id which is one time use.
|
||||
Use the following command as an example:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ scp -p -P 29418 GERRIT-SERVER:hooks/commit-msg REPODIR/.git/hooks/
|
||||
|
||||
You just need to enter the command above one time.
|
||||
The command above needs to be entered only once.
|
||||
|
||||
|
||||
Avoid Pushing Untested Work to a Gerrit Server
|
||||
|
@ -55,18 +54,18 @@ Avoid Pushing Untested Work to a Gerrit Server
|
|||
|
||||
To avoid pushing untested work to Gerrit, we recommend you follow these steps:
|
||||
|
||||
1. Make the leak difficult to occur:
|
||||
1. Rename your tree:
|
||||
|
||||
- Change the name of the remote Git tree from *origin* to *another name*.
|
||||
This complicates unintentionally pushing work to Gerrit.
|
||||
This prevents complications when work is unintentionally pushed to Gerrit.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git remote rename origin another-name
|
||||
|
||||
- Use `precommit hooks`_ to scan for problematic words in your commit.
|
||||
Follow the installation instructions in the :file:`README.rst` for check patch.
|
||||
Update the checkarray with keywords that might signal danger in your commits.
|
||||
Update the :literal:`checkarray` with keywords that might signal danger in your commits.
|
||||
|
||||
.. _precommit hooks: https://github.com/niden/Git-Pre-Commit-Hook-for-certain-words
|
||||
|
||||
|
@ -81,8 +80,8 @@ Keeping Track of Changes
|
|||
* Set Gerrit to send you email:
|
||||
|
||||
- Gerrit will subscribe you to the mailing list created for that change if a developer adds you
|
||||
as a reviewer or you comment on a specific Patch Set.
|
||||
* Opening a change in Gerrit's review interface is as a quick way to follow that change.
|
||||
as a reviewer, or if you comment on a specific Patch Set.
|
||||
* Opening a change in Gerrit's review interface is a quick way to follow that change.
|
||||
* Watch projects in the Gerrit projects section at `Gerrit`_, select at least
|
||||
*New Changes, New Patch Sets, All Comments* and *Submitted Changes*.
|
||||
|
||||
|
@ -110,12 +109,12 @@ Topic branches
|
|||
**************
|
||||
|
||||
Topic branches are temporary branches that you push to commit a set of
|
||||
logically grouped dependent commits:
|
||||
logically-grouped dependent commits:
|
||||
|
||||
To push changes from :file:`REMOTE/master` tree to Gerrit for being reviewed as a topic
|
||||
in **TopicName** use the following command as an example:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git push REMOTE HEAD:refs/for/master/TopicName
|
||||
|
||||
|
@ -126,11 +125,11 @@ Topic branches will disappear from the master tree when its content is merged.
|
|||
Creating a Cover Letter for a Topic
|
||||
===================================
|
||||
|
||||
You might decide if you want the cover letter to appear in the history or not.
|
||||
You may decide whether or not you'd like the cover letter to appear in the history.
|
||||
|
||||
1. To make a cover letter that appears in the history, use this command:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git commit --allow-empty
|
||||
|
||||
|
@ -138,26 +137,27 @@ Edit the commit message, this message then becomes the cover letter.
|
|||
The command used doesn't change any files in the source tree.
|
||||
|
||||
2. To make a cover letter that doesn't appear in the history follow these steps:
|
||||
Put the empty commit at the end of your commits list so it can be ignored
|
||||
without having to rebase. Now add your commits
|
||||
* Put the empty commit at the end of your commits list so it can be ignored
|
||||
without having to rebase.
|
||||
* Now add your commits
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git commit ...
|
||||
$ git commit ...
|
||||
$ git commit ...
|
||||
|
||||
Then push the commits to a topic branch, use the following command as an example:
|
||||
* Finally, push the commits to a topic branch. The following command is an example:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git push REMOTE HEAD:refs/for/master/TopicName
|
||||
|
||||
If you already have commits but you want to set a cover letter, create an empty commit for
|
||||
the cover letter and move the commit so it becomes the last commit of the list. Use the following
|
||||
the cover letter and move the commit so it becomes the last commit on the list. Use the following
|
||||
command as an example:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git rebase -i HEAD~#Commits
|
||||
|
||||
|
@ -168,7 +168,7 @@ Be careful to uncomment the commit before moving it.
|
|||
Finding Available Topics
|
||||
========================
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ ssh -p 29418 oic-review.01.org gerrit query \ status:open project:forto-collab branch:master \
|
||||
| grep topic: | sort -u
|
||||
|
@ -192,21 +192,21 @@ Refer to the `git review documentation`_ for the installation process.
|
|||
|
||||
.. _git review documentation: https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers
|
||||
|
||||
In general, to check out the change using Git use the following command:
|
||||
To check out a specific change using Git, the following command usually works:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git review -d CHANGEID
|
||||
|
||||
If you don't have Git-review installed use the following commands:
|
||||
If you don't have Git-review installed, the following commands will do the same thing:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD
|
||||
|
||||
For example, for the 4th version of change 2464, NN is 24 (the first two digits):
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD
|
||||
|
||||
|
@ -214,19 +214,19 @@ For example, for the 4th version of change 2464, NN is 24 (the first two digits)
|
|||
Using Draft Branches
|
||||
********************
|
||||
|
||||
You can use draft branches to add certain reviewers before you publish your change.
|
||||
You can use draft branches to add specific reviewers before you publishing your change.
|
||||
The Draft Branches are pushed to :file:`refs/drafts/master/TopicName`
|
||||
|
||||
The next command ensures a local branch is created:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git checkout -b BRANCHNAME
|
||||
|
||||
|
||||
The next command pushes your change to the drafts branch under **TopicName**:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git push REMOTE HEAD:refs/drafts/master/TopicName
|
||||
|
||||
|
@ -235,46 +235,50 @@ The next command pushes your change to the drafts branch under **TopicName**:
|
|||
Using Sandbox Branches
|
||||
**********************
|
||||
|
||||
You can create your own branches for features development.
|
||||
The branches are pushed to the :file:`refs/sandbox/USERNAME/BRANCHNAME` location.
|
||||
You can create your own branches to develop features. The branches are pushed to the
|
||||
:file:`refs/sandbox/USERNAME/BRANCHNAME` location.
|
||||
|
||||
The next commands ensures the branch is created in Gerrit's server.
|
||||
These commands ensure the branch is created in Gerrit's server.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git checkout -b sandbox/USERNAME/BRANCHNAME
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git push --set-upstream REMOTE HEAD:refs/heads/sandbox/USERNAME/BRANCHNAME
|
||||
|
||||
Usually, the process to create content is: develop the code, break the information
|
||||
into small commits, then submit changes, apply feedback and finally, rebase.
|
||||
Usually, the process to create content is:
|
||||
|
||||
* develop the code,
|
||||
* break the information into small commits,
|
||||
* submit changes,
|
||||
* apply feedback,
|
||||
* rebase.
|
||||
|
||||
The next command pushes forcibly without review
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git push REMOTE sandbox/USERNAME/BRANCHNAME
|
||||
|
||||
You can also push forcibly with review
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME
|
||||
|
||||
|
||||
Updating the Versions of a Change
|
||||
Updating the Version of a Change
|
||||
*********************************
|
||||
|
||||
During the review process, you might be asked to update your change.
|
||||
It is possible to submit multiple versions of the same change.
|
||||
Each version of the change is called a patch set.
|
||||
During the review process, you might be asked to update your change. It is possible to submit
|
||||
multiple versions of the same change. Each version of the change is called a patch set.
|
||||
|
||||
Always maintain the **Change-Id** that was assigned.
|
||||
For example, there is a list of commits, **c0...c7**, which were submitted as a topic branch:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git log REMOTE/master..master
|
||||
|
||||
|
@ -284,27 +288,27 @@ For example, there is a list of commits, **c0...c7**, which were submitted as a
|
|||
|
||||
$ git push REMOTE HEAD:refs/for/master/SOMETOPIC
|
||||
|
||||
Now, you get reviewers' feedback and there are changes in **c3** and **c4** that must be fixed.
|
||||
After you get reviewers' feedback, there are changes in **c3** and **c4** that must be fixed.
|
||||
If the fix requires rebasing, rebasing changes the commit Ids, see the :ref:`rebasing` section
|
||||
for more information. However, you must keep the same Change-Id and push the changes again:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git push REMOTE HEAD:refs/for/master/SOMETOPIC
|
||||
|
||||
This new push creates a patches revision, your local history is then cleared.
|
||||
However you can still access the history of your changes in Gerrit on the :guilabel:`review UI`
|
||||
section, for each change.
|
||||
This new push creates a patches revision, your local history is then cleared. However you can
|
||||
still access the history of your changes in Gerrit on the :guilabel:`review UI` section, for each
|
||||
change.
|
||||
|
||||
It is also allowed to add more commits when pushing new versions.
|
||||
It is also permitted to add more commits when pushing new versions.
|
||||
|
||||
.. _rebasing:
|
||||
|
||||
Rebasing
|
||||
********
|
||||
|
||||
Usually rebasing is the last step before pushing changes to Gerrit,
|
||||
this allows you to make the necessary *Change-Ids*. The *Change-Ids* must be kept the same.
|
||||
Rebasing is usually the last step before pushing changes to Gerrit; this allows you to make the
|
||||
necessary *Change-Ids*. The *Change-Ids* must be kept the same.
|
||||
|
||||
* **squash:** mixes two or more commits into a single one.
|
||||
* **reword:** changes the commit message.
|
||||
|
@ -326,7 +330,7 @@ Before pushing a rebase to your master, ensure that the history has a consecutiv
|
|||
For example, your :file:`REMOTE/master` has the list of commits from **a0** to **a4**;
|
||||
Then, your changes **c0...c7** are on top of **a4**; thus:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git log --oneline REMOTE/master..master
|
||||
|
||||
|
@ -340,16 +344,17 @@ Then, your changes **c0...c7** are on top of **a4**; thus:
|
|||
...
|
||||
c7
|
||||
|
||||
If :file:`REMOTE/master` receives commits **a5**,** a6** and **a7**. Pull with a rebase as follows:
|
||||
If :file:`REMOTE/master` receives commits **a5**, **a6** and **a7**. Pull with a
|
||||
rebase as follows:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git pull --rebase REMOTE master
|
||||
|
||||
This pulls **a5-a7** and re-apply **c0-c7** on top of them:
|
||||
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git log --oneline REMOTE/master..master
|
||||
a0
|
||||
|
@ -360,24 +365,24 @@ This pulls **a5-a7** and re-apply **c0-c7** on top of them:
|
|||
...
|
||||
c7
|
||||
|
||||
Getting better Logs from Git
|
||||
Getting Better Logs from Git
|
||||
****************************
|
||||
|
||||
Use these commands to change the configuration of Git in order to produce better logs:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git config log.abbrevCommit true
|
||||
|
||||
The command above sets the log to abbreviate the commits' hash.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git config log.abbrev 5
|
||||
|
||||
The command above sets the abbreviation length to the last 5 characters of the hash.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git config format.pretty oneline
|
||||
|
||||
|
@ -386,7 +391,7 @@ The command above avoids the insertion of an unnecessary line before the Author
|
|||
To make these configuration changes specifically for the current Git user,
|
||||
you must add the path option :option:`–-global` to :command:`config` as follows:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ git config –-global log.abbrevCommit true
|
||||
$ git config –-global log.abbrev 5
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue