Merge pull request #315 from jgrewe/gov

Add a few words about governance to the CONTRIBUTING guideline

Author: mpsonntag

CONTRIBUTING.md

@@ -4,6 +4,14 @@ How to contribute to python-odml
 This document gives some information about how to contribute to the odML project.
 
 
+Governance model
+----------------
+
+The project has a core team of **maintainers** who are long-term contributors and responsible for coordinating the project. There is also a set of one-time or short period **contributors**. We consider everyone a contributor who reports issues, opens pull requests, or takes part in issue discussions. Any such contribution is welcome. Maintainers have commit access to the repository and will review and merge pull requests. Becoming a maintainer is possible for everyone who wants to help maintaining and shaping the project and to take over more responsibility. Requests to become a maintainer need to be approved by the existing maintainers.
+
+Any addition to the code happens via pull requests (there are only very few exceptions in which someone pushes directly to master, see below for more information). Thus, any contribution will be reviewed before it is merged. Bug fixes and other contributions to the API will undergo this pragmatic approach. Format or API changes, especially those that would lead to breaking changes, will be discussed via the issue tracker and video meetings and need to be agreed on by the maintainters. We aim at consensus decisions, but where this is not possible decisions are made by majority vote among the maintainers.
+
+
 Contributing
 ------------
 

README.rst renamed to README.md

@@ -1,40 +1,35 @@
-.. image:: https://travis-ci.org/G-Node/python-odml.svg?branch=master
-    :target: https://travis-ci.org/G-Node/python-odml
-.. image:: https://ci.appveyor.com/api/projects/status/2wfvsu7boe18kwjy?svg=true
-    :target: https://ci.appveyor.com/project/mpsonntag/python-odml
-.. image:: https://coveralls.io/repos/github/G-Node/python-odml/badge.svg?branch=master
-    :target: https://coveralls.io/github/G-Node/python-odml?branch=master
+![Travis build](https://travis-ci.org/G-Node/python-odml.svg?branch=master)
+![Appveyor](https://ci.appveyor.com/api/projects/status/2wfvsu7boe18kwjy?svg=true)
+![Test coverage](https://coveralls.io/repos/github/G-Node/python-odml/badge.svg?branch=master)
 
-odML (Open metaData Markup Language) core library
-=================================================
+# odML (Open metaData Markup Language) core library
 
 The open metadata Markup Language is a file based format (XML, JSON, YAML) for storing
 metadata in an organised human- and machine-readable way. odML is an initiative to define
 and establish an open, flexible, and easy-to-use format to transport metadata.
 
-The Python-odML library can be easily installed via :code:`pip`. The source code is freely
-available on `GitHub <https://github.com/G-Node/python-odml>`_. If you are not familiar
+The Python-odML library can be easily installed via ```pip```. The source code is freely
+available on [GitHub](https://github.com/G-Node/python-odml). If you are not familiar
 with the version control system **git**, but still want to use it, have a look at the
-documentation available on the `git-scm website <https://git-scm.com/>`_.
+documentation available on the [git-scm website](https://git-scm.com/).
 
 
-Breaking changes
-----------------
+# Breaking changes
+
 
 odML Version 1.4 introduced breaking format and API changes compared to the previous
 versions of odML. Files saved in the previous format versions can be converted to a 1.4
 compatible format using the version converter from the odml/tools package.
 
-Be aware that the value dtype :code:`binary` has been removed. Incorporating actual binary
+Be aware that the value dtype ```binary``` has been removed. Incorporating actual binary
 data into odML files is discouraged, provide references to the original files using the
-:code:`URL` dtype instead.
+```URL``` dtype instead.
 
-For details regarding the introduced changes please check the `github release notes
-<https://github.com/G-Node/python-odml/releases>`_.
+For details regarding the introduced changes please check the [github
+release notes](https://github.com/G-Node/python-odml/releases).
 
 
-Dependencies
-------------
+# Dependencies
 
 * Python 2.7 or 3.5
 * Python packages:
@@ -44,7 +39,7 @@ Dependencies
   * yaml (version 3.12)
   * rdflib (version >=4.2.2)
 
-* These packages will be downloaded and installed automatically if the :code:`pip`
+* These packages will be downloaded and installed automatically if the ```pip```
   method is used to install odML. Alternatively, they can be installed from the OS
   package manager. On Ubuntu, they are available as:
 
@@ -61,50 +56,57 @@ Dependencies
   * lib32z1-dev
 
 
-Installation
-------------
+# Installation
+
+The simplest way to install Python-odML is from PyPI using the pip tool:
 
-The simplest way to install Python-odML is from PyPI using the pip tool::
 
+```
   $ pip install odml
+```
 
-On Ubuntu, the pip package manager is available in the repositories as :code:`python-pip`.
+On Ubuntu, the pip package manager is available in the repositories as ```python-pip```.
 
 If this method is used, the appropriate Python dependencies are downloaded and installed
 automatically.
 
 
-Building from source
---------------------
+# Building from source
 
-To download the Python-odML library please either use git and clone the
-repository from GitHub::
+To download the Python-odML library please either use git and clone
+the repository from GitHub:
 
+```
   $ git clone https://github.com/G-Node/python-odml.git
+```
 
 If you don't want to use git download the ZIP file also provided on
 GitHub to your computer (e.g. as above on your home directory under a "toolbox"
 folder).
 
-To install the Python-odML library, enter the corresponding directory and run::
+To install the Python-odML library, enter the corresponding directory and run:
 
+```
   $ cd python-odml
   $ python setup.py install
+```
 
 **Note** The master branch is our current development branch, not all features might be
 working as expected. Use the release tags instead.
 
-odML Project page
------------------
+# odML Project page
 
 More information about the project including related projects as well as tutorials and
-examples can be found at our odML `project page <https://g-node.github.io/python-odml>`_.
+examples can be found at our odML [project page](https://g-node.github.io/python-odml).
+
+# Contributing and Governance
+
+See the [CONTRIBUTING](CONTIBUTING.md) document for more information on this.
 
-Bugs & Questions
-----------------
+# Bugs & Questions
 
 Should you find a behaviour that is likely a bug, please file a bug report at
-`the github bug tracker <https://github.com/G-Node/python-odml/issues>`_.
+[the github bug tracker](https://github.com/G-Node/python-odml/issues).
 
 If you have questions regarding the use of the library, feel free to join the
-`#gnode <http://webchat.freenode.net?channels=%23gnode>`_ IRC channel on freenode.
+[#gnode](http://webchat.freenode.net?channels=%23gnode) IRC channel on freenode.

setup.py

@@ -25,7 +25,7 @@
     'odml.scripts'
 ]
 
-with open('README.rst') as f:
+with open('README.md') as f:
     description_text = f.read()
 
 install_req = ["lxml", "pyyaml==3.13", "rdflib", "docopt", "pathlib"]
@@ -45,6 +45,7 @@
     install_requires=install_req,
     include_package_data=True,
     long_description=description_text,
+    long_description_content_type="text/markdown",
     classifiers=CLASSIFIERS,
     license="BSD",
     entry_points={'console_scripts': ['odmltordf=odml.scripts.odml_to_rdf:main',