michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: change bash to console refs

Browse source 
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:
L.S. Cook 2015-10-08 14:33:49 -07:00 • committed by Anas Nashif
commit 1f901bd491
1 changed files with 72 additions and 67 deletions
Download patch file Download diff file Expand all files Collapse all files

139
doc/collaboration/code/gerrit_practices.rst
View file

@ -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