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

Update documentation on contributing and releases

parent cc307ea0
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 @ e6fdf044
......@@ -13,8 +13,18 @@ User documentation can be found on the `wiki
submit bug reports and feature requests.
Developer documentation is `hosted at Read The Docs
<http://mutalyzer.readthedocs.org>`_. Contributions to Mutalyzer are welcome
as `GitHub pull requests <https://github.com/LUMC/mutalyzer/pulls>`_.
<http://mutalyzer.readthedocs.org>`_.
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
......
doc/development.rst → doc/contributing.rst
+ 74
− 0
View file @ e6fdf044
.. highlight:: none
.. _development:
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
reports, bug fixes, unit tests, documentation updates, or anything els you may
come up with.
Development of Mutalyzer happens on GitHub:
https://github.com/LUMC/mutalyzer
Coding style
------------
......@@ -38,18 +34,11 @@ use::
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
the Mutalyzer source directory.
.. note:: The Mutalyzer package must be installed before running the unit
tests.
Working with feature branches
-----------------------------
Contributions are most welcome as GitHub pull requests. If you're familiar
with the typical GitHub pull request workflow, you can skip this section.
New features are best implemented in their own branches, isolating the 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
is ready, a feature branch can be merged back into master via a *pull request*
in GitHub.
We assume you forked the Mutalyzer repository to your own namespace in GitHub
and are working from this fork. Before starting work on your feature, create a
branch for it::
Before starting your work, fork the Mutalyzer repository to your own namespace
in GitHub and work from this fork. Before starting work on your feature,
create a branch for it::
git clone https://github.com/<you>/mutalyzer.git && cd mutalyzer
git checkout -b your-feature
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::
git commit
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
request. After the branch was merged you can safely delete it::
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 257: http://www.python.org/dev/peps/pep-0257/
.. _SemVer: http://semver.org/
doc/index.rst
+ 17
− 5
View file @ e6fdf044
......@@ -25,15 +25,31 @@ Information for getting Mutalyzer running on a system.
deploy
Development
-----------
General information for Mutalyzer developers.
.. toctree::
:maxdepth: 2
issues
contributing
testing
release
Technical reference
-------------------
Application design and complete API reference.
Application design notes and API reference.
.. toctree::
:maxdepth: 2
design
strings
new-organism
api
......@@ -43,10 +59,6 @@ Additional notes
.. toctree::
:maxdepth: 2
development
issues
new-organism
strings
changelog
copyright
......
doc/release.rst 0 → 100644
+ 84
− 0
View file @ e6fdf044
.. 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 @ e6fdf044
.. 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