Information about version control
---------------------------------

PLplot uses git for version control.  The fundamental git
documentation we refer to most often is the freely downloadable
[Pro Git Book](http://git-scm.com/book).

Installation of git is straightforward as described at
<http://git-scm.com/book/en/Getting-Started-Installing-Git>

To summarize that page, on Linux platforms git is available from a
system install; on Mac OS X platforms git is available from the
git-osx-installer project, MacPorts, and Homebrew; and on Windows
platforms git is available from the msysGit project.  In all cases, it
is highly recommended that git is run from the command line rather
than from a GUI.

PLplot currently uses the rebase git workflow 
[described here](http://kevinold.com/2013/04/17/my-git-workflow.html).

And summarized here:
1. *ALWAYS* develop on a branch:
   $ git checkout -b new_branch

   Develop followed by tests of that development followed by

   $ git commit
   
   to create commits in new_branch.  If you create a commit and
   realize before you make additional commits that there is an error
   in the commit, please use the --amend option to the subsequent
   commit that fixes the error.  What this option does is squash the
   two commits together, i.e., it replace the old commit with the
   error by the combined old commit and fix.  This approach minimizes
   errors in the commits that will eventually be merged to master (see
   below), and this cleaner master history will make subsequent use of
   git-bisect (a killer-app typically used to find which commit first
   caused a regression) much easier.

2. Updating the master branch:
   $ git checkout master
   $ git fetch
   (optional) review newly downloaded changes 
   $ git log origin/master
   $ git merge --ff-only origin/master

   Make sure that you are on the master branch before doing the
   merge. Failure to do so will mean having to undo the merge as
   merging master into your branch is bad and attempts to push
   your work back to official repo will be rejected.

3. Updating your working branch so that it is a linear
   continuation of the work on the master branch:
   $ git checkout new_branch
   $ git rebase master

   Note that there is some possibility for headaches here. If one 
   of the files that you are working on is changed in the master 
   branch you may have to deal with merge conflicts. Unless you
   really need some new feature in master (and you probably
   should not if your branch is really a self-contained topic)
   then it is probably best to do this once just before you want
   to push your work back to the official repo.

   Also, git rebase is not suitable if you are right in the
   middle of work on a topic with a dirty tree with uncommitted
   changes.  For this case use 

   $ git checkout new_branch # (checkout the dirty tree with uncommitted changes)
   $ git stash save # (save that dirty tree to make new_branch clean
                    # i.e., all uncommitted changes disappear).
   $ git rebase master # (update that clean branch)
   $ git stash pop # (restore your uncommitted changes)
   # ... keep working.... until you are ready to commit (and ultimately
   # merge back to master and push).
   
4. Incorporate changes back into master:
   $ git checkout master 
   $ git merge --ff-only new_branch

   At this point you should see a message like "Fast-forward". If
   instead you see "Merge made by the 'recursive' strategy" this
   is bad and means that your changes will be rejected when you
   try to push them to the official repo. You can inspect the
   history with gitk and possibly collapse the offending commits
   into a single commit (using git rebase --interactive) that makes
   the history linear again.

5. Push changes to the official repo:
   Check first:
   $ git push --dry-run origin master

   Push:
   $ git push origin master

This is a rebase work flow. The linearity of the master branch is 
enforced by server side hooks and by only allowing fast-forward
merges with the merge flag --ff-only. You can make this the
default option for your repository using the command:
   $ git config merge.ff only

This will add these two lines:
[merge]
	ff = only

To the .git/config file in the home directory of the PLplot project.

Note one drawback of a rebase workflow like adopted here is care must
be used in sharing development branches with others.  One such method
is to publish an experimental branch using some public repository like
those at github and asking others to have a look and make suggestions,
as long as everyone else understands that it is a "read only" branch
whose series of commits will disappear and be replaced by other
commits whenever that branch is rebased on the official master version
(which must occur, for example, before it is ff-merged with the master
branch).  Another method which has no such concerns at all is simply
to use patches generated by "git format-patch" to share development
branches on the plplot-devel mailing list.  Developers who subscribe
to that list can easily apply those patches with the "git am" command
on some private branch to evaluate them (unless there are explicit
file conflicts with the HEAD of master in which case the developer of
those series of patches would need to bring them up to date with
master by rebasing his private development branch before regenerating
the patch series).

Configuring the build system
----------------------------

The PLplot build system now requires CMake to configure the build on
all build platforms (Linux, Mac OS X, traditional Unix, and
Windows). The latest instructions for building PLplot with cmake can
be found on the PLplot wiki.

http://sourceforge.net/p/plplot/wiki/

Coding standards for PLplot
---------------------------

When writing / contributing code for PLplot the following standards are 
followed:

C: ISO C99 standards with POSIX.1-2001 base specification (required 
for a number of functions)
C++: ISO C++ 1998 standard plus amendents
Fortran 95: Fortran 95 standard

To check code it is recommended to try compiling with suitable compiler 
flags to enforce these standards and to enable compiler warnings to check
for dubious code.

For gcc / g++ / gfortran the following flags can be used

CFLAGS='-O3 -std=c99 -pedantic -D_POSIX_C_SOURCE=200112L -Wall  \
-Wextra -Wmissing-prototypes -Wstrict-prototypes -Wnested-externs \ 
-Wconversion -Wshadow -Wcast-qual -Wcast-align -Wwrite-strings' 
CCFLAGS='-O3 -fvisibility=hidden -std=c++98 -pedantic -Wall -Wextra'

FFLAGS='-std=f95 -O3 -fall-intrinsics -fvisibility=hidden -pedantic \
-Wall -Wextra'

Adherence to the standards should help make the code more portable.

Some notes and recommendations
------------------------------

- Use C++ style // comments rather than the older /* */ style comments. 
The only exception to this where a comment is embeded in a line of code, 
e.g. to comment out a parameter name in a function definition in C++. 

- To mark function parameters as unused and to suppress at least gcc
warnings about these, mark the parameter names with the PL_UNUSED( )
macro.

Styling of code
---------------

The uncrustify code beautifying program is used to style the source
code consistently and in a readable manner. Running the 
scripts/style_source.sh shell script can be used the check the 
source code and optionally apply any styling changes required.
