Merge pull request #161 from bird-house/changes

add changes history to repo and tool to update new releases

###  Changes

- Add `bump2version` configuration to allow self-update of files that refer to new version releases 
and apply update of features listed in this changelog.
- Add `CHANGES.md` file with all previous version details extracted for PR merge commit messages.
- Add listing of change history to generated documentation on
[bird-house/birdhouse-deploy ReadTheDocs](https://birdhouse-deploy.readthedocs.io/en/latest/).
- Update `CONTRIBUTING.rst` file to include note about updating the new changelog for future PR.

### Fixes

- Fixes #157

### Notes

- daccs-iac test `esgf-dap` is failing, but unrelated reason to these changes (affects docs only, which are properly updated on ReadTheDocs)
  (see test results: http://daccs-jenkins.crim.ca/job/PAVICS-e2e-workflow-tests/job/master/483/console)

.bumpversion.cfg

@@ -0,0 +1,22 @@
+[bumpversion]
+current_version = 1.13.10
+commit = True
+tag = False
+tag_name = {new_version}
+
+[bumpversion:file:CHANGES.md]
+search =
+	[Unreleased](https://github.com/bird-house/birdhouse-deploy/tree/master) (latest)
+	------------------------------------------------------------------------------------------------------------------
+replace =
+	[Unreleased](https://github.com/bird-house/birdhouse-deploy/tree/master) (latest)
+	------------------------------------------------------------------------------------------------------------------
+
+	[//]: # (list changes here, using '-' for each new entry, remove this when items are added)
+
+	[{new_version}](https://github.com/bird-house/birdhouse-deploy/tree/{new_version}) ({now:%Y-%m-%d})
+	------------------------------------------------------------------------------------------------------------------
+
+[bumpversion:file:README.rst]
+search = {current_version}
+replace = {new_version}

.readthedocs.yml

@@ -22,6 +22,8 @@ formats: all
 # Optionally set the version of Python and requirements required to build your docs
 python:
   version: 3.6
+  install:
+    - requirements: docs/requirements.txt
 
 #conda:
 #  environment: environment-docs.yml

CONTRIBUTING.rst

@@ -23,35 +23,64 @@ Policy objectives
 Policy rules
 ~~~~~~~~~~~~~~~~~~~~~
 
-1. The repository has a main branch, "`master`_", open to the community where contributions, "PR", are welcome. This master branch must not have owners and therefore no organization can block contributions to it.
+1. The repository has a main branch, "`master`_", open to the community where contributions, "PR", are welcome.
+   This master branch must not have owners and therefore no organization can block contributions to it.
 
 .. _master: https://github.com/bird-house/birdhouse-deploy
 
-2. Contributions should be backward-compatible whenever possible, or feature a toggle switch so that organizations can activate the new feature on their own schedule. See `extra core components`_ and `optional components`_ for examples.
+2. Contributions should be backward-compatible whenever possible, or feature a toggle switch so that organizations
+   can activate the new feature on their own schedule. See `extra core components`_ and `optional components`_ for
+   examples.
 
 .. _extra core components: https://github.com/bird-house/birdhouse-deploy/blob/master/birdhouse/components/README.rst
 .. _optional components: https://github.com/bird-house/birdhouse-deploy/blob/master/birdhouse/optional-components/README.rst
 
 3. Contributions will trigger a test suite that must successfully pass before being merged (or integrated).
-4. Contributions must be reviewed by every willing organizations (Default reviewers are `@tlvu`_ for `Ouranos`_ and `@MatProv`_ for `CRIM`_).
+
+4. Contributions must be reviewed by every willing organizations
+   (Default reviewers are `@tlvu`_ for `Ouranos`_ and `@MatProv`_ for `CRIM`_).
 
 .. _@tlvu: https://github.com/tlvu
 .. _Ouranos: https://github.com/Ouranosinc
 .. _@MatProv: https://github.com/MatProv
 .. _CRIM: https://github.com/crim-ca
 
 5. The reviews must be rigorous while respecting the initial scope.
-6. Each organization wishing to review the changes has the duty to do so within a reasonable period of time (7 days) or to indicate its intention to do so later with reasonable reasons (e.g., vacation). After this time, its implicit support will be considered. It will be assumed that the organization agrees to the changes, and they will get merged without further notice.
-7. To encourage review in a timely manner, contributions should be simple and focused (do not mix multiple goals) and well explained (describe the "why" and the "impact/behavior change" on existing production deployment, as requested in the contribution template).
-8. Each organization maintains a fork for its production allowing it to deploy the platform at its own pace. It also allows to self-manage the production fork contribution permissions and develop feature branches.
-9. Each organization is responsible for keeping its production fork up to date with the main branch to avoid discrepancies.
-10. If patches or contributions are made directly in the production fork, they must also be ported back and approved in the main branch (no code that does not exist in the main branch should exist in a production fork).
-11. The main branch will contain the official versions of PAVICS that will evolve according to semantic versioning. These versions should be used by the organizations.
-12. If contributions are made directly in a production fork (point 10), a tagged version should use the last common one with the main branch but also include a suffix.
-    * Example: The main branch is at `2.1.8`, and a contribution is made in a production fork from `2.1.8`. The tag `2.1.9` cannot be applied because this version could possibly exists in the main branch. A tag looking like `2.1.8.orgXrev1` would be preferred.
+
+6. Each organization wishing to review the changes has the duty to do so within a reasonable period of time (7 days)
+   or to indicate its intention to do so later with reasonable reasons (e.g., vacation). After this time, its implicit
+   support will be considered. It will be assumed that the organization agrees to the changes, and they will get merged
+   without further notice.
+
+7. To encourage review in a timely manner, contributions should be simple and focused (do not mix multiple goals) and
+   well explained (describe the "why" and the "impact/behavior change" on existing production deployment, as requested
+   in the contribution template).
+   They should also include a description of provided modifications and fixes under the active ``Unreleased`` section
+   of the `CHANGES.md`_ history file for traceability.
+
+.. _CHANGES.md: https://github.com/bird-house/birdhouse-deploy/blob/master/CHANGES.md
+
+8. Each organization maintains a fork for its production allowing it to deploy the platform at its own pace.
+   It also allows to self-manage the production fork contribution permissions and develop feature branches.
+
+9. Each organization is responsible for keeping its production fork up to date with the main branch to avoid
+   discrepancies.
+
+10. If patches or contributions are made directly in the production fork, they must also be ported back and approved in
+    the main branch (no code that does not exist in the main branch should exist in a production fork).
+
+11. The main branch will contain the official versions of PAVICS that will evolve according to semantic versioning.
+    These versions should be used by the organizations.
+
+12. If contributions are made directly in a production fork (point 10), a tagged version should use the last common one
+    with the main branch but also include a suffix.
+
+    * Example: The main branch is at ``2.1.8``, and a contribution is made in a production fork from ``2.1.8``.
+      The tag ``2.1.9`` cannot be applied because this version could possibly exists in the main branch.
+      A tag looking like ``2.1.8.orgXrev1`` would be preferred.
 
 PAVICS multi organization git repository management
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. image:: https://raw.githubusercontent.com/bird-house/birdhouse-deploy/master/docs/source/images/multi_organizations_management.jpg
-  :alt: PAVICS multi organization git repository management
+  :alt: PAVICS multi organization git repository management

README.rst

@@ -4,10 +4,30 @@ birdhouse-deploy
 Scripts and configurations to deploy the various birds and servers required
 for a full-fledged production platform.
 
-..
-    .. image:: https://readthedocs.org/projects/birdhouse-deploy/badge/?version=latest
-        :target: https://birdhouse-deploy.readthedocs.io/en/latest/?badge=latest
-        :alt: Documentation Status
+.. start-badges
+
+.. list-table::
+    :stub-columns: 1
+
+    * - statuses
+      - | |readthedocs|
+    * - releases
+      - | |latest-version| |commits-since|
+
+.. |commits-since| image:: https://img.shields.io/github/commits-since/bird-house/birdhouse-deploy/1.13.10.svg
+    :alt: Commits since latest release
+    :target: https://github.com/bird-house/birdhouse-deploy/compare/1.13.10...master
+
+.. |latest-version| image:: https://img.shields.io/badge/tag-1.13.10-blue.svg?style=flat
+    :alt: Latest Tag
+    :target: https://github.com/bird-house/birdhouse-deploy/tree/1.13.10
+
+.. |readthedocs| image:: https://readthedocs.org/projects/birdhouse-deploy/badge/?version=latest
+    :alt: ReadTheDocs Build Status (latest version)
+    :target: https://birdhouse-deploy.readthedocs.io/en/latest/?badge=latest
+
+.. end-badges
+
 
 PAVICS
 ------

birdhouse/README.rst

@@ -245,5 +245,34 @@ Given a version number MAJOR.MINOR.PATCH, increment the:
    component.
 
 
+To help properly update versions in all files that could reference to the latest tag,
+the `bump2version <https://github.com/c4urself/bump2version>`_ utility is employed.
+Running this tool will modify versions in files referencing to the latest revision
+(as defined in `.bumpversion.cfg`_) and apply change logs
+updates by moving ``Unreleased`` items under a new version matching the new version.
+
+One of the following commands should be used to generate a new version.
+The local `.bumpversion.cfg`_ file should be detected automatically when
+calling the command from the root of the repository (otherwise, pass the path with ``--config-file``).
+
+.. code-block:: shell
+
+    # bump to a specific semantic version
+    bump2version --new-version "<MAJOR>.<MINOR>.<PATCH>" patch
+
+    # bump to a one increment above the corresponding part (eg: minor for 1.0.1 -> 1.1.0)
+    bump2version [major|minor|patch]
+
+    # test result without applying it
+    bump2version --verbose --dry-run <other options>
+
+
+Once the version as been bumped and the PR is merged, a corresponding version tag should be added
+to the commit generated by the merge. This step is intentionally manual instead of leaving it up
+to ``bump2version`` to auto-generated the tag in other to apply it directly on ``master`` branch
+after the merge, instead of onto the commits in the PR prior merging.
+
+
 .. _nginx.conf: ./config/proxy/nginx.conf
 .. _default.env: ./default.env
+.. _`.bumpversion.cfg`: ../.bumpversion.cfg

docs/requirements.txt

@@ -0,0 +1,2 @@
+# extra requirements specifically for documentation purposes
+m2r2

docs/source/changes.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../../CHANGES.md

docs/source/conf.py

@@ -41,6 +41,7 @@
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
+    'm2r2',  # add mdinclude
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/index.rst

@@ -6,7 +6,7 @@
 Introduction
 ============
 
-PAVICS is a research platform dedicated to climate analysis and visualization. It bundles 
+PAVICS is a research platform dedicated to climate analysis and visualization. It bundles
 data search, analytics and visualization services.
 
 .. include:: ../../README.rst
@@ -23,6 +23,7 @@ Contents:
    birdhouse/optional-components/README
    data_catalog
    contributing
+   changes
 
 
 Indices and tables