michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc : gerrit_pracitces : fix line lengths

Browse source 
gerrit_practices.rst has style and formatting issues.  Bringing them back
in line with the recommended practices of the project.

Change-Id: If76406e046ab376cea3e14c0e490e38587b34e6d
Signed-off-by: Dan Kalowsky <daniel.kalowsky@intel.com>
This commit is contained in:
Dan Kalowsky 2016-02-05 09:19:13 -08:00 • committed by Anas Nashif
commit 58d39653dc
1 changed files with 77 additions and 55 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -3,16 +3,19 @@
Gerrit Recommended Practices
############################
This document presents some best practices to help you use Gerrit more effectively.
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.
This document presents some best practices to help you use Gerrit more
effectively. 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 appropriately.
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 appropriately.
.. _Gerrit: http://oic-review.01.org/gerrit/
@ -26,9 +29,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.
@ -39,8 +42,8 @@ format and content expected in a commit message:::
Signed-off-by: Your Name your.email@example.org
AnotherExampleHeader: An Example of another Value
The Gerrit server provides a precommit hook to autogenerate the Change-Id which is one time use.
Use the following command as an example:
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:: console
@ -64,8 +67,10 @@ To avoid pushing untested work to Gerrit, we recommend you follow these steps:
$ 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 :literal:`checkarray` with keywords that might signal danger in your commits.
Follow the installation instructions in the :file:`README.rst` for
checkpatch.
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
@ -79,9 +84,13 @@ 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 if you comment on a specific Patch Set.
* Opening a change in Gerrit's review interface is a quick way to follow that change.
- Gerrit will subscribe you to the mailing list created for that change if a
developer adds you 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*.
@ -101,8 +110,8 @@ Emails contain some helpful headers for filtering:
- Autobuilders usually look like ``sys_EXAMPLE@intel.com``
Always track the projects you are working on; also see the feedback/comments mailing list
to learn and help others ramp up.
Always track the projects you are working on; also see the feedback/comments
mailing list to learn and help others ramp up.
Topic branches
@ -111,21 +120,23 @@ Topic branches
Topic branches are temporary branches that you push to commit a set of
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:
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:: console
$ git push REMOTE HEAD:refs/for/master/TopicName
The topic will show up in the review :abbr:`UI` and in the :guilabel:`Open Changes List`.
Topic branches will disappear from the master tree when its content is merged.
The topic will show up in the review :abbr:`UI` and in the
:guilabel:`Open Changes List`. Topic branches will disappear from the master
tree when its content is merged.
Creating a Cover Letter for a Topic
===================================
You may decide whether or not you'd like the cover letter to appear in the history.
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:
@ -138,7 +149,7 @@ 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.
without having to rebase.
* Now add your commits
.. code-block:: console
@ -147,15 +158,16 @@ The command used doesn't change any files in the source tree.
$ git commit ...
$ git commit ...
* Finally, push the commits to a topic branch. The following command is an example:
* Finally, push the commits to a topic branch. The following command is an
example:
.. 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 on the list. Use the following
command as an example:
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
on the list. Use the following command as an example:
.. code-block:: console
@ -174,7 +186,8 @@ Finding Available Topics
| grep topic: | sort -u
* *oic-review.01.org* Is the current URL where the project is hosted
* *status* Indicates the topic's current status: open , merged, abandoned, draft, merge conflict.
* *status* Indicates the topic's current status: open , merged, abandoned,
draft, merge conflict.
* *project* Refers to the current name of the project, in this case forto-collab
* *branch* The topic is searched at this branch.
* *topic* The name of an specific topic, leave it blank to include them all.
@ -183,8 +196,8 @@ Finding Available Topics
Downloading or Checking Out a Change
************************************
In the review UI, on the top right corner, the **Download** link provides a list of commands and
hyperlinks to checkout or download diffs or files.
In the review UI, on the top right corner, the **Download** link provides a
list of commands and hyperlinks to checkout or download diffs or files.
We recommend the use of the *git review* plugin.
The steps to install git review are beyond the scope of this document.
@ -198,13 +211,15 @@ To check out a specific change using Git, the following command usually works:
$ git review -d CHANGEID
If you don't have Git-review installed, the following commands will do the same thing:
If you don't have Git-review installed, the following commands will do the same
thing:
.. 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):
For example, for the 4th version of change 2464, NN is the first two digits
(24):
.. code-block:: console
@ -214,8 +229,8 @@ 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 specific reviewers before you publishing your change.
The Draft Branches are pushed to :file:`refs/drafts/master/TopicName`
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:
@ -235,8 +250,8 @@ The next command pushes your change to the drafts branch under **TopicName**:
Using Sandbox Branches
**********************
You can create your own branches to develop features. 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.
These commands ensure the branch is created in Gerrit's server.
@ -272,11 +287,13 @@ You can also push forcibly with review
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:
For example, there is a list of commits, **c0...c7**, which were submitted as a
topic branch:
.. code-block:: console
@ -288,17 +305,18 @@ For example, there is a list of commits, **c0...c7**, which were submitted as a
$ git push REMOTE HEAD:refs/for/master/SOMETOPIC
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:
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:: 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 permitted to add more commits when pushing new versions.
@ -307,8 +325,8 @@ It is also permitted to add more commits when pushing new versions.
Rebasing
********
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.
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.
@ -325,10 +343,11 @@ For more information you can visit `Atlasian`_ , `git book`_ and `git rebase`_.
Rebasing During a Pull
**********************
Before pushing a rebase to your master, ensure that the history has a consecutive order.
Before pushing a rebase to your master, ensure that the history has a
consecutive order.
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:
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:: console
@ -368,7 +387,8 @@ This pulls **a5-a7** and re-apply **c0-c7** on top of them:
Getting Better Logs from Git
****************************
Use these commands to change the configuration of Git in order to produce better logs:
Use these commands to change the configuration of Git in order to produce better
logs:
.. code-block:: console
@ -380,13 +400,15 @@ The command above sets the log to abbreviate the commits' hash.
$ git config log.abbrev 5
The command above sets the abbreviation length to the last 5 characters of the hash.
The command above sets the abbreviation length to the last 5 characters of the
hash.
.. code-block:: console
$ git config format.pretty oneline
The command above avoids the insertion of an unnecessary line before the Author line.
The command above avoids the insertion of an unnecessary line before the Author
line.
To make these configuration changes specifically for the current Git user,
you must add the path option :option:`–-global` to :command:`config` as follows:
@ -395,4 +417,4 @@ you must add the path option :option:`–-global` to :command:`config` as follow
$ git config –-global log.abbrevCommit true
$ git config –-global log.abbrev 5
$ git config –-global format.pretty oneline
$ git config –-global format.pretty oneline