<commit_before>Design
======

This section will go over some assumptions made by the Tunic library,
the general design of the library, and some things to keep in mind when
using it.

Purpose
-------

Tunic is meant to supplement your existing Fabric based deploy process,
not to replace it or the Fabric library / tool. Tunic is **not** an abstraction
layer for Fabric. It's merely meant to let you avoid writing the same thing
over and over again.

Directory structure
-------------------

Tunic doesn't care about where on your server you deploy to. However, it
expects that deployments are organized in a particular way and that each
deployment of your project is named in a particular way. The following
are **required** for Tunic functionality to work correctly.

For this example, let's assume you're deploying your project to ``/srv/www/myapp``.

* This base directory for your project should be writable as the user or group
  that deploys are being performed by.

* The directory structure under ``/srv/www/myapp`` must organized as follows. ::

    /
    +-- srv
        +-- www
            +-- myapp
                |-- releases
                |   +-- 20141105123145-0.2.0
                |   +-- 20141002231442-0.1.0
                +-- current

* The ``releases`` directory must be under your project base directory and be
  writeable by the user or group that deploys are being performed by.

* Each deploy under the ``releases`` directory must be named starting with a
  timestamp corresponding to when the deploy was done. The timestamp component
  should built with the largest period of time first (the current year), followed
  by each smaller component down to the second. The timezone used to generate this
  timestamp component doesn't matter as long as you always use the same one.

  The name for each deploy will be generated for you (in UTC) if you use the
  :func:`tunic.core.get_release_id` function. This is required to ensure that we
  can determine the time deploys were done relative to each other.

* ``current`` must be a symlink to the active deployment in the ``releases``
  directory. This symlink will be created for you automatically if you use the
  :meth:`tunic.core.ReleaseManager.set_current_release` method as part of your
  deploy process.

Dependence on Fabric
--------------------

Since Tunic is built on Fabric, it inherits the following behavior.

* Output from commands run by methods in :mod:`tunic.api` ends up being displayed
  just like output from commands run by Fabric. This can be changed through the
  use of Fabric `context managers`_.

* Since Tunic requires Fabric and Fabric doesn't support Python 3 (yet), Tunic
  won't work with Python 3 at this time.

* Since Tunic makes heavy use of Fabric and Fabric is not `thread safe`_, Tunic
  is also not thread safe.

.. _context managers: http://docs.fabfile.org/en/latest/api/core/context_managers.html
.. _thread safe: http://www.fabfile.org/faq.html#is-fabric-thread-safe


Versions
--------

Tunic uses `semantic versioning`_ of the form ``major.minor.patch``. All backwards
incompatible changes after version ``1.0.0`` will increment the major version number.
All backwards incompatible changes prior to version ``1.0.0`` will increment the minor
version number.

Since this is a Python project, only the subset of the semantic versioning spec that is
compatible with `PEP-440`_ will be used.
<commit_msg>Add link to Capistrano docs<commit_after>Design
======

This section will go over some assumptions made by the Tunic library,
the general design of the library, and some things to keep in mind when
using it.

Purpose
-------

Tunic is meant to supplement your existing Fabric based deploy process,
not to replace it or the Fabric library / tool. Tunic is **not** an abstraction
layer for Fabric. It's merely meant to let you avoid writing the same thing
over and over again.

Directory structure
-------------------

Tunic doesn't care about where on your server you deploy to. However, it
expects that deployments are organized in a particular way and that each
deployment of your project is named in a particular way. The following
are **required** for Tunic functionality to work correctly.

For this example, let's assume you're deploying your project to ``/srv/www/myapp``.

* This base directory for your project should be writable as the user or group
  that deploys are being performed by.

* The directory structure under ``/srv/www/myapp`` must organized as follows. ::

    /
    +-- srv
        +-- www
            +-- myapp
                |-- releases
                |   +-- 20141105123145-0.2.0
                |   +-- 20141002231442-0.1.0
                +-- current

* The ``releases`` directory must be under your project base directory and be
  writeable by the user or group that deploys are being performed by.

* Each deploy under the ``releases`` directory must be named starting with a
  timestamp corresponding to when the deploy was done. The timestamp component
  should built with the largest period of time first (the current year), followed
  by each smaller component down to the second. The timezone used to generate this
  timestamp component doesn't matter as long as you always use the same one.

  The name for each deploy will be generated for you (in UTC) if you use the
  :func:`tunic.core.get_release_id` function. This is required to ensure that we
  can determine the time deploys were done relative to each other.

* ``current`` must be a symlink to the active deployment in the ``releases``
  directory. This symlink will be created for you automatically if you use the
  :meth:`tunic.core.ReleaseManager.set_current_release` method as part of your
  deploy process.

If you've used Capistrano, this structure should feel pretty `familiar <http://capistranorb.com/documentation/getting-started/structure/>`_ ;)
  
Dependence on Fabric
--------------------

Since Tunic is built on Fabric, it inherits the following behavior.

* Output from commands run by methods in :mod:`tunic.api` ends up being displayed
  just like output from commands run by Fabric. This can be changed through the
  use of Fabric `context managers`_.

* Since Tunic requires Fabric and Fabric doesn't support Python 3 (yet), Tunic
  won't work with Python 3 at this time.

* Since Tunic makes heavy use of Fabric and Fabric is not `thread safe`_, Tunic
  is also not thread safe.

.. _context managers: http://docs.fabfile.org/en/latest/api/core/context_managers.html
.. _thread safe: http://www.fabfile.org/faq.html#is-fabric-thread-safe


Versions
--------

Tunic uses `semantic versioning`_ of the form ``major.minor.patch``. All backwards
incompatible changes after version ``1.0.0`` will increment the major version number.
All backwards incompatible changes prior to version ``1.0.0`` will increment the minor
version number.

Since this is a Python project, only the subset of the semantic versioning spec that is
compatible with `PEP-440`_ will be used.

{'fraction_non_alphanumeric': 0.0781205369894316, 'fraction_numerical': 0.012853470437017995, 'mean_word_length': 3.333539603960396, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 4, 'https://': 0, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2446426', 'n_tokens_mistral': 1921, 'n_tokens_neox': 1814, 'n_words': 957}