<commit_before>Developing tomcatmanager
========================

Get Source Code
---------------

Clone the repo from github::

		$ git clone <EMAIL>:tomcatmanager/tomcatmanager.git

I recommend using ``virtualenvwrapper`` and friends, especially for
development use. tomcatmanager requires python 3, I assume you've
already got that installed. Create a new environment, and then install
development dependencies::

    $ cd tomcatmanager
    $ mkvirtualenv --python=/usr/local/bin/python3 tomcatmanager
    $ setvirtualenvproject ~/.virtualenvs/tomcatmanager .
    $ workon tomcatmanager
    $ pip install -e .
    $ pip install -e .[dev]


Branches, tags, and versions
----------------------------

This project uses a simplified version of the `git flow branching
strategy <http://nvie.com/posts/a-successful-git-branching-model/>`_. We
don't use release branches, and we generally don't do hotfixes, so we
don't have any of those branches either. The master branch always
contains the latest release of the code uploaded to PyPI, with a tag for
the version number of that release.


The develop branch is where all the action occurs. Feature branches are
welcome. When it's time for a release, we merge develop into master.

This project uses `semantic versioning <http://semver.org/>`_.


Install in place
----------------

If you want to use the code in your repo as the module that everything
else imports, you can have setup.py deploy the package as links to your
source code instead of copying files to your python ``site-packages``
folder::

    $ python3 setup.py develop

To remove the development links::

    $ python3 setup.py develop --uninstall


Testing
-------

To ensure the tests can run without an external dependencies,
``tests/mock_server80.py`` contains a HTTP server which emulates
the behavior of Tomcat Manager 8.0. There is a test fixture to start
this server, and all the tests run against this fixture.

To run the tests::

	$ pytest


Make a Release
--------------

To make a release and deploy it to `PyPI
<https://pypi.python.org/pypi>`_, do the following:

1. Merge everything to be included in the release into the develop branch.

2. Ensure ``setup.py`` and ``docs/source/conf.py`` have the correct version number. If not, commit the proper version number to the develop branch.

3. Merge the develop branch into the master branch.

4. Tag the master branch with the version number

5. Clean the build::

    $ python3 setup.py clean --all
    $ rm -rf dist/

6. Build the source distribution::

    $ python3 setup.py sdist

7. Build the wheel::

    $ python3 setup.py bdist_wheel

8. Build the docs::

    $ python3 setup.py build_docs

9. Deploy the docs?

10. Upload packages to PyPI::

    $ twine upload dist/*

11. Checkout the develop branch and update the version numbers in ``setup.py`` and ``docs/source/conf.py``.<commit_msg>Update developer docs re: doctests<commit_after>Developing tomcatmanager
========================

Get Source Code
---------------

Clone the repo from github::

		$ git clone <EMAIL>.com:tomcatmanager/tomcatmanager.git

I recommend using ``virtualenvwrapper`` and friends, especially for
development use. tomcatmanager requires python 3, I assume you've
already got that installed. Create a new environment, and then install
development dependencies::

    $ cd tomcatmanager
    $ mkvirtualenv --python=/usr/local/bin/python3 tomcatmanager
    $ setvirtualenvproject ~/.virtualenvs/tomcatmanager .
    $ workon tomcatmanager
    $ pip install -e .
    $ pip install -e .[dev]


Branches, tags, and versions
----------------------------

This project uses a simplified version of the `git flow branching
strategy <http://nvie.com/posts/a-successful-git-branching-model/>`_. We
don't use release branches, and we generally don't do hotfixes, so we
don't have any of those branches either. The master branch always
contains the latest release of the code uploaded to PyPI, with a tag for
the version number of that release.


The develop branch is where all the action occurs. Feature branches are
welcome. When it's time for a release, we merge develop into master.

This project uses `semantic versioning <http://semver.org/>`_.


Install in place
----------------

If you want to use the code in your repo as the module that everything
else imports, you can have setup.py deploy the package as links to your
source code instead of copying files to your python ``site-packages``
folder::

    $ python3 setup.py develop

To remove the development links::

    $ python3 setup.py develop --uninstall


Testing
-------

To ensure the tests can run without an external dependencies,
``tests/mock_server80.py`` contains a HTTP server which emulates
the behavior of Tomcat Manager 8.0. There is a test fixture to start
this server, and all the tests run against this fixture.

To run the tests::

	$ pytest

This runs all the test in ``tests/`` and also runs doctests in
``tomcatmanager/``.

Make a Release
--------------

To make a release and deploy it to `PyPI
<https://pypi.python.org/pypi>`_, do the following:

1. Merge everything to be included in the release into the develop branch.

2. Ensure ``setup.py`` and ``docs/source/conf.py`` have the correct version
   number. If not, commit the proper version number to the develop branch.

3. Merge the develop branch into the master branch.

4. Tag the master branch with the version number

5. Clean the build::

    $ python3 setup.py clean --all
    $ rm -rf dist/

6. Build the source distribution::

    $ python3 setup.py sdist

7. Build the wheel::

    $ python3 setup.py bdist_wheel

8. Build the docs::

    $ python3 setup.py build_docs

9. Deploy the docs?

10. Upload packages to PyPI::

    $ twine upload dist/*

11. Checkout the develop branch and update the version numbers in
    ``setup.py`` and ``docs/source/conf.py``.
{'fraction_non_alphanumeric': 0.10550536901312425, 'fraction_numerical': 0.00852224305437191, 'mean_word_length': 3.2989010989010987, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4074535', 'n_tokens_mistral': 1651, 'n_tokens_neox': 1571, 'n_words': 770}