sort out contributor role with clear advantages, responsibilities and…

… procedure

.gitignore

@@ -7,3 +7,4 @@ target
 *.pyc
 nb-configuration.xml
 *.*~
+.DS_Store

docs/developer/procedures/contribute.rst

@@ -3,12 +3,37 @@ Contribute
 
 When submitting a patch or :doc:`pull request </procedures/pull_requests>`:
 
-* Small: Fix to one existing file, reviewer has your permission to apply the change
-* Large: Greater than a file, :doc:`contribution_license` is required
+* Small Contribution / Single Source Code File
 
-For details check the :doc:`contributor </roles/contribute>` role and responsibility page.
+  For a very small change (less than one file) a committer can review and apply the change on
+  your behalf. This is a quick workaround allowing us to correct spelling mistakes in the
+  documentation, clarify a javadoc, or accept a very small fix.
 
-.. admonition:: Talk first policy
+  We understand you may have to update several test cases to verify your change fixes its
+  intended problem.
+
+* Large Contributions / Multiple Files / New Files
+
+  To  contribute a new file, or if your change effects several files, sign a :doc:`contribution_license`.
+
+Procedure:
+
+* :doc:`contribution_license`
+
+Role and Responsibility:
+
+* :doc:`/roles/contributor`
+
+.. admonition:: Jira
+
+   Jira tracks features as well as bugs. By creating an issue the change will be listed in the GeoTools release notes.
+
+Code Contributions
+------------------
+
+Regardless of what you want to achieve, there are some common steps to consider:
+
+#. Talk first policy
 
    Unless you intend to provide a trivial change (fixing typos in the documentation, easy bugfix
    with test) the very first thing you should do is to subscribe to the :doc:`GeoTools developer
@@ -20,16 +45,72 @@ For details check the :doc:`contributor </roles/contribute>` role and responsibi
      the desired results
    * It makes it easier to review the pull request/patch as its content are already known and
      agreed upon
+
+#. Create a local branch::
+
+     git checkout -b fix_featureLock
+
+#. Work on the fix, using commit as needed.
 
-.. admonition:: Jira
+   * **Please remember to always include a test case, most pull requests/patches will be rejected if they don't contain one.**.
 
-   Jira tracks features as well as bugs. By creating an issue the change will be listed in the GeoTools release notes.
+   * Please make sure you're following the :doc:`coding conventions </conventions/code/style>`,
+     and otherwise avoid any reformats to the existing code, as they make it harder to review your
+     changes.
+
+     If you find sections not following the coding convetions and you want to amend their
+     formatting, that's fine, please do so in a separate commit/patch from the real code changes.
 
-.. admonition:: Master First
+#. Review the work that was done, make sure the changes contain all the files you need, and no other extraneous change.::
+
+     git status
    
-   Changes cannot be accepted directly onto the stable branch, and should be applied to master first.
+   In case you're making a pull request, single commit ones are preferred, you can use ``rebase -i`` to squash multiple commits into one, it's fine to have two commits if one is used to isolate code formatting changes
+
+#. Rebase the branch from master so you get a nice clean set of changes::
+
+      git pull --rebase master
+
+#. Do a full maven build (with tests) to make sure your fix compiles cleanly::
+
+      mvn clean install -Dall
+
+   .. admonition:: Don't break the Build
+   
+      We do have this nice rule about breaking the build (don't).
    
-   We are able to accept fixes and changes that do not break compatibility onto the stable branch after they have been tested on master.
+      This means that if you are working on core interfaces you will be running all over the place
+      cleaning up modules. One very good reason to talk to the list first is to give other module
+      maintainers a chance to get out of the way, or offer to help you clean up the mess.
+
+   .. admonition:: Master First
+   
+      Changes cannot be accepted directly onto the stable branch, they need to be tried out on master first.
+      
+      We are able to accept fixes and changes that do not break compatibility onto the stable branch after they have been tested on master.
+
+#. Submit pull request: for instructions on submitting a pull request see `Using Pull Requests <https://help.github.com/articles/using-pull-requests>`_ on GitHub.
+
+  Pull requests are reviewed by module maintainers as outlined in :doc:`/procedures/pull_requests`.
+
+   .. admonition:: Patch
+
+      Pull requests are generally reviewed faster (as we have build infrastructure in place to test
+      them). However attaching a patch to a JIRA issue is an alternative:
+
+      #. Create the patch::
+
+           git format-patch master > featureLock.patch
+
+      #. Open a JIRA issues against the subsystem in which the patch was made, the subject should
+         describe the contribution and ideally mention that a patch is included. Example: `Patch
+         for FeatureLock concurrency failure`
+
+      #. JIRA will automatically notify the maintainer of the module (since that is the best person
+         to do the code review). If no one answers or comments in the subsequent few days, then the
+         contributor can contact the developers' mailing list to let everyone know about the patch
+         and find someone else competent to review the code and integrate the contribution into the
+         code base or provide a request for improvements to the patch.
 
 Breaking published API or performing major changes on existing modules
 ----------------------------------------------------------------------
@@ -38,32 +119,45 @@ Any change involving a break in existing API (e.g., changing an interface, addin
 to an abstract class) and any significant change affecting more than one module should go through a
 formal proposal, that will be discussed and voted on the developer mailing list.
 
-Please consult the :doc:`proposal procedure page </procedures/proposal>` procedure for more details.
+Procedure:
 
-.. admonition:: Don't break the Build
-
-   We do have this nice rule about breaking the build (don't).
-
-   This means that if you are working on core interfaces you will be running all over the place
-   cleaning up modules. One very good reason to talk to the list first is to give other module
-   maintainers a chance to get out of the way, or offer to help you clean up the mess.
+* :doc:`/procedures/proposal`
 
-Adding a New Module
--------------------
+Role and Responsibility:
+
+* :doc:`/roles/committer`
+
+New Module
+----------
 
 You may be reaching out to GeoTools in order to add a new module to the library. That is fine and appreciated, in this case you should follow two extra steps:
 
-* You need to ask for a new "unsupported" module on the developer mailing list. This is a request for :doc:`/roles/commit` access.
+* You need to ask for a new "unsupported" module on the developer mailing list. This is a request for :doc:`/roles/committer` access.
 * Since you're certainly adding new files, you'll have to sign a contributor agreement
 
-See the :doc:`create` procedure for more information.
+Procedure:
+
+* :doc:`create`
+
+Role and Responsibility:
+
+* :doc:`/roles/committer`
 
-.. admonition:: Supported Modules
+Supported Module
+----------------
 
-   When ready your module can be included in the normal build for everyone; and you can go through the quality assurance procedures checks to make the module a :doc:`supported` part of GeoTools.
+When ready your module can be included in the normal build for everyone; and you can go through the quality assurance procedures checks to make the module a :doc:`supported` part of GeoTools.
+
+Procedure:
+
+* :doc:`supported`
+
+Role and Responsibility:
+
+* :doc:`/roles/maintainer`
 
-Work on existing Module
------------------------
+Existing Module
+---------------
 
 Be sure to discuss any change with the module maintainer on the developer list before starting work. Module maintainers have volunteered to look after the module and may be aware of other development teams working in this area or know of plans that can effect your work.
 

docs/developer/procedures/contribution_license.rst

@@ -3,7 +3,7 @@ Code Contribution License
 
 GeoTools has adopted a formal policy as part of the process of joining the Open Source Geospatial Foundation (OSGeo).
 
-All new :doc:`contributors </roles/contribute>` will be required to grant copyright to the foundation using a `Contributor Licenses <http://www.osgeo.org/content/foundation/legal/licenses.html>`_:
+All new :doc:`contributors </roles/contributor>` will be required to grant copyright to the foundation using a `Contributor Licenses <http://www.osgeo.org/content/foundation/legal/licenses.html>`_:
 
 * :download:`individual_contributor.txt </artifacts/individual_contributor.txt>`
 * :download:`corporate_contributor.txt </artifacts/corporate_contributor.txt>`

docs/developer/procedures/pull_requests.rst

@@ -32,7 +32,7 @@ When submitting your pull request:
 * Note any associated JIRA number
 * Link to any change proposal related to the pull request
 * Include a test case
-* If the change less than a file in size the reviewer can commit it on your behalf, over a file in size you will need to sign a :doc:`code contribution </roles/contribute>` agreement.
+* If the change less than a file in size the reviewer can commit it on your behalf, over a file in size you will need to sign a :doc:`contribution license <contribution_license>`
 
 .. note:: Jira is used as the project issue tracker. You can include a link to a pull request
    in JIRA as an alternative to a patch.

docs/developer/roles/commit.rst → docs/developer/roles/committer.rst

@@ -8,13 +8,13 @@ Advantages
 ----------
 
 * Work on your own unsupported module
-* Apply your own patches - after they have been reviewed
+* Apply your own pull requests / patches - after they have been reviewed
 
 Responsibilities
 ----------------
 A Committer has write access to the whole source code repository which entails certain responsibilities.
 
-* Committers must coordinate their efforts with the maintainers of any modules they wish to modify or extend, i.e. committers need to ask permission. Contact details for each module's maintainer can be found in the source code as part of the pom.xml file or in the Module Matrix. If committers are working in their own module, then they are themselves maintainers of that module and they can do as they wish in that module only.
+* Committers must coordinate their efforts with the maintainers of any modules they wish to modify or extend, i.e. committers need to ask permission. Contact details for each module's maintainer can be found in the source code as part of the :file:`pom.xml` file or in the Module Matrix. If committers are working in their own module, then they are themselves maintainers of that module and they can do as they wish in that module only.
 
 * Committers are expected to follow GeoTools conventions. They are required to read this developer's guide. Committers are responsible for any code they submit which means they are required to know and correctly document the origin of any code they submit and required to ensure they are legally allowed to submit and share that code.
 
@@ -30,7 +30,7 @@ This means that all code should be run through a full maven install and test cyc
 
    mvn clean install -Dall
 
-prior to commit. Yes, this takes time; yes, it is necessary.
+Prior to commit. Yes, this takes time; yes, it is necessary.
 
 Process
 -------
@@ -84,7 +84,6 @@ Process
        * :download:`individual_contributor.txt </artifacts/individual_contributor.txt>`
        * :download:`corporate_contributor.txt </artifacts/corporate_contributor.txt>`
 
-
 4. Getting write access to the repository
 
    Once we have confirmation that you have sent in the document any GeoTools committer can grant

docs/developer/roles/contributor.rst

@@ -0,0 +1,60 @@
+Contributors
+============
+
+Initially, newcomers to the project generally participate in an informal role as a contributor. These types of contributors have no long term responsibility to the project.
+
+Contributor Advantages
+----------------------
+
+* Ability to submit large pull requests and patches
+* Recognition as an open source contributor
+* We do our best to thank contributors in the GeoTools release notes
+
+.. note:: Looking for work? Recognition can take the form of a letter of reference from a PMC member. Participating in open source is a great way to build experience.
+
+Contributor Responsibilities
+----------------------------
+
+#. Talk to the developer list prior to starting any major work.
+
+#. Code Contribution License: ensure you are comfortable providing the Open Source Geospatial Foundation with access to your work. If you are employee you will need to talk to your manager as well.
+
+   For details see :doc:`/procedures/contribution_license`.
+
+#. Large contributions should include the contributor name in the list of authors of the class documentation for any file in which the contributor has made significant changes. That is the contributor's name should be added using the @author javadoc tag.
+
+Contributor Process
+-------------------
+
+#. In order to volunteer as a Contributor you need to submit a change:
+
+   * Small Contribution / Single Source Code File
+
+     For a very small change (less than one file) a committer can review and apply the change on
+     your behalf. This is a quick workaround allowing us to correct spelling mistakes in the
+     documentation, clarify a javadoc, or accept a very small fix.
+
+     We understand you may have to update several test cases to verify your change fixes its
+     intended problem.
+
+   * Large Contributions / Multiple Files / New Files
+
+     To  contribute a new file, or if your change effects several files, sign a :doc:`/procedures/contribution_license`.
+
+   Procedure:
+
+   * :doc:`/procedures/contribute`
+
+#. We also need to check that you have a contribution license on file with OSGeo.
+
+   Procedure:
+
+   *  :doc:`/procedures/contribution_license`.
+
+#. Review
+
+   Keep in mind that we have limited volunteers to review your work. Providing a test case, using the project source code formatting, and being available to answer questions all contribute to making you change easier to evaluate and accept.
+
+   Procedure:
+
+   *  :doc:`/procedures/pull_requests`

docs/developer/roles/index.rst

@@ -2,13 +2,13 @@
 Roles and Responsibilities
 ***************************
 
-Anyone can contribute to the GeoTools project by editing the web site, by writing documentation, by answering questions on the email list, or by contributing code directly into the project.
+Anyone can participate in the GeoTools project by editing the web site, by writing documentation, by answering questions on the email list, or by contributing code directly into the project. The following roles capture some of the responsibilities of working on shared code.
 
 
 .. toctree::
    :maxdepth: 1
 
-   contribute
-   commit
-   maintain
+   contributor
+   committer
+   maintainer
    committee