Skip to content
Snippets Groups Projects
Commit fa7eb343 authored by Vermaat's avatar Vermaat
Browse files

Merge pull request #19 from LUMC/contributing-docs 

Update documentation on contributing and releases
parents cc307ea0 e6fdf044
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
README.rst
+ 12
− 2
View file @ fa7eb343
...@@ -13,8 +13,18 @@ User documentation can be found on the `wiki ...@@ -13,8 +13,18 @@ User documentation can be found on the `wiki
submit bug reports and feature requests. submit bug reports and feature requests.
Developer documentation is `hosted at Read The Docs Developer documentation is `hosted at Read The Docs
<http://mutalyzer.readthedocs.org>`_. Contributions to Mutalyzer are welcome <http://mutalyzer.readthedocs.org>`_.
as `GitHub pull requests <https://github.com/LUMC/mutalyzer/pulls>`_.
Contributing
------------
Contributions to Mutalyzer are very welcome! They can be feature requests, bug
reports, bug fixes, unit tests, documentation updates, or anything els you may
come up with.
Please refer to the documentation for `more information on contributions
<http://mutalyzer.readthedocs.org/en/latest/contributing.html>`_.
Copyright Copyright
......
doc/development.rst → doc/contributing.rst
+ 74
− 0
View file @ fa7eb343
.. highlight:: none .. highlight:: none
.. _development: .. _contributing:
Development
===========
Development of Mutalyzer happens on GitHub:
https://github.com/LUMC/mutalyzer
Contributing Contributing
------------ ============
Contributions to Mutalyzer are very welcome! They can be feature requests, bug Contributions to Mutalyzer are very welcome! They can be feature requests, bug
reports, bug fixes, unit tests, documentation updates, or anything els you may reports, bug fixes, unit tests, documentation updates, or anything els you may
come up with. come up with.
Development of Mutalyzer happens on GitHub:
https://github.com/LUMC/mutalyzer
Coding style Coding style
------------ ------------
...@@ -38,18 +34,11 @@ use:: ...@@ -38,18 +34,11 @@ use::
python setup.py develop python setup.py develop
Unit tests Creating a pull request
---------- -----------------------
We use `pytest`_ for the unit tests. To run them, just type ``py.test`` from Contributions are most welcome as GitHub pull requests. If you're familiar
the Mutalyzer source directory. with the typical GitHub pull request workflow, you can skip this section.
.. note:: The Mutalyzer package must be installed before running the unit
tests.
Working with feature branches
-----------------------------
New features are best implemented in their own branches, isolating the work New features are best implemented in their own branches, isolating the work
from unrelated developments. In fact, it's good practice to *never work from unrelated developments. In fact, it's good practice to *never work
...@@ -57,10 +46,11 @@ directly on the master branch* but always in a separate branch. When your work ...@@ -57,10 +46,11 @@ directly on the master branch* but always in a separate branch. When your work
is ready, a feature branch can be merged back into master via a *pull request* is ready, a feature branch can be merged back into master via a *pull request*
in GitHub. in GitHub.
We assume you forked the Mutalyzer repository to your own namespace in GitHub Before starting your work, fork the Mutalyzer repository to your own namespace
and are working from this fork. Before starting work on your feature, create a in GitHub and work from this fork. Before starting work on your feature,
branch for it:: create a branch for it::
git clone https://github.com/<you>/mutalyzer.git && cd mutalyzer
git checkout -b your-feature git checkout -b your-feature
Commit changes on this branch. If you're happy with it, push to GitHub:: Commit changes on this branch. If you're happy with it, push to GitHub::
...@@ -74,81 +64,11 @@ in the pull request by pushing your branch again:: ...@@ -74,81 +64,11 @@ in the pull request by pushing your branch again::
git commit git commit
git push git push
You may also be asked to rebase your branch on the master branch if it has
changed since you started your work. This will require a forced push::
git fetch
git rebase origin/master
git push -f
If the work is done, a maintainer can merge your branch and close the pull If the work is done, a maintainer can merge your branch and close the pull
request. After the branch was merged you can safely delete it:: request. After the branch was merged you can safely delete it::
git branch -d your-feature git branch -d your-feature
Versioning
----------
A normal version number takes the form X.Y.Z where X is the major version, Y
is the minor version, and Z is the patch version. Development versions take
the form X.Y.Z.dev where X.Y.Z is the closest future release version.
Note that this scheme is not 100% compatible with `SemVer`_ which would
require X.Y.Z-dev instead of X.Y.Z.dev but `compatibility with setuptools
<http://peak.telecommunity.com/DevCenter/setuptools#specifying-your-project-s-version>`_
is more important for us. Other than that, version semantics are as described
by SemVer.
Releases are available from the GitHub git repository as tags. Additionally,
the latest release is available from the `release` branch.
.. note:: Older Mutalyzer version numbers took the form 2.0.beta-X where X was
incremented on release.
Release procedure
^^^^^^^^^^^^^^^^^
Releasing a new version is done as follows:
1. Make sure the section in the ``CHANGES`` file for this release is
complete and there are no uncommitted changes.
.. note::
Commits since release X.Y.Z can be listed with ``git log vX.Y.Z..`` for
quick inspection.
2. Update the ``CHANGES`` file to state the current date for this release
and edit ``mutalyzer/__init__.py`` by updating `__date__` and removing the
``dev`` value from `__version_info__`.
Commit and tag the version update::
git commit -am 'Bump version to X.Y.Z'
git tag -a 'vX.Y.Z'
3. Push to the GitHub repository (assuming the remote name is `github` and you
are working on the `master` branch::
git push github master
git push github master:release --tags
4. Add a new entry at the top of the ``CHANGES`` file like this::
Version X.Y.Z+1
---------------
Release date to be decided.
Increment the patch version and add a ``dev`` value to `__version_info__`
in ``mutalyzer/__init__.py`` and commit these changes::
git commit -am 'Open development for X.Y.Z+1'
.. _pytest: http://pytest.org/
.. _PEP 8: http://www.python.org/dev/peps/pep-0008/ .. _PEP 8: http://www.python.org/dev/peps/pep-0008/
.. _PEP 257: http://www.python.org/dev/peps/pep-0257/ .. _PEP 257: http://www.python.org/dev/peps/pep-0257/
.. _SemVer: http://semver.org/
doc/index.rst
+ 17
− 5
View file @ fa7eb343
...@@ -25,15 +25,31 @@ Information for getting Mutalyzer running on a system. ...@@ -25,15 +25,31 @@ Information for getting Mutalyzer running on a system.
deploy deploy
Development
-----------
General information for Mutalyzer developers.
.. toctree::
:maxdepth: 2
issues
contributing
testing
release
Technical reference Technical reference
------------------- -------------------
Application design and complete API reference. Application design notes and API reference.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
design design
strings
new-organism
api api
...@@ -43,10 +59,6 @@ Additional notes ...@@ -43,10 +59,6 @@ Additional notes
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
development
issues
new-organism
strings
changelog changelog
copyright copyright
......
doc/release.rst 0 → 100644
+ 84
− 0
View file @ fa7eb343
.. highlight:: none
.. _releases:
Releases
========
Versioning
----------
A normal version number takes the form X.Y.Z where X is the major version, Y
is the minor version, and Z is the patch version. Development versions take
the form X.Y.Z.dev where X.Y.Z is the closest future release version.
Note that this scheme is not 100% compatible with `SemVer`_ which would
require X.Y.Z-dev instead of X.Y.Z.dev but `compatibility with setuptools
<http://peak.telecommunity.com/DevCenter/setuptools#specifying-your-project-s-version>`_
is more important for us. Other than that, version semantics are as described
by SemVer.
Releases are available from the GitHub git repository as tags. Additionally,
the latest release is available from the `release` branch.
.. note:: Older Mutalyzer version numbers took the form 2.0.beta-X where X was
incremented on release.
Release procedure
-----------------
Releasing a new version is done as follows. This assumes remote `origin` is
the upstream Mutalyzer repository and you have push rights there.
1. Start a release branch and make sure the section in the ``CHANGES.rst``
file for this release is complete::
git checkout -b release-X.Y.Z
git add CHANGES.rst
git commit -m 'Update changelog'
.. note::
Commits since release X.Y.Z can be listed with ``git log vX.Y.Z..`` for
quick inspection.
2. Update the ``CHANGES.rst`` file to state the current date for this release
and edit ``mutalyzer/__init__.py`` by updating `__date__` and removing the
``dev`` value from `__version_info__`.
Commit and tag the version update::
git commit -am 'Bump version to X.Y.Z'
git tag -a 'vX.Y.Z' release-X.Y.Z^
3. Add a new entry at the top of the ``CHANGES.rst`` file like this::
Version X.Y.Z+1
---------------
Release date to be decided.
Increment the patch version and add a ``dev`` value to `__version_info__`
in ``mutalyzer/__init__.py`` and commit these changes::
git commit -am 'Open development for X.Y.Z+1'
4. Push these commits to GitHub::
git push origin release-X.Y.Z -u
And submit a pull request for this branch.
5. If everything looks ok and the pull request has been accepted you can push
the tag and update the `release` branch. Beware to re-tag if the pull
request was updated meanwhile. The working branch can be deleted.
::
git push origin vX.Y.Z:release --tags
git branch -d release-X.Y.Z
.. _SemVer: http://semver.org/
doc/testing.rst 0 → 100644
+ 19
− 0
View file @ fa7eb343
.. highlight:: none
.. _testing:
Testing
=======
We use `pytest`_ for the unit tests. To run them, just type ``py.test`` from
the Mutalyzer source directory.
.. note:: The Mutalyzer package must be installed before running the unit
tests.
Tests are `run automatically on Travis CI
<https://travis-ci.org/LUMC/mutalyzer>`_ for each pull request and push on
GitHub.
.. _pytest: http://pytest.org/
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment