Merge pull request #48 from zbeekman/contributing-issue-47

Adds CONTRIBUTING guidlines, fixes #47

Author: jacobwilliams

CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to [json-fortran](README.md)
+
+Looking to contribute something to [json-fortran](README.md)? **Here's how you can help.**
+
+## Key Branches
+
+- `master` is the latest, development version and all efforts should be made to keep it stable.
+
+## Filing issues
+
+- Before filing a new [issue](https://github.com/jacobwilliams/json-fortran/issues), please perform a search to see if that issue has already been filed by someone else, and whether or not a solution exists. If you are experiencing the same issue as one that's already posted, please leave any additional comments and information under the existing issue. If your issue is related to a previous issue, but substantively different, file a new issue and include a mention of the related issue in text, using GitHub's `#<issue-number>` syntax.
+- When filing an issue please try to include all of the following information
+  1. Problem description: What behavior are you seeing that you think is erroneous
+  1. Installation method: Did you build the code with one of the included build scripts? Some other way? Install from a binary package?
+  1. What type of system you are on: E.g., 64 bit Intel Mac OS X 10.10.2 (Yosemite) or x86_64 Ubuntu 14.04 LTS (Trusty Tahr)
+  1. If applicable, what compiler you used, and any non-standard options or configurations that were used.
+  1. All steps required to reproduce the problem
+
+## Outstanding Work
+
+- Take a look at the [issues](https://github.com/jacobwilliams/json-fortran/issues) to see if there is an issue you'd like to help address. [Issues](https://github.com/jacobwilliams/json-fortran/issues) with the [ready label](https://github.com/jacobwilliams/json-fortran/issues?q=is%3Aopen+is%3Aissue+label%3A%22ready%22) or in the [ready column on waffle.io](https://waffle.io/jacobwilliams/json-fortran) are issues that are ready to be dealt with. (i.e., They are not blocked by other dependencies and are higher priority.)
+
+## Pull Requests
+
+- Try not to pollute your pull request with unintended changes--keep them simple and small
+- Pull requests should address one issue at a time, and each commit should be a set of self contained, related changes. If you forget something in a commit, please use `git rebase -i <ref>^` to amend and/or squash erroneous commits. Here `<ref>` is the reference to to oldest commit needing to be modified (SHA, or `HEAD~4`, etc.)
+- Each commit should compile, and ideally pass the tests. Very complicated new features or fixes, may have commits that don't pass tests, if otherwise the commit history would include far to many changes in any given commit. Use an interactive rebase to fix any of these issues, as described above.
+- Pull requests should always be based on the upstream master, jacobwilliams/json-fortran:master. Please `rebase` your branch on top of the latest upstream master. Assuming you've added the upstream remote by running something like:
+```
+git remote add upstream git://github.com/jacobwilliams/json-fortran.git
+```
+You can accomplish this by running:
+```
+git rebase upstream
+```
+- Create a branch in your fork with a descriptive name that also includes the [issue number](https://github.com/jacobwilliams/json-fortran/issues), if applicable. For example, after forking the repo, you can run something like `git checkout -b Unicode-support-issue-35` before starting work on [issue #35 : Unicode support](https://github.com/jacobwilliams/json-fortran/issues/35)
+- When you're content with your changes, your commits are clean, self contained, with concise descriptive messages, and your changes compile and pass the tests, submit a pull request. We will review your changes, and may ask for certain modifications to be made.
+- Pull requests are tested by our [travis-ci](https://travis-ci.org/jacobwilliams/json-fortran) continuous integration system, and any errors uncovered will need to be fixed before the pull request can be merged into master.
+
+## Coding Standards
+
+- Each commit should address a single logical change and code base transformation.
+- Each commit **must** compile.
+- Each commit should pass the tests unless the feature being implemented or bug being fixed requires extensive changes that would result in a commit with too many different changes.
+- No extraneous white spaces are allowed to be introduced at line endings and all non binary files should end with a single new line. Run `git config core.whitespace trailing-space,space-before-tab,blank-at-eol,blank-at-eof` to setup the whitespace rules from within your fork, and then check for white space errors with `git diff --check` to see if you have accidentally introduced white space errors before committing. (You can also enable the sample `pre-commit` hook that ships with git, to prevent you from committing changes that introduce white space errors. See [this stackoverflow question](http://stackoverflow.com/questions/591923/make-git-automatically-remove-trailing-whitespace-before-committing/28446440)) for some tips on preventing the introduction of whitespace errors.
+- Please adhere to the code indentation and formatting as it currently exists, aligning common elements vertically, etc.
+- *Do NOT* allow your editor to make a bunch of indentation or white space changes, that will introduce non-substantive changes on lines that you have not actually edited.

README.md

@@ -5,18 +5,19 @@ A Fortran 2008 JSON API
 
 Status
 ------
-[![Build Status](https://travis-ci.org/jacobwilliams/json-fortran.svg?branch=master)](https://travis-ci.org/jacobwilliams/json-fortran)
+[![Build Status](https://img.shields.io/travis/jacobwilliams/json-fortran/master.svg?style=plastic)](https://travis-ci.org/jacobwilliams/json-fortran)
 [![GitHub issues](https://img.shields.io/github/issues/jacobwilliams/json-fortran.png?style=plastic)](https://github.com/jacobwilliams/json-fortran/issues)
-[![Ready in backlog](https://badge.waffle.io/jacobwilliams/json-fortran.png?label=Ready&title=Ready)](https://waffle.io/jacobwilliams/json-fortran)
+[![Ready in backlog](https://badge.waffle.io/jacobwilliams/json-fortran.png?label=Ready&title=Ready)](https://github.com/jacobwilliams/json-fortran/#contributing-)
 [![In Progress](https://badge.waffle.io/jacobwilliams/json-fortran.png?label=In%20Progress&title=In%20Progress)](https://waffle.io/jacobwilliams/json-fortran)
+[![Needs Review](https://badge.waffle.io/jacobwilliams/json-fortran.png?label=Needs%20Review&title=Needs%20Review)](https://waffle.io/jacobwilliams/json-fortran)
 
 Brief description
 ---------------
 
 An easy-to-use API for reading and writing JSON files, written in
 modern Fortran.  The source code is a single Fortran module file ([json_module.f90](https://github.com/jacobwilliams/json-fortran/blob/master/src/json_module.f90)).
 
-Download
+Download [![GitHub release](https://img.shields.io/github/release/jacobwilliams/json-fortran.svg?style=plastic)](https://github.com/jacobwilliams/json-fortran/releases)
 --------------------
 
 Download the official versioned releases [here](https://github.com/jacobwilliams/json-fortran/releases).  Or, get the latest development code from the master branch [here](https://github.com/jacobwilliams/json-fortran.git).
@@ -26,7 +27,7 @@ Building the library
 
 The code requires a Fortran compiler that supports
 various Fortran 2003 and Fortran 2008 features such as: allocatable
-strings, newunit, generic, class, and abstract interface.
+strings, `newunit`, `generic`, `class`, and `abstract interface`.
 It has been successfully compiled with the [Intel Fortran compiler
 13.1.0](https://software.intel.com/en-us/non-commercial-software-development) (and greater) and the recent [4.9 release of the GNU gfortran
 compiler](http://gcc.gnu.org/wiki/GFortran/News#GCC4.9).
@@ -38,7 +39,7 @@ Currently, several ways are provided to build the jsonfortran library
 
 * A [Visual Studio](http://www.visualstudio.com) project is included for building the library (and example program) on Windows with the Intel Fortran Compiler.  The project has been tested with Visual Studio 2010 and 2013.
 
-* An [SCons](http://www.scons.org) `SConstruct` file.  The library and example program are built by typing `scons` and installed by `scons install` or `sudo scons install`. 
+* An [SCons](http://www.scons.org) `SConstruct` file.  The library and example program are built by typing `scons` and installed by `scons install` or `sudo scons install`.
 
 * Additionally, a [CMake](http://www.cmake.org) build
 system is provided. This build system has been tested on Mac and Linux
@@ -130,7 +131,7 @@ To print the JSON file (either to a file or the console), the ```print_file``` m
 
 ```fortran
     call json%print_file()         !prints to the console
-    call json%print_file(iunit)    !prints to the file connnected to iunit
+    call json%print_file(iunit)    !prints to the file connected to iunit
 ```
 
 Building a JSON file from scratch
@@ -142,7 +143,7 @@ of ```json_value``` pointers.  See the json_example.f90 file for more examples.
 ```fortran
     program example2
 
-        use,intrinsic :: iso_fortran_env, only: wp => real64 
+        use,intrinsic :: iso_fortran_env, only: wp => real64
 
         use json_module
 
@@ -211,12 +212,15 @@ The code above produces the file:
 Documentation
 --------------
 
-The API documentation for the latest release version can be found [here](http://jacobwilliams.github.io/json-fortran).  The documentation can also be generated by processing the source files with [RoboDoc](http://rfsber.home.xs4all.nl/Robo/).  Note that both the shell script, CMake, and SCons will also generate these files automatically in the documentation folder, assuming you have RoboDoc installed. 
+The API documentation for the latest release version can be found [here](http://jacobwilliams.github.io/json-fortran).  The documentation can also be generated by processing the source files with [RoboDoc](http://rfsber.home.xs4all.nl/Robo/).  Note that both the shell script, CMake, and SCons will also generate these files automatically in the documentation folder, assuming you have RoboDoc installed.
+
+Contributing [![Ready in backlog](https://badge.waffle.io/jacobwilliams/json-fortran.png?label=Ready&title=Ready)](CONTRIBUTING.md)
+------------
+Want to help?  Take a quick look at our [contributing guidelines](CONTRIBUTING.md) then claim something in [the "ready" column on our Waffle.io](https://waffle.io/jacobwilliams/json-fortran) and [Fork. Commit. Pull request.](https://help.github.com/articles/fork-a-repo).
 
 License
 --------
-
-The json-fortran sourcecode and related files and documentation are distributed under a permissive free software license (BSD-style).  See the [LICENSE](https://raw.githubusercontent.com/jacobwilliams/json-fortran/master/LICENSE) file for more details.
+The json-fortran source code and related files and documentation are distributed under a permissive free software license (BSD-style).  See the [LICENSE](https://raw.githubusercontent.com/jacobwilliams/json-fortran/master/LICENSE) file for more details.
 
 Miscellaneous
 ---------------