diff --git a/docs/source/CONTRIBUTING.rst b/docs/source/CONTRIBUTING.rst index 4284448590e..8ccfe192ffc 100644 --- a/docs/source/CONTRIBUTING.rst +++ b/docs/source/CONTRIBUTING.rst @@ -27,19 +27,6 @@ access to all the Hyperledger community development tools, including `Jira `__ and the `Wiki `__ (for editing, only). -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 -:doc:`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 -key `__ into -the window and press 'Add'. - Getting help ------------ @@ -54,22 +41,21 @@ and will be glad to help. The only silly question is the one you don't ask. Questions are in fact a great way to help improve the project as they highlight where our documentation could be clearer. -Requirements and Use Cases --------------------------- - -We have a `Requirements -WG `__ -that is documenting use cases and from those use cases deriving -requirements. If you are interested in contributing to this effort, -please feel free to join the discussion in -`chat `__. - Reporting bugs -------------- -If you are a user and you find a bug, please submit an issue using +If you are a user and you have found a bug, please submit an issue using `JIRA `__. -Please try to provide sufficient information for someone else to reproduce the +Before you create a new JIRA issue, please try to search the existing items to +be sure no one else has previously reported it. If it has been previously +reported, then you might add a comment that you also are interested in seeing +the defect fixed. + +.. note:: If the defect is security-related, please follow the Hyperledger + `security bug reporting process `. + +If it has not been previously reported, create a new JIRA. Please try to provide +sufficient information for someone else to reproduce the issue. One of the project's maintainers should respond to your issue within 24 hours. If not, please bump the issue with a comment and request that it be reviewed. You can also post to the relevant fabric channel in @@ -77,6 +63,16 @@ reviewed. You can also post to the relevant fabric channel in be broadcast to ``#fabric-documentation``, a database bug to ``#fabric-ledger``, and so on... +Submitting your fix +------------------- + +If you just submitted a JIRA for a bug you've discovered, and would like to +provide a fix, we would welcome that gladly! Please assign the JIRA issue to +yourself, then you can submit a change request (CR). + +.. note:: If you need help with submitting your first CR, we have created a + brief :doc:`tutorial ` for you. + Fixing issues and working stories --------------------------------- @@ -117,29 +113,12 @@ Getting the support of three or more of the Hyperledger Fabric maintainers for t feature will greatly enhance the probability that the feature's related CRs will be merged. -Working with a local clone and Gerrit -------------------------------------- - -We are using -`Gerrit `__ to -manage code contributions. If you are unfamiliar, please review this -:doc:`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 -:doc:`environment `. +Setting up development environment +---------------------------------- Next, try :doc:`building the project ` in your local development environment to ensure that everything is set up correctly. -The :doc:`logging-control` document describes how to tweak -the logging levels of various components within Hyperledger Fabric. Finally, -every source file needs to include a -`license header `__: modified to include a copyright -statement for the principle author(s). - What makes a good change request? --------------------------------- @@ -189,9 +168,9 @@ What makes a good change request? bunch of generated code (protobufs, etc.). Again, there can be exceptions. - Note: large change requests, e.g. those with more than 300 LOC are more likely - than not going to receive a -2, and you'll be asked to refactor the change - to conform with this guidance. +.. note:: Large change requests, e.g. those with more than 300 LOC are more likely + than not going to receive a -2, and you'll be asked to refactor the + change to conform with this guidance. - Do not stack change requests (e.g. submit a CR from the same local branch as your previous CR) unless they are related. This will minimize merge @@ -203,18 +182,19 @@ What makes a good change request? character title, followed by a blank line, followed by a more comprehensive description of the change. Each change MUST include the JIRA identifier corresponding to the change (e.g. [FAB-1234]). This can be - in the title but should also be in the body of the commit message. - - Note that Gerrit will automatically create a hyperlink to the JIRA item. + in the title but should also be in the body of the commit message. See the + :doc:`complete requirements ` for an acceptable change + request. -e.g. +.. note:: That Gerrit will automatically create a hyperlink to the JIRA item. + e.g. -:: + :: - [FAB-1234] fix foobar() panic + [FAB-1234] fix foobar() panic - Fix [FAB-1234] added a check to ensure that when foobar(foo string) is called, - that there is a non-empty string argument. + Fix [FAB-1234] added a check to ensure that when foobar(foo string) + is called, that there is a non-empty string argument. Finally, be responsive. Don't let a change request fester with review comments such that it gets to a point that it requires a rebase. It only diff --git a/docs/source/Gerrit/changes.rst b/docs/source/Gerrit/changes.rst index 9d9e0a1f65b..e57484483d3 100644 --- a/docs/source/Gerrit/changes.rst +++ b/docs/source/Gerrit/changes.rst @@ -31,7 +31,7 @@ Informationally, ``commit messages`` must include: - **why** you chose that approach, and - **how** you know it works -- for example, which tests you ran. -Commits must :doc:`build cleanly <../dev-setup/build>` when applied in +Commits must :doc:`build cleanly <../dev-setup/build>` when applied on top of each other, thus avoiding breaking bisectability. Each commit must address a single identifiable issue and must be logically self-contained. @@ -70,4 +70,3 @@ will not be part of the final set, please let the reviewers know this. .. Licensed under Creative Commons Attribution 4.0 International License https://creativecommons.org/licenses/by/4.0/ - diff --git a/docs/source/Gerrit/gerrit.rst b/docs/source/Gerrit/gerrit.rst index 46f1a3b2fce..f8d8f18fcf9 100644 --- a/docs/source/Gerrit/gerrit.rst +++ b/docs/source/Gerrit/gerrit.rst @@ -1,5 +1,5 @@ Working with Gerrit -=================== +------------------- Follow these instructions to collaborate on Hyperledger Fabric through the Gerrit review system. @@ -24,7 +24,7 @@ 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 @@ -32,17 +32,8 @@ 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 @@ -52,7 +43,7 @@ provided a set of :doc:`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: @@ -65,14 +56,14 @@ To work on something, whether a new feature or a bugfix: ``Clone with git hook`` URL. Be sure that ``ssh`` is also selected, as this will make authentication much simpler: - :: +.. code:: - git clone ssh://LFID@gerrit.hyperledger.org:29418/fabric && scp -p -P 29418 LFID@gerrit.hyperledger.org:hooks/commit-msg fabric/.git/hooks/ + 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 -:doc:`development environment <../dev-setup/devenv>`. +.. 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 :doc:`development environment <../dev-setup/devenv>`. 4. Create a descriptively-named branch off of your cloned repository @@ -96,18 +87,18 @@ Then input precise and readable commit msg and submit. change will be reversed as well. Submitting a Change -------------------- +~~~~~~~~~~~~~~~~~~~ Currently, Gerrit is the only method to submit a change for review. -**Note:** Please review the :doc:`guidelines ` for making and -submitting a change. +.. note:: Please review the :doc:`guidelines ` for making and + submitting a change. Using git review -~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~ -**Note:** if you prefer, you can use the `git-review <#git-review>`__ -tool instead of the following. e.g. +.. 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. @@ -129,7 +120,7 @@ When you update your patch, you can commit with ``git commit --amend``, and then repeat the ``git review`` command. Not using git review -~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~ See the :doc:`directions for building the source code <../dev-setup/build>`. @@ -167,34 +158,6 @@ this: 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 ---------------------- @@ -247,4 +210,3 @@ link `__ .. Licensed under Creative Commons Attribution 4.0 International License https://creativecommons.org/licenses/by/4.0/ - diff --git a/docs/source/images/AddSSH1.png b/docs/source/images/AddSSH1.png new file mode 100644 index 00000000000..afbc8ce01b3 Binary files /dev/null and b/docs/source/images/AddSSH1.png differ diff --git a/docs/source/images/AddSSH2.png b/docs/source/images/AddSSH2.png new file mode 100644 index 00000000000..b7a535e6bc6 Binary files /dev/null and b/docs/source/images/AddSSH2.png differ diff --git a/docs/source/images/GitCloneCmd.png b/docs/source/images/GitCloneCmd.png new file mode 100644 index 00000000000..a046448c098 Binary files /dev/null and b/docs/source/images/GitCloneCmd.png differ diff --git a/docs/source/images/NewGerritUI.png b/docs/source/images/NewGerritUI.png new file mode 100644 index 00000000000..e8636810146 Binary files /dev/null and b/docs/source/images/NewGerritUI.png differ diff --git a/docs/source/images/SSHKeys.png b/docs/source/images/SSHKeys.png new file mode 100644 index 00000000000..da16e46b404 Binary files /dev/null and b/docs/source/images/SSHKeys.png differ diff --git a/docs/source/images/Settings.png b/docs/source/images/Settings.png new file mode 100644 index 00000000000..85558f4f3ca Binary files /dev/null and b/docs/source/images/Settings.png differ diff --git a/docs/source/images/lf-sandbox.png b/docs/source/images/lf-sandbox.png new file mode 100644 index 00000000000..5e55a54987a Binary files /dev/null and b/docs/source/images/lf-sandbox.png differ diff --git a/docs/source/submit_cr.rst b/docs/source/submit_cr.rst new file mode 100644 index 00000000000..d429b314c88 --- /dev/null +++ b/docs/source/submit_cr.rst @@ -0,0 +1,202 @@ +Submitting your first change request (CR) +----------------------------------------- + +We are using +`Gerrit `__ to +manage code contributions and reviews. If you are unfamiliar with Gerrit, +please review this :doc:`document ` before proceeding. + +.. note:: Gerrit has a reputation of having a clunky user experience. However, + the Google team has been working on improving this, and they have + added a "New UI" option that will allow you to work with their new + and much improved UX. See the link at the bottom of the Fabric + Gerrit page, linked above. + + .. image:: images/NewGerritUI.png + +Setting up your SSH key +~~~~~~~~~~~~~~~~~~~~~~~ + +Before you can submit a change set for review, you will need to register your +public SSH key. Login to +`Gerrit `__ with your +:doc:`LFID `, and click on your name in the upper +right-hand corner of your browser window and then click 'Settings'. + +.. image:: images/Settings.png + :width: 300px + +In the left-hand margin, you should see a link for 'SSH Public Keys'. + +.. image:: images/SSHKeys.png + :width: 200px + +Press the ``Add Key...`` button + +.. image:: images/AddSSH1.png + :width: 400px + +Copy-n-paste your `public SSH key `__ into +the window and press 'Add'. + +.. image:: images/AddSSH2.png + :width: 600px + +Sandbox +~~~~~~~ + +We have created the +`lf-sandbox project `__, +to allow you to familiarize yourself with using Gerrit. We'll use that project +in our tutorial for submitting your first CR. + +Clone your project +~~~~~~~~~~~~~~~~~~ + +First step is to clone your project to your laptop or development server. +Navigate your browser to the Gerrit `Projects `__ +page and scroll down to the ``lf-sandbox`` project. + +.. image:: images/lf-sandbox.png + :width: 500px + +The project page will provide you with the full git clone command needed to +clone the project. Select the ``clone with commit-msg hook`` option and copy the +command to the clipboard. + +.. image:: images/GitCloneCmd.png + :width: 600px + +Now, in a terminal window on your laptop, paste and run the command. e.g. + +.. code:: + + git clone ssh://foobar@gerrit.hyperledger.org:29418/lf-sandbox && scp -p -P 29418 foobar@gerrit.hyperledger.org:hooks/commit-msg lf-sandbox/.git/hooks/ + +Checkout a development branch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Now that you have cloned the repository, change directory to the ``lf-sandbox`` +directory. Now let's make a change. First, let's create a new branch in which +to work: + +.. code:: + + git checkout -b + +Now let's modify a file. Pick a file, any file and make a change. You can also +add a new file or delete an existing file. Don't be shy, this is just a +sandbox. + +Committing your change +~~~~~~~~~~~~~~~~~~~~~~ + +Once you've made your change, check to see what the current status is. + +.. code:: + + git status + On branch foo + Untracked files: + (use "git add ..." to include in what will be committed) + + README.md + + nothing added to commit but untracked files present (use "git add" to track) + +Now let's add the changed file to the list of files tracked by git. + +.. code:: + + git add . + +Now let's commit that change. + +.. code:: + + git commit -s + +This will open up an editing session using your favorite command-line editor +where you will fill in a commit message. Add a commit message. + +.. note:: Note that for the Hyperledger Fabric project(s) we would have a + title line that includes the JIRA number of the issue to which the + change request applies. Please review the + :doc:`guidelines ` for change requests. + +.. code:: + + FAB-1234 + + I made a change + + Signed-off-by: John Doe + + # Please enter the commit message for your changes. Lines starting + # with '#' will be ignored, and an empty message aborts the commit. + # On branch foo + # Changes to be committed: + # new file: README.md + # + +Submitting your change request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once you have saved the commit message, you can push the change request +to Gerrit. Here, we have a couple of options. + +The first option is to use the full git syntax. + +.. code:: + + git push origin HEAD:refs/for/master + +This will yield results something like the following: + +.. code:: + + Counting objects: 3, done. + Delta compression using up to 4 threads. + Compressing objects: 100% (2/2), done. + Writing objects: 100% (3/3), 340 bytes | 0 bytes/s, done. + Total 3 (delta 1), reused 0 (delta 0) + remote: Resolving deltas: 100% (1/1) + remote: Processing changes: new: 1, refs: 1, done + remote: Missing issue-id in commit message + remote: Commit 539d9a1fe036f332db87d37b49cea705bdf6e432 not associated to any issue + remote: + remote: Hint: insert one or more issue-id anywhere in the commit message. + remote: Issue-ids are strings matching ([A-Z][A-Z0-9]{1,9}-\d+) + remote: and are pointing to existing tickets on its-jira Issue-Tracker + remote: + remote: New Changes: + remote: https://gerrit.hyperledger.org/r/16157 I made a change + remote: + To ssh://gerrit.hyperledger.org:29418/lf-sandbox + * [new branch] HEAD -> refs/for/master + +The second option, +`git review `__ simplifies +things a bit. The link above will provide info on how to install and setup +``git-review``. + +Once installed and configured, you can submit your change with ``git review``. + +:: + + $ git review + +Modifying your change request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to update your patch, say to address a review comment, or to fix +something affecting CI, you can commit revised changes with + +.. code:: + + git commit --amend + +and then repeat the ``git review`` or full syntax as before. + +Should you have further questions, please don't hesitate to ask on the mailing +list or rocket chat.