Merge pull request #93 from rapidpro/release-process

Release process

conf/salt/project/venv.sls

@@ -5,6 +5,11 @@ include:
   - project.repo
   - python
 
+deadsnakes-python2.7:
+  pkgrepo.managed:
+    - humanname: Deadsnakes PPA fro Python 2.7
+    - ppa: fkrull/deadsnakes-python2.7
+
 python-pkgs:
   pkg:
     - installed
@@ -13,6 +18,7 @@ python-pkgs:
       - python{{ pillar['python_version'] }}-dev
     - require:
       - pkgrepo: deadsnakes
+      - pkgrepo: deadsnakes-python2.7
 
 venv:
   virtualenv.managed:

docs/source/conf.py

@@ -49,10 +49,10 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# The short X.Y version.
-version = '0.1'
 # The full version, including alpha/beta/rc tags.
-release = '0.1.1'
+release = __import__('tracpro').__version__
+# The short X.Y version.
+version = '.'.join(release.split('.')[:2])
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/index.rst

@@ -26,9 +26,15 @@ TracPro was built for UNICEF by `Nyaruka <http://nyaruka.com/>`_ and is currentl
 
 .. toctree::
    :maxdepth: 2
-   :caption: Server/Deployment
+   :caption: Releases
+
+   releases/changelog.rst
+   releases/deployment-process.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Servers and Provisioning
 
-   servers/deployment-process.rst
    servers/fabric.rst
    servers/provisioning.rst
    servers/server-setup.rst

docs/source/releases/changelog.rst

@@ -0,0 +1,18 @@
+Changelog
+=========
+
+Tracpro's version is incremented upon each merge to master according to our
+:ref:`production deployment process <release-to-production>`.
+
+We recommend reviewing the release notes and code diffs before upgrading
+between versions.
+
+v1.0.0 (unreleased)
+-------------------
+
+Code diff: https://github.com/rapidpro/tracpro/compare/v0.0.50...develop
+
+* First Caktus release.
+
+
+.. _semantic versioning: http://semver.org/

docs/source/releases/deployment-process.rst

@@ -0,0 +1,114 @@
+Deployment Process
+==================
+
+Release to staging
+------------------
+
+#. Ensure that your work has been pushed to GitHub.
+
+#. On your local machine, check out the branch that you wish to deploy.
+
+#. By default, the ``develop`` branch is deployed to staging (regardless of
+   which branch you've checked out locally). If you wish to
+   deploy a different branch, you will need to edit your local copy of
+   `conf/pillar/staging.sls
+   <https://github.com/rapidpro/tracpro/blob/develop/conf/pillar/staging.sls>`_
+   to use a different branch name.
+
+#. Run the deploy::
+
+    fab staging deploy
+
+
+.. _reset-staging-environment:
+
+Reset staging environment
+-------------------------
+
+These steps will restore the production database and code states to the
+staging environment.
+
+#. Copy the production database to staging::
+
+    fab prod_db_to_staging
+
+#. On your local machine, check out the master branch::
+
+    git checkout master
+
+#. Edit your local copy of `conf/pillar/staging.sls
+   <https://github.com/rapidpro/tracpro/blob/develop/conf/pillar/staging.sls>`_
+   to specify the ``master`` branch for deployment.
+
+#. Deploy the ``master`` branch to staging::
+
+    fab staging deploy
+
+#. Undo the change to `conf/pillar/staging.sls
+   <https://github.com/rapidpro/tracpro/blob/develop/conf/pillar/staging.sls>`_.
+
+
+.. _release-to-production:
+
+Release to production
+---------------------
+
+#. **Before** merging changes to ``master``, the complete deployment process
+   should be tested on staging.
+
+   * :ref:`Restore <reset-staging-environment>` production data, media, and code
+     to the staging machine.
+
+   * Check out the ``develop`` branch locally and deploy it to staging::
+
+       fab staging deploy
+
+     **NOTE:** If you are deploying a hotfix branch, you will need to edit
+     your local copy of `conf/pillar/staging.sls
+     <https://github.com/rapidpro/tracpro/blob/develop/conf/pillar/staging.sls>`_
+     accordingly.
+
+   * Confirm that changes are behaving as expected, and troubleshoot the
+     deploy process until you are confident.
+
+#. Finalize the release number.
+
+   * Update the version number according to `semantic versioning`_, and change
+     the version state to ``"final"``.
+
+       * The micro version is incremented with backwards-compatible bugfixes.
+
+       * The minor version is incremented with backwards-compatible features.
+
+       * The major version is incremented with incompatible changes.
+
+   * Update the :doc:`release notes <changelog>` (including notes about
+     one-off deployment requirements, if needed) and add the current date as
+     the release date.
+
+   * Commit these changes and push to GitHub.
+
+#. Merge all changes to the ``master`` branch, ensure that these changes
+   are pushed to GitHub, and confirm that the Travis build has passed.
+
+#. Check out the updated ``master`` branch locally, and create a release tag::
+
+    git tag -a vX.Y.Z -m "Released YYYY-MM-DD" && git push origin --tags
+
+#. Copy the release notes to the GitHub releases interface.
+
+#. Run the production deploy::
+
+    fab production deploy
+
+#. Merge the ``master`` branch into ``develop``::
+
+    git checkout develop
+    git merge origin/master
+    git push origin develop
+
+#. On the ``develop`` branch, increment the micro version and change the code
+   state to ``"dev"``. Commit these changes and push to GitHub.
+
+
+.. _semantic versioning: http://semver.org/

docs/source/servers/fabric.rst

@@ -26,14 +26,13 @@ branch has migrations that have not yet been run on the remote server.
 Copying production data to staging
 ----------------------------------
 
-To copy the production database and media files to staging::
+To copy the production database to staging::
 
-    fab prod_to_staging
+    fab prod_db_to_staging
 
-**NOTES:** Media files will be synced through the local development
-environment first. Additionally, migrations must run
-(``fab staging manage_run:"migrate"``) if the branch that is deployed on
-staging has new migrations that have not been run on production.
+**NOTES:** Migrations must run (``fab staging manage_run:"migrate"``) if the
+branch that is deployed on staging has new migrations that have not been run
+on production.
 
 Running commands on the server
 ------------------------------
@@ -44,4 +43,4 @@ To run a management command on a remote server::
 
 Use the ``manage_shell`` alias to run a Python shell on a remote server::
 
-    fab [production|staging] manage_shell
+    fab [production|staging] manage_shell