diff --git a/docs/source/CONTRIBUTING.rst b/docs/source/CONTRIBUTING.rst index 37391b624c..e08372d942 100644 --- a/docs/source/CONTRIBUTING.rst +++ b/docs/source/CONTRIBUTING.rst @@ -13,7 +13,7 @@ Getting a Linux Foundation account In order to participate in the development of the Hyperledger Fabric project, you will need a `Linux Foundation -account `__. You will need to use your LF ID to +account `__. You will need to use your LF ID to access to all the Hyperledger community development tools, including `Gerrit `__, `Jira `__ and the @@ -25,7 +25,7 @@ Setting up your SSH key For Gerrit, before you can submit any change set for review, you will need to register your public SSH key. Login to `Gerrit `__ with your -`LFID `__, and click on your name in the upper +`LFID `__, and click on your name in the upper right-hand corner of your browser window and then click 'Settings'. In the left-hand margin, you should see a link for 'SSH Public Keys'. Copy-n-paste your `public SSH @@ -87,18 +87,18 @@ Working with a local clone and Gerrit We are using `Gerrit `__ to manage code contributions. If you are unfamiliar, please review this -`document `__ before proceeding. +`document `__ before proceeding. After you have familiarized yourself with ``Gerrit``, and maybe played around with the ``lf-sandbox`` `project `__, you should be ready to set up your local development -`environment `__. +`environment `__. -Next, try `building the project `__ in your local +Next, try `building the project `__ in your local development environment to ensure that everything is set up correctly. -`Logging control `__ describes how to tweak +`Logging control `__ describes how to tweak the logging levels of various components within the Fabric. Finally, every source file needs to include a `license header `__: modified to include a copyright @@ -186,7 +186,7 @@ Coding guidelines ----------------- Be sure to check out the language-specific `style -guides `__ before making any changes. This +guides `__ before making any changes. This will ensure a smoother review. Communication @@ -202,7 +202,7 @@ list `__. Maintainers ----------- -The project's `maintainers `__ are responsible for +The project's `maintainers `__ are responsible for reviewing and merging all patches submitted for review and they guide the over-all technical direction of the project within the guidelines established by the Hyperledger Project's Technical Steering Committee @@ -218,7 +218,7 @@ designate an initial set of maintainers that will be approved by the top-level project's existing maintainers when the project is first approved. The project's maintainers will, from time-to-time, consider adding or removing a maintainer. An existing maintainer can submit a -change set to the `MAINTAINERS.md `__ file. If there are +change set to the `MAINTAINERS.rst `__ file. If there are less than eight maintainers, a majority of the existing maintainers on that project are required to merge the change set. If there are more than eight existing maintainers, then if five or more of the maintainers diff --git a/docs/source/Gerrit/best-practices.md b/docs/source/Gerrit/best-practices.md deleted file mode 100644 index 1e15b6f5aa..0000000000 --- a/docs/source/Gerrit/best-practices.md +++ /dev/null @@ -1,337 +0,0 @@ -# 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. - -## Browsing the Git Tree - -Visit [Gerrit](https://gerrit.hyperledger.org/r/#/admin/projects/fabric) then -select `Projects --> List --> SELECT-PROJECT --> Branches`. Select the branch -that interests you, click on `gitweb` located on the right-hand side. Now, -`gitweb` loads your selection on the Git web interface and redirects -appropriately. - -## Watching a Project - -Visit [Gerrit](https://gerrit.hyperledger.org/r/#/admin/projects/fabric), then -select `Settings`, located on the top right corner. Select `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: - - Brief (no more than 50 chars) one line description. - - Elaborate summary of the changes made referencing why (motivation), what was -changed and how it was tested. Note also any changes to documentation made to -remain consistent with the code changes, wrapping text at 72 chars/line. - - Jira: FAB-100 - Change-Id: LONGHEXHASH - 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. - -**Recommended reading:** [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/) - -## Avoid Pushing Untested Work to a Gerrit Server - -To avoid pushing untested work to Gerrit. - -Check your work at least three times before pushing your change to Gerrit. -Be mindful of what information you are publishing. - -## Keeping Track of Changes - -- Set Gerrit to send you emails: - - - Gerrit will add you to the email distribution list for a 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*. - -Always track the projects you are working on; also see the feedback/comments -mailing list to learn and help others ramp up. - -## Topic branches - -Topic branches are temporary branches that you push to commit a set of -logically-grouped dependent commits: - -To push changes from `REMOTE/master` tree to Gerrit for being reviewed as -a topic in **TopicName** use the following command as an example: - - $ git push REMOTE HEAD:refs/for/master/TopicName - -The topic will show up in the review :abbr:`UI` and in the -`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. - -1. To make a cover letter that appears in the history, use this command: - -``` -git commit --allow-empty -``` - -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 - -``` -git commit ... -git commit ... -git commit ... -``` - - - Finally, push the commits to a topic branch. The following command is an - example: - -``` -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: - -``` -git rebase -i HEAD~#Commits -``` - -Be careful to uncomment the commit before moving it. -`#Commits` is the sum of the commits plus your new cover letter. - - -## Finding Available Topics - -``` - $ ssh -p 29418 gerrit.hyperledger.org gerrit query \ status:open project:fabric branch:master \ - | grep topic: | sort -u -``` - -- [gerrit.hyperledger.org]() Is the current URL where the project is hosted. -- *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 fabric. -- *branch* The topic is searched at this branch. -- *topic* The name of an specific topic, leave it blank to include them all. -- *sort* Sorts the found topics, in this case by update (-u). - -## 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. - -We recommend the use of the *git review* plugin. -The steps to install git review are beyond the scope of this document. -Refer to the [git review documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers) for the installation process. - -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: - -``` -git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD -``` - -For example, for the 4th version of change 2464, NN is the first two digits -(24): - -``` -git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD -``` - -## Using Draft Branches - -You can use draft branches to add specific reviewers before you publishing your -change. The Draft Branches are pushed to `refs/drafts/master/TopicName` - -The next command ensures a local branch is created: - -``` -git checkout -b BRANCHNAME -``` - -The next command pushes your change to the drafts branch under **TopicName**: - -``` -git push REMOTE HEAD:refs/drafts/master/TopicName -``` - -## Using Sandbox Branches - -You can create your own branches to develop features. The branches are pushed to -the `refs/sandbox/USERNAME/BRANCHNAME` location. - -These commands ensure the branch is created in Gerrit's server. - -``` -git checkout -b sandbox/USERNAME/BRANCHNAME -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, -- submit changes, -- apply feedback, -- rebase. - -The next command pushes forcibly without review: - -``` -git push REMOTE sandbox/USERNAME/BRANCHNAME -``` - -You can also push forcibly with review: - -``` -git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME -``` - -## 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. - -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: - -``` -git log REMOTE/master..master - -c0 -... -c7 - -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 [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section -for more information. However, you must keep the same Change-Id and push the -changes again: - -``` -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 -`review UI` section, for each change. - -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. - -- **squash:** mixes two or more commits into a single one. -- **reword:** changes the commit message. -- **edit:** changes the commit content. -- **reorder:** allows you to interchange the order of the commits. -- **rebase:** stacks the commits on top of the master. - -## Rebasing During a Pull - -Before pushing a rebase to your master, ensure that the history has a -consecutive order. - -For example, your `REMOTE/master` has the list of commits from **a0** to -**a4**; Then, your changes **c0...c7** are on top of **a4**; thus: - -``` -git log --oneline REMOTE/master..master - -a0 -a1 -a2 -a3 -a4 -c0 -c1 -... -c7 -``` - -If `REMOTE/master` receives commits **a5**, **a6** and **a7**. Pull with a -rebase as follows: - -``` -git pull --rebase REMOTE master -``` - -This pulls **a5-a7** and re-apply **c0-c7** on top of them: - - -``` - $ git log --oneline REMOTE/master..master - a0 - ... - a7 - c0 - c1 - ... - c7 -``` - -## Getting Better Logs from Git - -Use these commands to change the configuration of Git in order to produce better -logs: - -``` -git config log.abbrevCommit true -``` - -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. - -``` -git config format.pretty oneline -``` - -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 `--global` to `config` as follows: diff --git a/docs/source/Gerrit/best-practices.rst b/docs/source/Gerrit/best-practices.rst new file mode 100644 index 0000000000..c8385c9797 --- /dev/null +++ b/docs/source/Gerrit/best-practices.rst @@ -0,0 +1,371 @@ +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. + +Browsing the Git Tree +--------------------- + +Visit +`Gerrit `__ +then select ``Projects --> List --> SELECT-PROJECT --> Branches``. +Select the branch that interests you, click on ``gitweb`` located on the +right-hand side. Now, ``gitweb`` loads your selection on the Git web +interface and redirects appropriately. + +Watching a Project +------------------ + +Visit +`Gerrit `__, +then select ``Settings``, located on the top right corner. Select +``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: + +Brief (no more than 50 chars) one line description. + +Elaborate summary of the changes made referencing why (motivation), what +was changed and how it was tested. Note also any changes to +documentation made to remain consistent with the code changes, wrapping +text at 72 chars/line. + +| Jira: FAB-100 +| Change-Id: LONGHEXHASH +| 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. + +**Recommended reading:** `How to Write a Git Commit +Message `__ + +Avoid Pushing Untested Work to a Gerrit Server +---------------------------------------------- + +To avoid pushing untested work to Gerrit. + +Check your work at least three times before pushing your change to +Gerrit. Be mindful of what information you are publishing. + +Keeping Track of Changes +------------------------ + +- Set Gerrit to send you emails: + +- Gerrit will add you to the email distribution list for a 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*. + +Always track the projects you are working on; also see the +feedback/comments mailing list to learn and help others ramp up. + +Topic branches +-------------- + +Topic branches are temporary branches that you push to commit a set of +logically-grouped dependent commits: + +To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed +as a topic in **TopicName** use the following command as an example: + +$ git push REMOTE HEAD:refs/for/master/TopicName + +The topic will show up in the review :abbr:``UI`` and in the +``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. + +1. To make a cover letter that appears in the history, use this command: + +:: + + git commit --allow-empty + +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 + +:: + + git commit ... + git commit ... + git commit ... + +- Finally, push the commits to a topic branch. The following command is + an example: + +:: + + 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: + +:: + + git rebase -i HEAD~#Commits + +Be careful to uncomment the commit before moving it. ``#Commits`` is the +sum of the commits plus your new cover letter. + +Finding Available Topics +------------------------ + +:: + + $ ssh -p 29418 gerrit.hyperledger.org gerrit query \ status:open project:fabric branch:master \ + | grep topic: | sort -u + +- `gerrit.hyperledger.org <>`__ Is the current URL where the project is + hosted. +- *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 + fabric. +- *branch* The topic is searched at this branch. +- *topic* The name of an specific topic, leave it blank to include them + all. +- *sort* Sorts the found topics, in this case by update (-u). + +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. + +We recommend the use of the *git review* plugin. The steps to install +git review are beyond the scope of this document. Refer to the `git +review +documentation `__ +for the installation process. + +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: + +:: + + git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD + +For example, for the 4th version of change 2464, NN is the first two +digits (24): + +:: + + git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD + +Using Draft Branches +-------------------- + +You can use draft branches to add specific reviewers before you +publishing your change. The Draft Branches are pushed to +``refs/drafts/master/TopicName`` + +The next command ensures a local branch is created: + +:: + + git checkout -b BRANCHNAME + +The next command pushes your change to the drafts branch under +**TopicName**: + +:: + + git push REMOTE HEAD:refs/drafts/master/TopicName + +Using Sandbox Branches +---------------------- + +You can create your own branches to develop features. The branches are +pushed to the ``refs/sandbox/USERNAME/BRANCHNAME`` location. + +These commands ensure the branch is created in Gerrit's server. + +:: + + git checkout -b sandbox/USERNAME/BRANCHNAME + 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, +- submit changes, +- apply feedback, +- rebase. + +The next command pushes forcibly without review: + +:: + + git push REMOTE sandbox/USERNAME/BRANCHNAME + +You can also push forcibly with review: + +:: + + git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME + +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. + +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: + +:: + + git log REMOTE/master..master + + c0 + ... + c7 + + 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 +`rebasing `__ +section for more information. However, you must keep the same Change-Id +and push the changes again: + +:: + + 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 ``review UI`` section, for each change. + +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. + +- **squash:** mixes two or more commits into a single one. +- **reword:** changes the commit message. +- **edit:** changes the commit content. +- **reorder:** allows you to interchange the order of the commits. +- **rebase:** stacks the commits on top of the master. + +Rebasing During a Pull +---------------------- + +Before pushing a rebase to your master, ensure that the history has a +consecutive order. + +For example, your ``REMOTE/master`` has the list of commits from **a0** +to **a4**; Then, your changes **c0...c7** are on top of **a4**; thus: + +:: + + git log --oneline REMOTE/master..master + + a0 + a1 + a2 + a3 + a4 + c0 + c1 + ... + c7 + +If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull +with a rebase as follows: + +:: + + git pull --rebase REMOTE master + +This pulls **a5-a7** and re-apply **c0-c7** on top of them: + +:: + + $ git log --oneline REMOTE/master..master + a0 + ... + a7 + c0 + c1 + ... + c7 + +Getting Better Logs from Git +---------------------------- + +Use these commands to change the configuration of Git in order to +produce better logs: + +:: + + git config log.abbrevCommit true + +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. + +:: + + git config format.pretty oneline + +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 ``--global`` to ``config`` as +follows: diff --git a/docs/source/Gerrit/changes.md b/docs/source/Gerrit/changes.md deleted file mode 100644 index fe5b1e7845..0000000000 --- a/docs/source/Gerrit/changes.md +++ /dev/null @@ -1,63 +0,0 @@ -# Submitting a Change to Gerrit - -Carefully review the following before submitting a change. These -guidelines apply to developers that are new to open source, as well as -to experienced open source developers. - -## Change Requirements - -This section contains guidelines for submitting code changes for review. -For more information on how to submit a change using Gerrit, please -see [Gerrit](gerrit.md). - -Changes are submitted as Git commits. Each commit must contain: - -- a short and descriptive subject line that is 72 characters or fewer, - followed by a blank line. -- a change description with your logic or reasoning for the changes, - followed by a blank line -- a Signed-off-by line, followed by a colon (Signed-off-by:) -- a Change-Id identifier line, followed by a colon (Change-Id:). Gerrit won't - accept patches without this identifier. - -A commit with the above details is considered well-formed. - -All changes and topics sent to Gerrit must be well-formed. Informationally, -`commit messages` must include: - -* **what** the change does, -* **why** you chose that approach, and -* **how** you know it works -- for example, which tests you ran. - -Commits must [build cleanly](../dev-setup/build.md) when applied in top of each -other, thus avoiding breaking bisectability. Each commit must address a single -identifiable issue and must be logically self-contained. - -For example: One commit fixes whitespace issues, another renames a -function and a third one changes the code's functionality. An example commit -file is illustrated below in detail: - -``` -A short description of your change with no period at the end - -You can add more details here in several paragraphs, but please keep each line -width less than 80 characters. A bug fix should include the issue number. - -Fix Issue # 7050. - -Change-Id: IF7b6ac513b2eca5f2bab9728ebd8b7e504d3cebe1 -Signed-off-by: Your Name -``` -Each commit must contain the following line at the bottom of the commit -message: - -``` -Signed-off-by: Your Name -``` - -The name in the Signed-off-by line and your email must match the change -authorship information. Make sure your :file:`.git/config` is set up -correctly. Always submit the full set of changes via Gerrit. - -When a change is included in the set to enable other changes, but it -will not be part of the final set, please let the reviewers know this. diff --git a/docs/source/Gerrit/changes.rst b/docs/source/Gerrit/changes.rst new file mode 100644 index 0000000000..56abbcf244 --- /dev/null +++ b/docs/source/Gerrit/changes.rst @@ -0,0 +1,67 @@ +Submitting a Change to Gerrit +============================= + +Carefully review the following before submitting a change. These +guidelines apply to developers that are new to open source, as well as +to experienced open source developers. + +Change Requirements +------------------- + +This section contains guidelines for submitting code changes for review. +For more information on how to submit a change using Gerrit, please see +`Gerrit `__. + +Changes are submitted as Git commits. Each commit must contain: + +- a short and descriptive subject line that is 72 characters or fewer, + followed by a blank line. +- a change description with your logic or reasoning for the changes, + followed by a blank line +- a Signed-off-by line, followed by a colon (Signed-off-by:) +- a Change-Id identifier line, followed by a colon (Change-Id:). Gerrit + won't accept patches without this identifier. + +A commit with the above details is considered well-formed. + +All changes and topics sent to Gerrit must be well-formed. +Informationally, ``commit messages`` must include: + +- **what** the change does, +- **why** you chose that approach, and +- **how** you know it works -- for example, which tests you ran. + +Commits must `build cleanly <../dev-setup/build.md>`__ when applied in +top of each other, thus avoiding breaking bisectability. Each commit +must address a single identifiable issue and must be logically +self-contained. + +For example: One commit fixes whitespace issues, another renames a +function and a third one changes the code's functionality. An example +commit file is illustrated below in detail: + +:: + + A short description of your change with no period at the end + + You can add more details here in several paragraphs, but please keep each line + width less than 80 characters. A bug fix should include the issue number. + + Fix Issue # 7050. + + Change-Id: IF7b6ac513b2eca5f2bab9728ebd8b7e504d3cebe1 + Signed-off-by: Your Name + +Each commit must contain the following line at the bottom of the commit +message: + +:: + + Signed-off-by: Your Name + +The name in the Signed-off-by line and your email must match the change +authorship information. Make sure your :file:``.git/config`` is set up +correctly. Always submit the full set of changes via Gerrit. + +When a change is included in the set to enable other changes, but it +will not be part of the final set, please let the reviewers know this. diff --git a/docs/source/Gerrit/gerrit.md b/docs/source/Gerrit/gerrit.md deleted file mode 100644 index 633dd532f8..0000000000 --- a/docs/source/Gerrit/gerrit.md +++ /dev/null @@ -1,218 +0,0 @@ -# Working with Gerrit - -Follow these instructions to collaborate on the Hyperledger Fabric Project -through the Gerrit review system. - -Please be sure that you are subscribed to the [mailing -list](http://lists.hyperledger.org/mailman/listinfo/hyperledger-fabric) and of -course, you can reach out on [chat](https://chat.hyperledger.org/) if -you need help. - -Gerrit assigns the following roles to users: - -* **Submitters**: May submit changes for consideration, review other code - changes, and make recommendations for acceptance or rejection by voting - +1 or -1, respectively. -* **Maintainers**: May approve or reject changes based upon feedback from - reviewers voting +2 or -2, respectively. -* **Builders**: (e.g. Jenkins) May use the build automation infrastructure to - verify the change. - -Maintainers should be familiar with the [review process](reviewing.md). However, -anyone is welcome to (and encouraged!) review changes, and hence may find that -document of value. - -## Git-review - -There's a **very** useful tool for working with Gerrit called -[git-review](https://www.mediawiki.org/wiki/Gerrit/git-review). This -command-line tool can automate most of the ensuing sections for you. Of course, -reading the information below is also highly recommended so that you understand -what's going on behind the scenes. - -## Sandbox project - -We have created a [sandbox -project](https://gerrit.hyperledger.org/r/#/admin/projects/lf-sandbox) to allow -developers to familiarize themselves with Gerrit and our workflows. Please do -feel free to use this project to experiment with the commands and tools, below. - -## Getting deeper into Gerrit - -A comprehensive walk-through of Gerrit is beyond the scope of this document. -There are plenty of resources available on the Internet. A good summary can be -found [here](https://www.mediawiki.org/wiki/Gerrit/Tutorial). We have also -provided a set of [Best Practices](best-practices.md) that you may find helpful. - -## Working with a local clone of the repository - -To work on something, whether a new feature or a bugfix: - -1. Open the Gerrit [Projects page](https://gerrit.hyperledger.org/r/#/admin/projects/) - -2. Select the project you wish to work on. - -3. Open a terminal window and clone the project locally using the `Clone with git -hook` URL. Be sure that `ssh` is also selected, as this will make authentication -much simpler: -``` -git clone ssh://LFID@gerrit.hyperledger.org:29418/fabric && scp -p -P 29418 LFID@gerrit.hyperledger.org:hooks/commit-msg fabric/.git/hooks/ -``` - -**Note:** if you are cloning the fabric project repository, you will want to -clone it to the `$GOPATH/src/github.com/hyperledger` directory so that it will -build, and so that you can use it with the Vagrant [development -environment](../dev-setup/devenv.md). - -4. Create a descriptively-named branch off of your cloned repository - -``` -cd fabric -git checkout -b issue-nnnn -``` - -5. Commit your code. For an in-depth discussion of creating an effective commit, -please read [this document](changes.md). - -``` -git commit -s -a -``` - -Then input precise and readable commit msg and submit. - -6. Any code changes that affect documentation should be accompanied by -corresponding changes (or additions) to the documentation and tests. This -will ensure that if the merged PR is reversed, all traces of the change will -be reversed as well. - -## Submitting a Change - -Currently, Gerrit is the only method to submit a change for review. **Please review -the [guidelines](changes.md) for making and submitting a change**. - -### Use git review - -**Note:** if you prefer, you can use the [git-review](#git-review) tool instead -of the following. e.g. - -Add the following section to `.git/config`, and replace `` with your -gerrit id. - -``` -[remote "gerrit"] - url = ssh://@gerrit.hyperledger.org:29418/fabric.git - fetch = +refs/heads/*:refs/remotes/gerrit/* -``` - -Then submit your change with `git review`. - -``` -$ cd -$ git review -``` - -When you update your patch, you can commit with `git commit --amend`, and then -repeat the `git review` command. - -### Not Use git review - -Directions for building the source code can be found [here](../dev-setup/build.md). - -When a change is ready for submission, Gerrit requires that the -change be pushed to a special branch. The name of this special branch -contains a reference to the final branch where the code should reside, -once accepted. - -For the Hyperledger Fabric Project, the special branch is called `refs/for/master`. - -To push the current local development branch to the gerrit server, open a -terminal window at the root of your cloned repository: - -``` -cd -git push origin HEAD:refs/for/master -``` -If the command executes correctly, the output should look similar to this: - -``` -Counting objects: 3, done. -Writing objects: 100% (3/3), 306 bytes | 0 bytes/s, done. -Total 3 (delta 0), reused 0 (delta 0) -remote: Processing changes: new: 1, refs: 1, done -remote: -remote: New Changes: -remote: https://gerrit.hyperledger.org/r/6 Test commit -remote: -To ssh://LFID@gerrit.hyperledger.org:29418/fabric -* [new branch] HEAD -> refs/for/master -``` - -The gerrit server generates a link where the change can be tracked. - -## Adding reviewers - -Optionally, you can add reviewers to your change. - -To specify a list of reviewers via the command line, add -`%r=reviewer@project.org` to your push command. For example: - -``` -git push origin HEAD:refs/for/master%r=rev1@email.com,r=rev2@notemail.com -``` - Alternatively, you can auto-configure GIT to add a set of reviewers if your - commits will have the same reviewers all at the time. - - To add a list of default reviewers, open the :file:`.git/config` file in the - project directory and add the following line in the `[ branch “master” ]` - section: - -``` -[branch "master"] #.... push = -HEAD:refs/for/master%r=rev1@email.com,r=rev2@notemail.com` -``` - -Make sure to use actual email addresses instead of the `@email.com and @notemail.com` -addressses. Don't forget to replace `origin` with your git remote name. - -## Reviewing Using Gerrit - -* **Add**: This button allows the change submitter to manually add names of - people who should review a change; start typing a name and the system - will auto-complete based on the list of people registered and with - access to the system. They will be notified by email that you are - requesting their input. - -* **Abandon**: This button is available to the submitter only; it allows a - committer to abandon a change and remove it from the merge queue. - -* **Change-ID**: This ID is generated by Gerrit (or system). It becomes - useful when the review process determines that your commit(s) have to - be amended. You may submit a new version; and if the same Change-ID - header (and value) are present, Gerrit will remember it and present - it as another version of the same change. - -* **Status**: Currently, the example change is in review status, as indicated - by “Needs Verified” in the upper-left corner. The list of - Reviewers will all emit their opinion, voting +1 if they agree to the - merge, -1 if they disagree. Gerrit users with a Maintainer role can - agree to the merge or refuse it by voting +2 or -2 respectively. - -Notifications are sent to the email address in your commit message's -Signed-off-by line. Visit your [Gerrit dashboard](https://gerrit.hyperledger.org/r/#/dashboard/self), to check the progress of your requests. - -The history tab in Gerrit will show you the in-line comments and the author of -the review. - -## Viewing Pending Changes - -Find all pending changes by clicking on the `All --> Changes` link in the -upper-left corner, or [open this link](https://gerrit.hyperledger.org/r/#/q/project:fabric). - -If you collaborate in multiple projects, you may wish to limit searching to -the specific branch through the search bar in the upper-right side. - -Add the filter *project:fabric* to limit the visible changes to -only those from the Hyperledger Fabric Project. - -List all current changes you submitted, or list just those changes in need -of your input by clicking on `My --> Changes` or [open this link](https://gerrit.hyperledger.org/r/#/dashboard/self) diff --git a/docs/source/Gerrit/gerrit.rst b/docs/source/Gerrit/gerrit.rst new file mode 100644 index 0000000000..eb6cc7da3a --- /dev/null +++ b/docs/source/Gerrit/gerrit.rst @@ -0,0 +1,246 @@ +Working with Gerrit +=================== + +Follow these instructions to collaborate on the Hyperledger Fabric +Project through the Gerrit review system. + +Please be sure that you are subscribed to the `mailing +list `__ +and of course, you can reach out on +`chat `__ if you need help. + +Gerrit assigns the following roles to users: + +- **Submitters**: May submit changes for consideration, review other + code changes, and make recommendations for acceptance or rejection by + voting +1 or -1, respectively. +- **Maintainers**: May approve or reject changes based upon feedback + from reviewers voting +2 or -2, respectively. +- **Builders**: (e.g. Jenkins) May use the build automation + infrastructure to verify the change. + +Maintainers should be familiar with the `review +process `__. However, anyone is welcome to (and +encouraged!) review changes, and hence may find that document of value. + +Git-review +---------- + +There's a **very** useful tool for working with Gerrit called +`git-review `__. This +command-line tool can automate most of the ensuing sections for you. Of +course, reading the information below is also highly recommended so that +you understand what's going on behind the scenes. + +Sandbox project +--------------- + +We have created a `sandbox +project `__ +to allow developers to familiarize themselves with Gerrit and our +workflows. Please do feel free to use this project to experiment with +the commands and tools, below. + +Getting deeper into Gerrit +-------------------------- + +A comprehensive walk-through of Gerrit is beyond the scope of this +document. There are plenty of resources available on the Internet. A +good summary can be found +`here `__. We have also +provided a set of `Best Practices `__ that you may +find helpful. + +Working with a local clone of the repository +-------------------------------------------- + +To work on something, whether a new feature or a bugfix: + +1. Open the Gerrit `Projects + page `__ + +2. Select the project you wish to work on. + +3. Open a terminal window and clone the project locally using the + ``Clone with git hook`` URL. Be sure that ``ssh`` is also selected, + as this will make authentication much simpler: + + :: + + git clone ssh://LFID@gerrit.hyperledger.org:29418/fabric && scp -p -P 29418 LFID@gerrit.hyperledger.org:hooks/commit-msg fabric/.git/hooks/ + +**Note:** if you are cloning the fabric project repository, you will +want to clone it to the ``$GOPATH/src/github.com/hyperledger`` directory +so that it will build, and so that you can use it with the Vagrant +`development environment <../dev-setup/devenv.md>`__. + +4. Create a descriptively-named branch off of your cloned repository + +:: + + cd fabric + git checkout -b issue-nnnn + +5. Commit your code. For an in-depth discussion of creating an effective + commit, please read `this document `__. + +:: + + git commit -s -a + +Then input precise and readable commit msg and submit. + +6. Any code changes that affect documentation should be accompanied by + corresponding changes (or additions) to the documentation and tests. + This will ensure that if the merged PR is reversed, all traces of the + change will be reversed as well. + +Submitting a Change +------------------- + +Currently, Gerrit is the only method to submit a change for review. +**Please review the `guidelines `__ for making and +submitting a change**. + +Use git review +~~~~~~~~~~~~~~ + +**Note:** if you prefer, you can use the `git-review <#git-review>`__ +tool instead of the following. e.g. + +Add the following section to ``.git/config``, and replace ```` +with your gerrit id. + +:: + + [remote "gerrit"] + url = ssh://@gerrit.hyperledger.org:29418/fabric.git + fetch = +refs/heads/*:refs/remotes/gerrit/* + +Then submit your change with ``git review``. + +:: + + $ cd + $ git review + +When you update your patch, you can commit with ``git commit --amend``, +and then repeat the ``git review`` command. + +Not Use git review +~~~~~~~~~~~~~~~~~~ + +Directions for building the source code can be found +`here <../dev-setup/build.md>`__. + +When a change is ready for submission, Gerrit requires that the change +be pushed to a special branch. The name of this special branch contains +a reference to the final branch where the code should reside, once +accepted. + +For the Hyperledger Fabric Project, the special branch is called +``refs/for/master``. + +To push the current local development branch to the gerrit server, open +a terminal window at the root of your cloned repository: + +:: + + cd + git push origin HEAD:refs/for/master + +If the command executes correctly, the output should look similar to +this: + +:: + + Counting objects: 3, done. + Writing objects: 100% (3/3), 306 bytes | 0 bytes/s, done. + Total 3 (delta 0), reused 0 (delta 0) + remote: Processing changes: new: 1, refs: 1, done + remote: + remote: New Changes: + remote: https://gerrit.hyperledger.org/r/6 Test commit + remote: + To ssh://LFID@gerrit.hyperledger.org:29418/fabric + * [new branch] HEAD -> refs/for/master + +The gerrit server generates a link where the change can be tracked. + +Adding reviewers +---------------- + +Optionally, you can add reviewers to your change. + +To specify a list of reviewers via the command line, add +``%r=reviewer@project.org`` to your push command. For example: + +:: + + git push origin HEAD:refs/for/master%r=rev1@email.com,r=rev2@notemail.com + +Alternatively, you can auto-configure GIT to add a set of reviewers if +your commits will have the same reviewers all at the time. + +To add a list of default reviewers, open the :file:``.git/config`` file +in the project directory and add the following line in the +``[ branch “master” ]`` section: + +:: + + [branch "master"] #.... push = + HEAD:refs/for/master%r=rev1@email.com,r=rev2@notemail.com` + +Make sure to use actual email addresses instead of the +``@email.com and @notemail.com`` addressses. Don't forget to replace +``origin`` with your git remote name. + +Reviewing Using Gerrit +---------------------- + +- **Add**: This button allows the change submitter to manually add + names of people who should review a change; start typing a name and + the system will auto-complete based on the list of people registered + and with access to the system. They will be notified by email that + you are requesting their input. + +- **Abandon**: This button is available to the submitter only; it + allows a committer to abandon a change and remove it from the merge + queue. + +- **Change-ID**: This ID is generated by Gerrit (or system). It becomes + useful when the review process determines that your commit(s) have to + be amended. You may submit a new version; and if the same Change-ID + header (and value) are present, Gerrit will remember it and present + it as another version of the same change. + +- **Status**: Currently, the example change is in review status, as + indicated by “Needs Verified” in the upper-left corner. The list of + Reviewers will all emit their opinion, voting +1 if they agree to the + merge, -1 if they disagree. Gerrit users with a Maintainer role can + agree to the merge or refuse it by voting +2 or -2 respectively. + +Notifications are sent to the email address in your commit message's +Signed-off-by line. Visit your `Gerrit +dashboard `__, to +check the progress of your requests. + +The history tab in Gerrit will show you the in-line comments and the +author of the review. + +Viewing Pending Changes +----------------------- + +Find all pending changes by clicking on the ``All --> Changes`` link in +the upper-left corner, or `open this +link `__. + +If you collaborate in multiple projects, you may wish to limit searching +to the specific branch through the search bar in the upper-right side. + +Add the filter *project:fabric* to limit the visible changes to only +those from the Hyperledger Fabric Project. + +List all current changes you submitted, or list just those changes in +need of your input by clicking on ``My --> Changes`` or `open this +link `__ diff --git a/docs/source/Gerrit/lf-account.md b/docs/source/Gerrit/lf-account.md deleted file mode 100644 index e95ad3916e..0000000000 --- a/docs/source/Gerrit/lf-account.md +++ /dev/null @@ -1,106 +0,0 @@ -# Requesting a Linux Foundation Account - -Contributions to the Fabric code base require a Linux Foundation account. -Follow the steps below to create a Linux Foundation account. - -## Creating a Linux Foundation ID - -1. Go to the [Linux Foundation ID website](https://identity.linuxfoundation.org/). - -2. Select the option `I need to create a Linux Foundation ID`. - -3. Fill out the form that appears: - -4. Open your email account and look for a message with the subject line: - "Validate your Linux Foundation ID email". - -5. Open the received URL to validate your email address. - -6. Verify the browser displays the message `You have successfully - validated your e-mail address`. - -7. Access `Gerrit` by selecting `Sign In`: - -8. Use your Linux Foundation ID to Sign In: - -## Configuring Gerrit to Use SSH - -Gerrit uses SSH to interact with your Git client. A SSH private key -needs to be generated on the development machine with a matching public -key on the Gerrit server. - -If you already have a SSH key-pair, skip this section. - -As an example, we provide the steps to generate the SSH key-pair on a Linux -environment. Follow the equivalent steps on your OS. - -1. Create a key-pair, enter: - -``` -ssh-keygen -t rsa -C "John Doe john.doe@example.com" -``` - -**Note:** This will ask you for a password to protect the private key as it -generates a unique key. Please keep this password private, and DO NOT -enter a blank password. - -The generated key-pair is found in: `~/.ssh/id_rsa` and `~/.ssh/id_rsa.pub`. - -1. Add the private key in the `id_rsa` file in your key ring, e.g.: - -``` -ssh-add ~/.ssh/id_rsa -``` - -Once the key-pair has been generated, the public key must be added to Gerrit. - -Follow these steps to add your public key `id_rsa.pub` to the Gerrit -account: - -1. Go to [Gerrit](https://gerrit.hyperledger.org/r/#/admin/projects/fabric). - -2. Click on your account name in the upper right corner. - -3. From the pop-up menu, select `Settings`. - -4. On the left side menu, click on `SSH Public Keys`. - -5. Paste the contents of your public key `~/.ssh/id_rsa.pub` and click - `Add key`. - -**Note:** The `id_rsa.pub` file can be opened with any text editor. Ensure - that all the contents of the file are selected, copied and pasted into the - `Add SSH key` window in Gerrit. - -**Note:** The ssh key generation instructions operate on the assumtion that -you are using the default naming. It is possible to generate multiple ssh Keys -and to name the resulting files differently. See the [ssh-keygen](https://en.wikipedia.org/wiki/Ssh-keygen) -documentation for details on how to do that. Once you have generated non-default -keys, you need to configure ssh to use the correct key for Gerrit. In that case, -you need to create a `~/.ssh/config` file modeled after the one below. - -``` -host gerrit.hyperledger.org - HostName gerrit.hyperledger.org - IdentityFile ~/.ssh/id_rsa_hyperledger_gerrit - User -``` -where is your Linux Foundation ID and the value of IdentityFile is the -name of the public key file you generated. - -**Warning:** Potential Security Risk! Do not copy your private key - `~/.ssh/id_rsa` Use only the public `~/.ssh/id_rsa.pub`. - -## Checking Out the Source Code - -1. Ensure that SSH has been set up properly. See - `Configuring Gerrit to Use SSH` for details. - -2. Clone the repository with your Linux Foundation ID (): - -``` -git clone ssh://@gerrit.hyperledger.org:29418/fabric fabric -``` - -You have successfully checked out a copy of the source code to your local -machine. diff --git a/docs/source/Gerrit/lf-account.rst b/docs/source/Gerrit/lf-account.rst new file mode 100644 index 0000000000..523f0c6fb2 --- /dev/null +++ b/docs/source/Gerrit/lf-account.rst @@ -0,0 +1,117 @@ +Requesting a Linux Foundation Account +===================================== + +Contributions to the Fabric code base require a Linux Foundation +account. Follow the steps below to create a Linux Foundation account. + +Creating a Linux Foundation ID +------------------------------ + +1. Go to the `Linux Foundation ID + website `__. + +2. Select the option ``I need to create a Linux Foundation ID``. + +3. Fill out the form that appears: + +4. Open your email account and look for a message with the subject line: + "Validate your Linux Foundation ID email". + +5. Open the received URL to validate your email address. + +6. Verify the browser displays the message + ``You have successfully validated your e-mail address``. + +7. Access ``Gerrit`` by selecting ``Sign In``: + +8. Use your Linux Foundation ID to Sign In: + +Configuring Gerrit to Use SSH +----------------------------- + +Gerrit uses SSH to interact with your Git client. A SSH private key +needs to be generated on the development machine with a matching public +key on the Gerrit server. + +If you already have a SSH key-pair, skip this section. + +As an example, we provide the steps to generate the SSH key-pair on a +Linux environment. Follow the equivalent steps on your OS. + +1. Create a key-pair, enter: + +:: + + ssh-keygen -t rsa -C "John Doe john.doe@example.com" + +**Note:** This will ask you for a password to protect the private key as +it generates a unique key. Please keep this password private, and DO NOT +enter a blank password. + +The generated key-pair is found in: ``~/.ssh/id_rsa`` and +``~/.ssh/id_rsa.pub``. + +1. Add the private key in the ``id_rsa`` file in your key ring, e.g.: + +:: + + ssh-add ~/.ssh/id_rsa + +Once the key-pair has been generated, the public key must be added to +Gerrit. + +Follow these steps to add your public key ``id_rsa.pub`` to the Gerrit +account: + +1. Go to + `Gerrit `__. + +2. Click on your account name in the upper right corner. + +3. From the pop-up menu, select ``Settings``. + +4. On the left side menu, click on ``SSH Public Keys``. + +5. Paste the contents of your public key ``~/.ssh/id_rsa.pub`` and click + ``Add key``. + +**Note:** The ``id_rsa.pub`` file can be opened with any text editor. +Ensure that all the contents of the file are selected, copied and pasted +into the ``Add SSH key`` window in Gerrit. + +**Note:** The ssh key generation instructions operate on the assumtion +that you are using the default naming. It is possible to generate +multiple ssh Keys and to name the resulting files differently. See the +`ssh-keygen `__ documentation +for details on how to do that. Once you have generated non-default keys, +you need to configure ssh to use the correct key for Gerrit. In that +case, you need to create a ``~/.ssh/config`` file modeled after the one +below. + +:: + + host gerrit.hyperledger.org + HostName gerrit.hyperledger.org + IdentityFile ~/.ssh/id_rsa_hyperledger_gerrit + User + +where is your Linux Foundation ID and the value of IdentityFile is the +name of the public key file you generated. + +**Warning:** Potential Security Risk! Do not copy your private key +``~/.ssh/id_rsa`` Use only the public ``~/.ssh/id_rsa.pub``. + +Checking Out the Source Code +---------------------------- + +1. Ensure that SSH has been set up properly. See + ``Configuring Gerrit to Use SSH`` for details. + +2. Clone the repository with your Linux Foundation ID (): + +:: + + git clone ssh://@gerrit.hyperledger.org:29418/fabric fabric + +You have successfully checked out a copy of the source code to your +local machine. diff --git a/docs/source/Gerrit/reviewing.md b/docs/source/Gerrit/reviewing.md deleted file mode 100644 index 79fafe8f27..0000000000 --- a/docs/source/Gerrit/reviewing.md +++ /dev/null @@ -1,51 +0,0 @@ -# Reviewing a Change - -1. Click on a link for incoming or outgoing review. - -2. The details of the change and its current status are loaded: - - * **Status:** Displays the current status of the change. In the - example below, the status reads: Needs Verified. - - * **Reply:** Click on this button after reviewing to add a final - review message and a score, -1, 0 or +1. - - * **Patch Sets:** If multiple revisions of a patch exist, this button - enables navigation among revisions to see the changes. By default, - the most recent revision is presented. - - * **Download:** This button brings up another window with multiple - options to download or checkout the current changeset. The button on - the right copies the line to your clipboard. You can easily paste it - into your git interface to work with the patch as you prefer. - - Underneath the commit information, the files that have been changed by - this patch are displayed. - -3. Click on a filename to review it. Select the code base to differentiate - against. The default is `Base` and it will generally be - what is needed. - -4. The review page presents the changes made to the file. At the top of - the review, the presentation shows some general navigation options. - Navigate through the patch set using the arrows on the top - right corner. It is possible to go to the previous or next file in the - set or to return to the main change screen. Click on the yellow sticky - pad to add comments to the whole file. - - The focus of the page is on the comparison window. The changes made - are presented in green on the right versus the base version on the left. - Double click to highlight the text within the actual change to provide - feedback on a specific section of the code. Press *c* once the code is - highlighted to add comments to that section. - -5. After adding the comment, it is saved as a *Draft*. - -6. Once you have reviewed all files and provided feedback, click the - *green up arrow* at the top right to return to the main change page. Click - the `Reply` button, write some final comments, and submit your score for - the patch set. Click `Post` to submit the review of each reviewed file, as - well as your final comment and score. Gerrit sends an email to the - change-submitter and all listed reviewers. Finally, it logs the review - for future reference. All individual comments are saved as *Draft* until - the `Post` button is clicked. diff --git a/docs/source/Gerrit/reviewing.rst b/docs/source/Gerrit/reviewing.rst new file mode 100644 index 0000000000..e67210c009 --- /dev/null +++ b/docs/source/Gerrit/reviewing.rst @@ -0,0 +1,52 @@ +Reviewing a Change +================== + +1. Click on a link for incoming or outgoing review. + +2. The details of the change and its current status are loaded: + +- **Status:** Displays the current status of the change. In the example + below, the status reads: Needs Verified. + +- **Reply:** Click on this button after reviewing to add a final review + message and a score, -1, 0 or +1. + +- **Patch Sets:** If multiple revisions of a patch exist, this button + enables navigation among revisions to see the changes. By default, + the most recent revision is presented. + +- **Download:** This button brings up another window with multiple + options to download or checkout the current changeset. The button on + the right copies the line to your clipboard. You can easily paste it + into your git interface to work with the patch as you prefer. + +Underneath the commit information, the files that have been changed by +this patch are displayed. + +3. Click on a filename to review it. Select the code base to + differentiate against. The default is ``Base`` and it will generally + be what is needed. + +4. The review page presents the changes made to the file. At the top of + the review, the presentation shows some general navigation options. + Navigate through the patch set using the arrows on the top right + corner. It is possible to go to the previous or next file in the set + or to return to the main change screen. Click on the yellow sticky + pad to add comments to the whole file. + +The focus of the page is on the comparison window. The changes made are +presented in green on the right versus the base version on the left. +Double click to highlight the text within the actual change to provide +feedback on a specific section of the code. Press *c* once the code is +highlighted to add comments to that section. + +5. After adding the comment, it is saved as a *Draft*. + +6. Once you have reviewed all files and provided feedback, click the + *green up arrow* at the top right to return to the main change page. + Click the ``Reply`` button, write some final comments, and submit + your score for the patch set. Click ``Post`` to submit the review of + each reviewed file, as well as your final comment and score. Gerrit + sends an email to the change-submitter and all listed reviewers. + Finally, it logs the review for future reference. All individual + comments are saved as *Draft* until the ``Post`` button is clicked. diff --git a/docs/source/mdtorst.sh b/docs/source/mdtorst.sh index bd8a25e08b..dd563ca22b 100644 --- a/docs/source/mdtorst.sh +++ b/docs/source/mdtorst.sh @@ -7,5 +7,5 @@ do echo "Converting $f to $filename.rst" `pandoc $f -t rst -o $filename.rst` # uncomment this line to delete the source file. - rm $f + # rm $f done