Development process documentation specifically about contribution

docs/conf.py

@@ -97,6 +97,8 @@
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False
 
+# If true, enable figure numbering
+numfig = True
 
 # -- Options for HTML output ----------------------------------------------
 

docs/developmentProcess/index.rst

@@ -0,0 +1,18 @@
+.. Developer Documentation for libCellML
+
+=================================
+libCellML Developer Documentation
+=================================
+
+This section of documentation is intended for developers.  libCellML uses Git for source code management (SCM), Buildbot for continuous integration testing and Github to host the software on the web.  The way in which these elements are brought together and how a developer is expected to use them forms the development process which is defined here.
+
+The repository at https://github.com/cellml/libcellml is the definitive repository for the software and used for creating software releases.  We will refer to this repository as the **prime** repository.  The developer documentation describes the Git branching model in use on the **prime** repository and the process to follow for getting new code added to this repository.  The process is designed to be as standard as possible.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   libcellml-development-setup
+   libcellml-development-contribution

docs/developmentProcess/libcellml-development-contribution.rst

@@ -0,0 +1,57 @@
+.. _Developer Contribution for libCellML:
+
+=================
+Contributing Code
+=================
+
+This section describes how to contribute to the libCellML project.  While there are many types of contribution, this section focuses on code and documentation contributions (and contributions of any other digital assets that are managed using the version control system).  We recommend that you have first read :doc:`Setup <libcellml-development-setup>`. 
+
+.. contents:
+
+Overview
+========
+
+An issue is used to initiate work and for overall discussion.  A pull request is created and referenced from the issue.
+
+Reviewers provide feedback on the changes by adding comments to the pull request or associated commits. The BuildBot build/test procedure will run each time changes are pushed to the pull request's branch, and the results are displayed in the pull request view.
+
+Once all the changes and reviews are complete, one of the :term:`prime repository` owners will merge the pull request into the prime repository, onto the develop branch.
+
+Note that a bug is just a type of issue, and that resolving the bug requires both a test that triggers the bug, as well as the implementation of the fix.
+
+Issue Assignment
+================
+
+If an issue has not been created for the required work (e.g. implementation of a feature, fixing of a bug), then create a new one. To assign yourself to the issue, leave a comment on the issue to that effect.
+
+
+Pull Request Collaboration
+==========================
+
+Pull the latest changes from the develop branch.  Create a branch with a name that briefly describes the work, based off the head of develop. This will be referred to as the topic branch.
+
+For code changes, an automated test should be the first code written and committed.
+Since it is expected that the test should compile and run, then, if this requires that the interface to the implementation is coded,
+this must be done too, and included in the commit.  One of the reasons requiring that a failing test
+is committed first is that it validates the test, since the test then only passes when the implementation is completed.  
+
+After the first commit, push to GitHub so that your work can be shared with others.
+
+Next, create a pull request from your topic branch targeting the :term:`prime repository`'s develop branch.  On the issue, post a comment with a reference to the pull request.  To reference the pull request from the issue in the GitHub comment area, type a hash, "#". A list will appear, from which you can select the pull request. The mark-up for creating the reference will then be automatically added.
+
+Once the work is ready for review, post a comment to the original issue requesting a review, including a reference to the pull request.
+GitHub sends notification to those subscribed to the issue and they will review the work, posting feedback on the commits within the pull request, or on the pull request itself.  Respond to this feedback as appropriate, e.g. making coding changes, posting a reply, etc.  Comments are also welcome earlier, since reviewers can see the work on the pull request from the start.  We are striving for a friendly atmosphere of social coding where developers can offer each other guidance and help.
+
+Sometimes it can take more than one pull request to resolve an issue, and not all pull requests will be merged, some my be closed without being merged. 
+
+Test Driven Development
+=======================
+
+Test driven development entails writing code that automatically tests the implementation before writing the implementation itself.  Running the tests prior to writing the implementation should cause the tests to fail, and running them after the implementation has been written should cause them to then pass.  This helps validate that the tests cover the required behaviour.  It is common to find that the initial implementation was incomplete (e.g. didn't cover all cases), but nevertheless, the tests didn't detect this.  This is addressed by improving the tests first, and then improving the implementation.  It can often take multiple cycles of modifying tests and implementation to complete the work.  Commit the code changes each time the tests are incrementally improved, and each time the implementation code passes the tests, or more often if necessary.
+
+Refactoring means improving the code without adding features, and the automated tests provide validation that the refactored code performs as well as before.
+
+Completion of Workflow
+======================
+
+Once the owners of the :term:`prime repository` are satisfied that the work on the issue is complete and that the feedback has been addressed, one of the owners will post a comment on the issue notifying subscribers that they intend to merge the pull request.  After allowing a suitable amount of time for any objections to be raised, and if none are raised, the owner will merge and close the pull request, and if no further work is required to resolve the issue, they will close the issue, stating that it has been resolved.

docs/developmentProcess/libcellml-development-setup.rst

@@ -0,0 +1,81 @@
+.. _Contributor Setup for libCellML:
+
+=================
+Contributor Setup
+=================
+
+This section describes how someone wanting to contribute to the libCellML project should set up their *working copy*.
+
+.. contents::
+
+Overview
+========
+
+Before you begin you will need to have a few prerequisites satisfied:
+
+#. GitHub user account (if necessary, create one using this link https://github.com/join ) (for the rest of this document we will call our user *libCellML-developer*)
+#. A Git client installed (see http://git-scm.com/downloads and http://git-scm.com/downloads/guis )
+
+This document doesn't cover the process of satisfying these prerequisites in any further detail.  The remainder of this document assumes that these prerequisites have been met.
+
+The goal here is to get a working copy of the project's files (i.e. source code, tests, and documentation, etc.) onto your
+ computer so that you can begin working.  Firstly, you need to fork the :term:`prime libCellML repository`, make a clone onto your
+ computer, and set up the Git remotes.  :numref:`Figure %s <libcellml-github-figure>` shows some of these setup actions and the
+ resulting setup.  It also shows the information flow for making contributions (steps 1 to 4).
+
+.. _libcellml-github-figure:
+.. figure:: images/libcellml-github.png
+   :align: center
+   :width: 600px
+   :alt: Setup of Git repository fork and clone
+
+   Setup of repository fork and clone
+
+The three steps to getting set up are detailed below.
+
+Forking your own copy
+=====================
+
+Login to GitHub with your user name and go to::
+
+  https://github.com/cellml/libcellml
+
+and fork this repository into your own GitHub user account.  This is done by clicking on fork.
+
+Clone
+=====
+
+You now need to clone the libcellml repository to your computer.  You do this by going to your fork (in this example, user libCellML-developer's fork) at:
+
+  https://github.com/libCellML-developer/libcellml
+
+.. note:: Don't clone this location.  Substitute your own GitHub user name in place of *libCellML-developer*.
+
+On the right hand side of the web page on your fork of the repository you can get the link for cloning the repository to your computer, in our example::
+
+  https://github.com/libCellML-developer/libcellml.git
+
+Now clone the repository. If using git from the command line on a Unix-like system, this is done as follows::
+
+  cd /somewhere/you/keep/project/files
+  git clone https://github.com/libCellML-developer/libcellml.git
+
+.. note:: Again, don't clone this location. Substitute your own user name in place of *libCellML-developer*.
+
+Set Git remotes
+===============
+
+You now need to setup a read-only remote connection to the :term:`prime repository`. To do this from the command line::
+
+  cd libcellml
+  git remote add prime https://github.com/cellml/libcellml
+  git config remote.prime.pushurl "you really didn't want to do that" #This is optional
+
+.. note:: The third command is optional, and only recommended if you have sufficient permission to push directly to the prime repository.
+
+You have now added a new remote named **prime** and set origin as the default fetch and push location to point at your fork on GitHub.  Here **prime** is a reference to the main definitive repository where releases are made for the libCellML project.  You have also optionally also set the **prime** repository as read-only by setting an invalid push URL.
+
+Finally
+=======
+
+This completes the set up.  Next, read :doc:`Contributing <libcellml-development-contribution>`, which explains how to get your changes accepted into libCellML's prime repository.

docs/glossary.rst

@@ -0,0 +1,12 @@
+.. _glossary:
+
+========
+Glossary
+========
+
+.. glossary::
+   :sorted:
+
+   Prime repository
+   Prime libCellML repository
+      The repository at https://github.com/cellml/libcellml is the definitive repository for the software and used for creating software releases.  We will refer to this repository as the **prime** repository.

docs/index.rst

@@ -15,7 +15,8 @@ Contents:
 
    roadmap
    usecases
-
+   developmentProcess/index
+   glossary
 
 
 Indices and tables