[esp-r] Procedures for ESP-r code contributions

[Ian Beausoleil-Morrison]

Dear ESP-r Community,

This is further to the email Alex Ferguson distributed regarding the
electronic meeting on November 7.  The purpose of this meeting is to
discuss and agree a set of procedures for contributing source code to
continue the evolution of ESP-r.

As most of you will be aware, ESP-r's source code's repository was
transitioned from a Subversion server to GitHub a number of months ago.
The transition to a new version control tool (git) has not been the
smoothest for many concerned (including me).  Moving forward, we are
planning on continuing to manage the "master" version of the source code on
GitHub.  However, support will no longer be provided for individual
developers to branch off "master" and to contribute code through "pull" or
"merge" requests.  Rather, a simple (admittedly unsophisticated) set of
procedures are being proposed and will be discussed during the electronic
meeting November 7.  The proposed set of procedures is outlined below.

I look forward to discussing this on November 7 so that we can move forward
on incorporating a number of lingering code contributions.

Regards,
- Ian



*Proposed code contribution procedures*


   1. Download a ZIP of the latest source from
   https://github.com/ESP-rCommunity/ESP-rSource.
   2. Extract the ZIP archive into a directory called "archive".
   3. Create a copy of "archive" using the following command: cp -R archive
   my-code
   4. Merge your code changes into the "my-code" directory.
   5. Run a recursive diff to ensure that the only differences between
   "archive" and "my-code" are your intended additions, deletions, and changes.
   6. Do a complete build of "archive" and "my-code".
   7. Run tester.pl to contrast the simulation predictions between
   "archive" and "my-code".
   8. Create a patch of your code changes using the following command: diff
   -rupN archive/ my-code/ > code-contribution.patch
   9. Email "code-contribution.patch" to the archivist using the email
   template below.


Email template for code contributions:

Send a note to the archivist using the template below once you have
completed these steps.

Summary of changes:
- If the submitted code bundles together numerous contributions, then
  provide a one or two sentence description of each. Use a separate point
  for each item and clearly indicate whether it provides new functionality
  for the user, repairs a bug, tidies code, or is a work in progress.  Do
not
  dwell on the details but rather provide a high-level description that
communicates
  the significance of the change to users and other developers.
- If new functionality is provided for the user, then indicate whether this
  affects the Simulator, the Project Manager, the Results Analyzer, etc.
  If this code affects the Project Manager or Results Analyzer, then
  detail this change from the user's perspective.  If a new model has been
  added, then provide a citation to a thesis or a paper that describes its
  theoretical basis.
- If a bug has been repaired, then indicate whether this affects the
  Simulator, the Project Manager, the Results Analyzer, etc.  If it affects
  simulation results, then detail under what circumstances.
- If this change tidies code without providing (at this point in time) new
  functionality or repairing a bug, then clearly indicate this.
- If this contribution is a work in progress that does not provide (at this
  point in time) new functionality or repair a bug, then clearly indicate
  this.
- IMPORTANT: Use proper grammar and spelling!


Testing summary:
- Successfully compiled GTK and X11 versions of ESP-r on Linux
  (GCC x.y.z).
- Successfully compiled X11 version on Cygwin (GCC x.y.z).
- Exercised relevant bps and prj menus for both GTK and X11
  versions on Linux. All menus found to work as expected.
- Ran tester.pl over complete test suite comparing archive to my-code using
  X11 version on Linux.  All test cases passed: no differences reported.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.strath.ac.uk/archives/esp-r/attachments/20141031/4889175a/attachment.html