ADD Collaboration Guideline ReST content files.

Includes the Collaboration Guideline. It contains the infromation
regarding the use of the mailing list, Gerrit, the coding style and
other usefull collaboration information.

This Collaboration Guideline is constantly changing as new methods of
collaboration are used.


Change-Id: I9f1e66556e99defa8729f87f19052b539e8628d3
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>

doc/collaboration/collaboration.rst

@@ -0,0 +1,17 @@
+Collaboration Guidelines
+########################
+
+Thank you for your interest in collaborating with the Tiny Mountain
+project. These guidelines provide you an overview of the best ways to
+collaborate with the rest of the team. Read them carefully before
+submitting any work for review.
+
+.. toctree::
+   :maxdepth: 2
+
+   collaboration_rule1
+   collaboration_mailing
+   collaboration_patches
+   collaboration_gerrit
+   collaboration_coding
+   collaboration_maintainers

doc/collaboration/collaboration_coding.rst

@@ -0,0 +1,41 @@
+.. _Coding:
+
+Coding Style
+############
+
+Use this coding guideline to ensure that your development complies with
+the project's style and naming conventions.
+
+In general, follow the `Linux kernel coding style`_, with the following
+exceptions:
+
+* Add braces to every if and else body, even if it is a single line.
+  Use the :option:`--ignore BRACES` flag to make :program:`checkpatch`
+  stop complaining.
+* Use hard tab stops. Set the tab width to either 4 or 8 spaces. Train
+  :program:`checkpatch` to only warn when lines are over 100
+  characters. In general, break lines at 80 characters where possible.
+  If you are trying to align comments after declarations, use spaces
+  instead of tabs to align them.
+* Use C89-style single line comments, :literal:`/* */`. The C99-style
+  single line comment, //, is not allowed.
+* Use :literal:`/*! */` for any comments that need to appear in the
+  documentation.
+
+Checking for Conformity Using Checkpatch
+########################################
+
+The Linux kernel GPL-licensed tool, :program:`checkpatch` is used to
+check the conformity to the coding style. The tool is available in the
+scripts directory. To invoke :program:`checkpatch` when you commit
+code, edit your :file:`.git/hooks/pre-commit` file to contain:
+
+.. code-block::bash
+
+   #!/bin/sh
+
+   set -e exec
+
+   git diff --cached | /path/to/checkpatch.pl --no-signoff - || true
+
+.. _Linux kernel coding style: https://www.kernel.org/doc/Documentation/CodingStyle

doc/collaboration/collaboration_gerrit.rst

@@ -0,0 +1,395 @@
+.. include:: ../substitutions.rst
+
+Submitting a Patch Via Gerrit
+#############################
+
+
+Follow this instructions to collaborate on the |project| project using
+the infrastructure within Intel’s Open Source site, 01.org_. First, let
+us answer a couple of common questions regarding the use of Gerrit
+within |project|.
+
+#. Who has access to the Gerrit infrastructure?
+
+   Intel, WindRiver and other partners who have agreed to collaborate
+   in this project.
+
+#. How long will this infrastructure be used?
+
+   Until the project is transferred to the Linux Foundation.
+
+Make sure to subscribe to the `mailing list`_ by filling out the
+`registration form`_.
+
+.. _registration form: https://lists.01.org/mailman/listinfo/foss-rtos-collab
+
+.. _mailing list: foss-rtos-collab@lists.01.org
+
+.. contents:: Table of Contents
+   :depth: 2
+
+Configuring Gerrit Access
+*************************
+
+Gerrit access requires some basic user setup.  The following process has
+been defined as a simple walk-through to enable quick access to the
+Gerrit services.
+
+Accessing Gerrit
+================
+
+#. `Create`_ or `update`_ a 01.org_ account.
+
+#. Submit your your 01.org_ account and corporate email address to
+   |PM| `<mailto:hirally.santiago.rodriguez@intel.com>`_.
+
+#. Once access is granted, `access Gerrit`_.
+
+#. Log in using your 01.org account credentials.
+
+.. _Create: https://01.org/user/register
+
+.. _update: https://01.org/user/login
+
+.. _access Gerrit: https://oic-review.01.org/gerrit/
+
+.. _01.org: https://01.org/
+
+Configuring SSH to Use Gerrit
+=============================
+
+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 you would like to use, please skip
+down to step.
+
+Please follow the steps below to get started.
+
+1. Create a key-pair in your Linux machine, type:
+
+.. code-block:: bash
+
+   $ 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 at:
+:file:`~/.ssh/id_rsa and ~/.ssh/id_rsa.pub`.
+
+2. Add the the private key in the :file:`id_rsa` file in your key ring,
+type:
+
+.. code-block:: bash
+
+   $ ssh-add ~/.ssh/id_rsa
+
+3. Add your the public key :file:`id_rsa.pub` to the Gerrit account:
+
+   a. Go to `access Gerrit`_.
+
+   b. Click on your account name in the upper right corner.
+
+   c. From the pop-up menu, select :guilabel:`Settings`.
+
+   d. On the left hand menu select, click on
+   :guilabel:`SSH Public Keys`.
+
+   e. Click Add key and paste the contents of your public key
+   :file:`~/.id/id_rsa.pub`.
+
+.. note:: To obtain the contents of your public key
+   on a Linux machine type:
+   :command:`$ cat ~/.ssh/id_rsa.pub`
+   The output is the contents of :file:`~/.id/id_rsa.pub`.
+   Paste it into the Add SSH key window in Gerrit.
+.. warning:: Potential Security Risk 
+   Do not copy your private key :file:`~/.ssh/id_rsa` Use the public
+   :file:`~/.id/id_rsa.pub` instead.
+
+
+Coding with Gerrit
+******************
+
+Gerrit is a review system, and as such, assigns the following roles to
+users:
+
+* Submitter: Submit changes for consideration, review other code
+  changes and make recommendations for acceptance or rejection voting
+  +1 or -1, respectively.
+* Maintainers: Approve or reject changes based upon the feedback of
+  the reviewers voting +2 or -2, respectively.
+* Builder: Used for the build automation infrastructure.
+
+A comprehensive walkthrough of Gerrit is beyond the scope of this
+document. There are plenty of resources available on the Internet. A
+good summaries can be found here:
+`<https://wiki.iotivity.org/how_to_use_gerrit>`_
+`<https://gerrit-review.googlesource.com/Documentation/user-review-ui.html>`_
+
+For more detailed information visit:
+`<http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/intro-quick.html>`_
+
+
+Checking the Code Out
+=====================
+
+#. Ensure that SSH has been set up porperly. See
+   `Configuring SSH to Use Gerrit`_ for details.
+
+#. Clone the repository, type:
+
+   :command:`$ git clone ssh://01ORGUSERNAME@oic-review.01.org:29418/forto-collab`
+
+#. You have checked out a local copy of the source code. Develop
+   freely, issuing as many commits and rebases as needed.
+
+
+Submitting a Patch
+------------------
+
+Currently, there is only one method to submit a patch for review:
+
+**Gerrit**
+
+Before you submit, please ensure each of your commits conform with the
+coding and contribution guidelines of the project. Directions for
+building the source code are out of the scope of this document. Please
+refer to the :ref:`Install`.
+
+When a patch set is ready for submission, Gerrit requires that the
+changes 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 |project|, the special branch is called refs/for/master .
+
+1. Push the current local development branch to the gerrit server, type:
+
+.. code-block:: bash
+
+   $ git push origin HEAD:refs/for/master
+
+If the command is executed correctly,the output should look similar to
+this:
+
+.. code-block:: bash
+
+   Counting objects: 4, done. Compressing objects: 100% (2/2), done.
+   Writing objects: 100% (3/3), 325 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: remote:
+   New Changes: remote: https://oic-review.01.org/gerrit/1045 This is
+   test #1 remote: To ssh://oic-review.01.org:29418/forto-collab
+   * [new branch]      HEAD -> refs/for/master
+
+The gerrit server generates a
+`link <https://oic-review.01.org/gerrit/1045>`_ where the change can be
+tracked.
+
+2. Add reviewers to your patch.
+
+  a. To Define the list of reviewers via the command line at code
+  submission time. Add *%r=reviewer@project.org* to the command. For
+  example:
+
+.. code-block:: bash
+
+   $ git push origin
+   HEAD:refs/for/master%r=rev1@email.com,rev2@notemail.com`
+
+
+  b. Autoconfigure GIT to add a set of reviewers if your commits will
+  have the same reviewers all at the time.
+
+      i. In the cloned repo, open the :file:`.git/config` file.
+
+      ii. Add the following line in the
+      :literal:`[ branch “master” ]` section:
+
+.. code-block:: bash
+
+      [branch "master"] #.... push =
+      HEAD:refs/for/master%r=rev1@email.com,rev2@notemail.com`
+
+.. note::
+   In the examples, actual email addresses should be used instead of the
+   :literal:`@email.com and @notemail.com` addressses.
+   
+Reviewing Using Gerrit
+**********************
+
+ An example of a gerrit patch review page:
+
+.. figure:: figures/gs_collaboration_gerrit01.png
+   :scale: 75 %
+   :alt: Gerrit Review Page
+   
+   An example of a Gerrit change review page.
+
+   The fields highlighted in yellow are of interest and require a
+   little more explanation.
+   
+* Add: This button allows the patch submitter to manually add names of
+  people who should review this changeset; type 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 only available to the submitter, allowing
+  the committer to abandon this changeset and get no more work done on
+  it.
+* Change-ID: This is an ID generated by Gerrit (or system). This is
+  useful when the review process determines that your commit(s) have to
+  be redone. You can upload 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 patch is in review status, as indicated by
+  the “Needs Code-Review” 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 page <https://oic-review.01.org/gerrit/#/dashboard/self>`_,
+to check the progress of your requests.
+
+Click on a request and the history tab shows you the feedback.
+
+.. figure:: figures/gs_collaboration_gerrit02.png
+   :scale: 75 %
+   :alt: Gerrit Feedback Page
+
+   An example of how feedback is displayed on Gerrit.
+
+Viewing Pending Patches
+=======================
+
+1. Find all the pending patches by clicking on the
+:menuselection:`All --> Changes` link in the upper left corner or
+directly at:
+`<https://oic-review.01.org/gerrit/#/q/project:forto-collab>`_
+
+If you collaborate in multiple projects, you may wish to limit the
+branch through the search bar in the upper right side.
+
+Add the filter *project:forto-collab* to limit the visible patches only
+to those of the forto-collab project.
+
+2. List all current patches you submitted or those patches in need of
+your input by clicking on :menuselection:`My --> Changes` or going to:
+`<https://oic-review.01.org/gerrit/#/dashboard/self>`_
+
+Reviewing a Patch
+-----------------
+
+1. Click on a the link for incoming or outgoing review, such as
+*“This is test #1”* shown in this figure:
+
+.. figure:: figures/gs_collaboration_gerrit03.png
+   :scale: 75 %
+   :alt: Incoming and Outgoing Reviews
+
+   An example of incoming and outgoing items in review.
+
+2. The details of the patch and its current status are loaded:
+
+
+.. figure:: figures/gs_collaboration_gerrit04.png
+   :scale: 75 %
+   :alt: Detailed View of a Patch in Gerrit
+
+   An example of the detailed view of a patch in Gerrit.
+
+   The highlighted items require further explanation.
+
+From left to right:
+
+* **The state:** Displays the current status of the patch. In the
+  example the status reads: +l Needs Code-Review.
+
+* **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
+  allows navigation between the 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.
+
+3. Underneath the commit information, a list shows the files that have
+been changed by this patch:
+
+.. figure:: figures/gs_collaboration_gerrit05.png
+   :scale: 75 %
+   :alt: Changed Files Example
+
+   Observe the list of the files changed by the patch at the bottom.
+
+4. Click on a filename to start reviewing it.  Select the code base to
+differentiate against. The default is Base and it will generally be
+what is needed.
+
+.. figure:: figures/gs_collaboration_gerrit06.png
+   :scale: 75 %
+   :alt: Code Base Location
+
+   Shows where to change the comparison base version on the review page.
+
+5. 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 highlighted 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.
+
+.. figure:: figures/gs_collaboration_gerrit07.png
+   :scale: 75 %
+   :alt: Review Page Navigation Highlights
+
+   Highlights the navigation options of the review page.
+
+
+6. The focus of the page is on the comparison window. The changes made
+are presented in pink on the left versus the base version on the right.
+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.
+
+.. figure:: figures/gs_collaboration_gerrit08.png
+   :scale: 75 %
+   :alt: Commenting on a Code Section
+
+   Shows how to add a comment in the comparison window.
+
+7. After adding the comment it is saved as a draft.
+
+.. figure:: figures/gs_collaboration_gerrit09.png
+   :scale: 75 %
+   :alt: Saved Comment as Draft
+
+   Shows a comment saved as a draft.
+
+8. Once you are done commenting all the files of the patch, click the
+green up arrow at the top right to return to the main patch 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
+patch 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.
+
+.. figure:: figures/gs_collaboration_gerrit10.png
+   :scale: 75 %
+   :alt: Submitting the Final Comment and Review
+
+   Shows the dialog box for submitting the final comment and the review 
+   score of a patch.

doc/collaboration/collaboration_mailing.rst

@@ -0,0 +1,64 @@
+Rules for Collaboration on an Open Source Mailing List
+######################################################
+
+Follow these rules to effectively use the mailing list and get as much
+feedback as possible on your work.
+
+* Use the mailing list as much as possible.
+
+* Learn the rules.
+
+* Read the archives if in doubt.
+
+* Choose a meaningful subject line.
+
+* Ask questions and write to the subject matter experts directly and
+  CC the mailing list.
+
+* Before doing any large coding work, send a design document with your
+  proposed changes to the mailing list. This will save you from losing
+  time implementing a solution that the community may reject.
+
+* Write briefly and to the point but give enough context for someone
+  to respond without recreating your thought process.
+
+* Be persistent if you are not getting a response but be measured.
+
+* Write a separate email each work item. If they are connected, say so
+  in each email.
+
+* Don't rehash old issues.
+
+* Only reply if you can provide new information or a new perspective.
+  Avoid "me-too" posts.
+
+* When replying in-line to a mail that was CC'ed to the list, trim out
+  unnecessary context between replies and at the end of your mail.
+
+* Do not use capital letters to emphasize a point.
+
+* Make sure your lines are between 72 to 76 characters long.
+
+References
+**********
+
+* General info:
+
+   + http://linux.sgms-centre.com/misc/netiquette.php
+
+   + http://www.ietf.org/rfc/rfc1855.txt
+
+   + http://www.infradead.org/~dwmw2/email.html
+
+   + http://www.arm.linux.org.uk/mailinglists/etiquette.php #e3
+
+   + http://lifehacker.com/5473859/basic-etiquette-for-emai
+     l-lists-and-forums
+
+* Reasons why top posting considered harmful:
+
+   + https://lkml.org/lkml/2005/1/11/111
+
+   + http://www.dickgaughan.co.uk/usenet/guide/faq08-topp.html
+
+   + http://www.mail-archive.com/brin-l@coollist.com/msg00178.html

doc/collaboration/collaboration_maintainers.rst

@@ -0,0 +1,9 @@
+Information Regarding Maintainers
+#################################
+
+Read this information to learn how maintainers review changes using Gerrit.
+
+Once a change is sent to Gerrit for review the maintainers
+receive an email requesting them to review the change. The master
+branch should never be rebased. Code can be reverted as necessary,
+instead of rewriting the history.

doc/collaboration/collaboration_patches.rst

@@ -0,0 +1,77 @@
+Submitting a Patch
+##################
+
+Read the following information carefully before submitting a patch. It
+applies for developers that are new to open source as well as for
+experienced open source developers.
+
+New to Open Source?
+*******************
+
+Welcome to open source software development. Whether you are an
+experienced developer within a corporate environment, a beginner trying
+out something new or someone in between, we thank you for your interest
+in the development of Tiny Mountain.
+
+Before you begin we suggest you read the `Patch Philosophy`_.
+
+.. _`Patch Philosophy`: http://kernelnewbies.org/PatchPhilosophy
+
+Be sure to read the documentation before submitting any patches.
+
+It is of great importance that each patch includes a Signed-off-by line,
+containing your full legal name. Adding your Signed-off-by line means
+you assert this patch meets the legal requirements of the
+`developer certificate of origin`_. Read and understand that document
+before contributing code or documentation to the project.
+
+.. _`developer certificate of origin`: http://developercertificate.org/
+
+Patch Requirements
+******************
+
+Here you can find the required format and content for patches. For more
+information on how to submit a patch using Gerrit please refer to
+`Submitting a Patch Via Gerrit`_.
+
+Each patch must contain a short descriptive subject line, typically less
+than 72 characters, a patch description, and a Signed-off-by line. A
+patch with all three is considered well formed. A patch set must have
+all three plus a cover letter to be considered well formed.
+
+All patches and patch sets sent to Gerrit must be well formed. Commit
+messages must include “what” the patch does, “why” you chose that
+approach, what assumptions you made and “how” you know it works, for
+example, which tests you’ve run.
+
+
+Commits must build cleanly when applied in top of each other, thus
+avoiding breaking bisectability. Commits must pass the
+:file:`scripts/checkpatch.pl` requirements. For more details see the
+:ref:`Coding` section. 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.
+
+Every commit must contain the following line at the bottom of the commit
+message:
+
+Signed-off-by: your@email.address
+
+The name in the Signed-off-by line and your email must match the patch
+authorship information. Make sure your *.git/config* is set up
+correctly. Always submit the full patchset via Gerrit.
+
+When a patch is included in the set to enable the other patches but it
+will not be part of the final set, let the reviewers know this. Use
+requests for comment (RFCs) to send work proposals, progress snapshots
+of your work or to get early feedback on features or changes that will
+affect multiple areas in the code.
+
+Before you submit, please ensure each of your commits conforms with the
+coding and contribution guidelines of the project found in
+`Patch Requirements`_.
+
+If you are submitting a patch that has someone else's Signed-off-by make
+sure that you include that person as a Reviewer in Gerrit.

doc/collaboration/collaboration_rule1.rst

@@ -0,0 +1,14 @@
+The Most Important Rule of Open Source
+######################################
+
+Open source is about sharing as much information as possible about the
+development you are doing. Maintainers and contributors must
+communicate and with each other using the open source collaboration
+tools: the mailing list, Gerrit and JIRA. We strive to be open about
+our work, making sure to include all key community stake holders, both
+maintainers and expert developers, and the community mailing list.
+
+In this spirit, do not send private feedback through email. Instead,
+send feedback to the mailing list, making sure to hit 'Reply-to-all',
+and keeping the CC list intact. While the mailing list can be used to
+hold design discussions, remember to submit all patches using Gerrit.