doc: update readme

README.md

@@ -1,12 +1,29 @@
-# The RAVEN Toolbox
-The RAVEN (Reconstruction, Analysis and Visualization of Metabolic Networks) Toolbox is a software suite for Matlab that allows for semi-automated reconstruction of genome-scale models (GEMs). It makes use of published models and/or KEGG, MetaCyc databases, coupled with extensive gap-filling and quality control features. The software suite also contains methods for visualizing simulation results and omics data, as well as a range of methods for performing simulations and analyzing the results. The software is a useful tool for system-wide data analysis in a metabolic context and for streamlined reconstruction of metabolic networks based on protein homology.
+# ![The RAVEN Toolbox 2](RAVEN2.png)
+The RAVEN (Reconstruction, Analysis and Visualization of Metabolic Networks) Toolbox 2 is a software suite for Matlab that allows for semi-automated reconstruction of genome-scale models (GEMs). It makes use of published models and/or KEGG, MetaCyc databases, coupled with extensive gap-filling and quality control features. The software suite also contains methods for visualizing simulation results and omics data, as well as a range of methods for performing simulations and analyzing the results. The software is a useful tool for system-wide data analysis in a metabolic context and for streamlined reconstruction of metabolic networks based on protein homology.
 
 If you are using RAVEN in any scientific work, please cite: [R. Agren, et. al, “The RAVEN Toolbox and Its Use for Generating a Genome-scale Metabolic Model for Penicillium chrysogenum,” PLoS Comput. Biol., vol. 9, no. 3, p. e1002980, Mar. 2013.](http://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1002980).
 
-> A manuscript describing RAVEN Toolbox 2.0 is currently being prepared. Citation details will therefore be updated in the near future.
+> A manuscript describing RAVEN Toolbox 2 is currently being prepared. Citation details will therefore be updated in the near future.
 
 Please report any technical issues and bugs [here](https://github.com/SysBioChalmers/RAVEN/issues). For other issues, please contact [Eduard Kerkhoven](https://github.com/edkerk).
 
+-----
+## Overview
+
+[Releases](#releases)
+
+[Installation](#installation)
+
+[Tutorials](#tutorials)
+
+[Hidden Markov Models (HMMs) for KEGG reconstruction](#hidden-markov-models-for-kegg-based-reconstruction)
+
+[Development](#development-guidelines)
+
+[Links](#links)
+
+-----
+
 ## Releases
 RAVEN can be installed via cloning the GitHub repository as per below or by downloading and extracting one of the a zipped [release](https://github.com/SysBioChalmers/RAVEN/releases). Please note that the releases do not always represent the most up to date version.
 
@@ -19,7 +36,7 @@ RAVEN can be installed via cloning the GitHub repository as per below or by down
 * At least one solver for linear programming:
   * Preferred: [Gurobi Optimizer](http://www.gurobi.com/downloads/gurobi-optimizer) (version 7.5 or higher), academic license is available [here](https://user.gurobi.com/download/licenses/free-academic).
   * Alternative/legacy: [MOSEK](https://www.mosek.com/downloads/details/5/) (version 7 only), academic license is available [here](https://www.mosek.com/products/academic-licenses/).
-  * If the user has [COBRA Toolbox](https://github.com/opencobra/cobratoolbox) installed, it is possible to use the default COBRA solver (the one which is set by _changeCobraSolver_).
+  * If the user has [COBRA Toolbox](https://github.com/opencobra/cobratoolbox) installed, it is possible to use the default COBRA solver (the one which is set by [_changeCobraSolver_](#cobra-toolbox).
 
 
 ### Instructions
@@ -31,7 +48,7 @@ git clone [email protected]:SysBioChalmers/RAVEN.git
 ```
 * Alternatively, download the latest [release](https://github.com/SysBioChalmers/RAVEN/releases) of RAVEN Toolbox as a ZIP file, and extracted to your favourite directory.
 
-Once extracted, ensure that all other software dependencies (e.g. libSBML, Gurobi) are installed (see above for [list](#dependencies), below for [instructions](#libSBML). Then, open MATLAB and run the following command:
+Once extracted, ensure that all other software dependencies (e.g. libSBML, Gurobi) are installed (see above for [list](#dependencies), below for [instructions](#libsbml). Then, open MATLAB and run the following command:
 ```matlab
 cd('[location]/RAVEN/installation'))
 checkInstallation
@@ -71,7 +88,7 @@ savepath
 
 #### Mosek
 1. Download from the link [above](#dependencies) and install Mosek to your favourite location.
-2. Make sure you obtained a [license](https://www.mosek.com/products/academic-licenses/) following [instructions] (https://docs.mosek.com/8.0/install/installation.html#setting-up-the-license).
+2. Make sure you obtained a [license](https://www.mosek.com/products/academic-licenses/) following [instructions](https://docs.mosek.com/8.0/install/installation.html#setting-up-the-license).
 3. To install Mosek in MATLAB, follow [instructions](https://docs.mosek.com/8.0/toolbox/installation.html#id1). Note: the documentation mentions version 8, but RAVEN only works with version 7 of Mosek.
 4.  Make sure that MATLAB remembers the Mosek installation for next time, by running the following command: 
 
@@ -91,8 +108,11 @@ setRavenSolver('cobra')
 ## Tutorials
 Some tutorials highlighting basic RAVEN functionality can be found in the 'tutorial' folder in the installation directory.
 
-## Pre-trained Hidden Markov Models (HMMs) for KEGG Orthology (KO) protein sets
-_For RAVEN 2.0_
+## Hidden Markov Models for KEGG based reconstruction
+
+Provided are pre-trained Hidden Markov Models (HMMs) for KEGG Orthology (KO) protein sets:
+
+##### For RAVEN 2.0 and later
 
 For _de novo_ reconstruction of a GEM, the RAVEN function _getKEGGModelForOrganism_ can use HMMs trained on KO protein sets. Provided are HMMs trained on KEGG Release 82.0. CD-HIT was used to obtain non-redundant representative KO protein sets thereby clustering proteins with the defined identity and overlap with the longest protein in the corresponding cluster threshold values. Multisequence alignment with MAFFT and training with HMMER 3.1b2 were then performed. The provided archives contain only pre-trained HMMs.
 
@@ -107,7 +127,7 @@ HMM sets can be downloaded **automatically** during GEM reconstruction from KEGG
 |[prok90_kegg82](http://biomet-toolbox.org/tools/downloadable/files/euk100_kegg82.zip)|82.0|prokaryota|90|90
 |[prok50_kegg82](http://biomet-toolbox.org/tools/downloadable/files/euk100_kegg82.zip)|82.0|prokaryota|50|90
 
-_For RAVEN 1.9.0 or older_
+##### For RAVEN 1.9.0 or older
 
 HMMs were trained from KO protein sets, based on KEGG Release 58.1. Multisequence alignment was performed with ClustalW2, whereas HMMs were trained with HMMER 2.3. All the associated proteins were used in multisequence alignment and HMMs training. In addition to pre-trained HMMs, the archives also contain multisequence alignment data. The following HMM sets are available:
 
@@ -116,6 +136,47 @@ HMMs were trained from KO protein sets, based on KEGG Release 58.1. Multisequenc
 |[eukaryota](http://biomet-toolbox.org/tools/downloadable/files/euk100_kegg82.zip)|58.1|eukaryota
 |[prokaryota](http://biomet-toolbox.org/tools/downloadable/files/euk100_kegg82.zip)|58.1|eukaryota
 
+## Development guidelines
+
+Anybody is welcome to contribute to the development of RAVEN Toolbox, but please abide by the following guidelines.
+
+When making _any_ changes to an existing function (`*.m`-file, change the name and date near the bottom of the commented section that is included the beginning of each function. In this section, please specify what each parameter is doing, and what are default settings. Have a look at existing functions to see what style is used.
+
+### Urgent bugfix
+* When fixing a bug in an existing function, make a separate branch from `master` and name the branch after the function you are fixing.
+* Make commits to this branch while working on your bugfix. Note that bugfixes have to be backwards compatible.
+* When you are certain that your bugfix works, make a pull request to the `master` branch. Also, see [Pull request](#pull-request) below.
+
+### New features/functions
+* For other development (not bugfixes, but for instance introducing new functions or new/updated features for existing functions): make a separate branch from `devel` and name the branch for instance after the function/feature you are fixing/developing.
+* Make commits to this branch while developing. Aim for backwards compatibility, and try to avoid very new MATLAB functions when possible, to accommodate users with older MATLAB versions.
+* When you are happy with your new function/feature, make a pull request to the `devel` branch. Also, see [Pull request](#pull-request) below.
+
+### Semantic commits
+Use semantic commit messages to make it easier to show what you are aiming to do:
+* `chore`: updating binaries, KEGG or MetaCyc database files, etc.
+* `doc`: updating documentation (in `doc` folder) or explanatory comments in functions.
+* `feat`: new feature added, e.g. new function introduced / new parameters / new algorithm / etc.
+* `fix`: bugfix.
+* `refactor`: see [code refactoring](https://en.wikipedia.org/wiki/Code_refactoring).
+* `style`: minor format changes of functions (spaces, semi-colons, etc., no code change).
+
+Examples:
+```
+feat: exportModel additional export to YAML
+chore: update KEGG model to version 83.0
+fix: optimizeProb parsing results from Gurobi
+```
+More detailed explanation or comments can be left in the commit description.
+
+### Pull request
+* No changes should be directly commited to the `master` or `devel` branches. Pull requests should be used.
+* The person making the pull request and the one accepting the merge _cannot_ be the same person.
+* Typically, wait ~ 1 week before merging, to allow for other developers to inspect the pull request.
+* A merge with the master branch typically invokes a new release (see [versioning](#versioning)).
+
+### Versioning
+RAVEN Toolbox follows [semantic versioning](https://semver.org/), and a `version.txt` file is updated with each release of the master branch.
 
 ## Links
 For more systems biology related software and recently published genome-scale models from the Systems and Synthetic Biology group at Chalmers University of Technology, please visit the [Github page](https://github.com/SysBioChalmers). For more information and publications by the Systems and Synthetic Biology please visit [SysBio](www.sysbio.se).