.. This file is part of everyapp.bootstrap.
.. Copyright (C) 2010-2012 Krys Lawrence
..
.. everyapp.bootstrap is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by the
.. Free Software Foundation, either version 3 of the License, or (at your
.. option) any later version.
..
.. everyapp.bootstrap is distributed in the hope that it will be useful, but
.. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.. or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
.. more details.
..
.. You should have received a copy of the GNU General Public License along with
.. this program.  If not, see <http://www.gnu.org/licenses/>.

.. index:: hacking, development; overview
.. _hacking:

Development Overview
====================

Developing *everyapp.bootstrap* can be great fun.  In order to keep things
manageable, the source code is stored in a Mercurial_ repository and a
consistent development environment has been built (using *everyapp.bootstrap*,
of course).  Additionally, the documentation, in it's various formats, is all
generated from a single set of source files that are readable in plain text
form as well.

In order to get started hacking, whether it be on the code or the
documentation, you need to clone the repository and bootstrap the development
environment.  See below for details on how to do both.  After that you are free
to make your changes and submit patches as desired.

Happy hacking! [#rms1]_

.. index:: clone repository, development; clone repository
.. _clone_repository:

Cloning the Repository
======================

*everyapp.bootstrap*'s source code is stored in a Mercurial_ repository on
Bitbucket_.  To check out the latest revision from the repository, run::

  hg clone https://bitbucket.org/everyapp/bootstrap everyapp.bootstrap

.. index::
   pair: development; environment
.. _development_environment:

Setting up a Development Environment
====================================

Once you have cloned the repository (see above), you need to bootstrap the
development environment before you can start hacking on the code effectively.
To do so, run these commands::

  cd everyapp.bootstrap
  python bootstrap.py
  source bin/activate

On Windows, replace the last line above with::

  Scripts\activate.bat

Or, to just install it directly, run::

  cd everyapp.bootstrap
  python setup.py install

.. index:: generating documentation, documentation; generating
.. _generating_documentation:

Generating the Documentation
============================

While the plain text version of the documentation provides most of the relevant
information, the full documentation is best experienced in one of the generated
formats.  The following generated formats are currently supported:

* |HTML|
* |PDF|
* EPUB_
* man_

You can view the generated documentation online, or you can generate the above
formats by following the instructions below.

.. NOTE::

   To generate the documentation, you must first set up the development
   environment (virtualenv_ environment with all development dependencies
   already installed).  The instructions and code assume that you are working
   from within one.  See above for instructions on how to set one up.

.. NOTE::

   In addition to the tools automatically included in the development
   environment, you will also need to have Latex_ installed in order to
   generate the |PDF| format.  See the `Sphinx documentation
   <http://sphinx.pocoo.org/builders.html#sphinx.builders.latex.LaTeXBuilder>`_
   for details.  If you do not have Latex_ installed, or do not want the |PDF|
   version, just omit the ``latexpdf`` option or command from the instructions
   below.

On |POSIX| systems (Linux, Mac, etc.), run the following commands::

  cd  doc/source
  make clean html epub latexpdf man

On Windows systems, run the following::

  cd doc\source
  make clean
  make html
  make epub
  make latexpdf
  make man

On all platforms the generated documentation will be in the |doc/build|
directory.

.. index:: packaging a release, release; packaging
.. _packaging_release:

Packaging a Release
===================

This project occasionally produces release distributions.  These are stable
versions of the code with specific version numbers.  Additionally, sometimes it
is useful to produce development releases.  The instructions below outline how
to create release distributions.

To make a release:

1. Update the release date and add important changes in the |doc/NEWS.txt|
   file.  Commit the changes.
2. Proof read and spell check all source code and documentation.  Commit the
   changes.
3. Tag the release using the version number as the tag.  e.g. ``v0.3.1``.
4. Generate the change log with::

     hg log --style changelog > doc/ChangeLog.txt

5. If running on a |POSIX| machine (Linux, Mac), fix the line endings with::

     unix2dos doc/ChangeLog.txt

6. If this is an official release and not a development release, run::

     python setup.py release sdist

7. Otherwise, run::

     python setup.py sdist

8. Test the generated source distribution in the |dist/| directory.
9. Upload to PyPI by running::

     python setup.py [release] sdist register upload

10. Delete the generated |doc/ChangeLog.txt| file.
11. Generate the documentation by following |the instructions above|.
12. Copy the |PDF| and EPUB_ version into the |HTML| version by running::

      cd doc/build
      cp latex/everyapp.bootstrap-<version>.pdf html/_static/everyapp.bootstrap.pdf
      cp epub/everyapp.bootstrap-<version>.epub html/_static/everyapp.bootstrap.epub

    Or on Windows, run::

      cd doc\build
      copy latex\everyapp.bootstrap-<version>.pdf html\_static\everyapp.bootstrap.pdf
      copy epub\everyapp.bootstrap-<version>.epub html\_static\everyapp.bootstrap.epub

13. Upload the documentation by running::

      python setup.py upload_docs

14. Increase version in |setup.py| for the next release.  Make sure this is
    consistent with `Semantic Versioning 1.0.0
    <http://semver.org/spec/v1.0.0.html>`_.
15. Add a new section to |doc/NEWS.txt| for the next release.
16. Commit the changes.
17. Remember to push all changesets to Bitbucket.
18. Update your development environment by running::

      python setup.py develop

.. rubric:: Footnotes

.. [#rms1] This expression is most famously used by `Richard M. Stallman`_.
