docs/DevelopmentSetup.rst
.. _development-setup:
Development Setup
=================
Make sure that you have the :ref:`repository installed
<installation-repository>`.
.. _development-setup-requirements:
Install Requirements
--------------------
To install all requirements for the development setup, execute
.. code:: bash
pip install --upgrade -r requirements.txt -r test-requirements.txt -r dev-requirements.txt
Sphinx Documentation Setup
--------------------------
Sphinx was setup using `the tutorial from readthedocs
<http://read-the-docs.readthedocs.io/en/latest/getting_started.html>`__.
It should be already setup if you completed :ref:`the previous step
<development-setup-requirements>`.
Further reading:
- `domains <http://www.sphinx-doc.org/en/stable/domains.html>`__
With Notepad++ under Windows, you can run the `make_html.bat
<https://github.com/fossasia/kniteditor/blob/master/docs/make_html.bat>`__ file in the
``docs`` directory to create the documentation and show undocumented code.
Code Climate
------------
To install the code climate command line interface (cli), read about it in
their github `repository <https://github.com/codeclimate/codeclimate>`__
You need docker to be installed. Under Linux you can execute this in the
Terminal to install docker:
.. code:: bash
wget -qO- https://get.docker.com/ | sh
sudo usermod -aG docker $USER
Then, log in and out. Then, you can install the command line interface:
.. code:: bash
wget -qO- https://github.com/codeclimate/codeclimate/archive/master.tar.gz | tar xvz
cd codeclimate-* && sudo make install
Then, go to the kniteditor repository and analyze it.
.. code:: bash
codeclimate analyze
Version Pinning
---------------
We use version pinning, described in `this blog post (outdated)
<http://nvie.com/posts/pin-your-packages/>`__.
Also read the `current version
<https://github.com/nvie/pip-tools>`__ for how to set up.
After installation you can run
.. code:: bash
pip install -r requirements.in -r test-requirements.in -r dev-requirements.in
pip-compile --output-file requirements.txt requirements.in
pip-compile --output-file test-requirements.txt test-requirements.in
pip-compile --output-file dev-requirements.txt dev-requirements.in
pip-sync requirements.txt dev-requirements.txt test-requirements.txt
pip install --upgrade -r requirements.txt -r test-requirements.txt -r dev-requirements.txt
``pip-sync`` uninstalls every package you do not need and
writes the fix package versions to the requirements files.
Continuous Integration
----------------------
Motivation
~~~~~~~~~~
Deployment is automized by `Travis
<https://travis-ci.org/fossasia/kniteditor>`__ and `AppVeyor
<https://ci.appveyor.com/project/AllYarnsAreBeautiful/kniteditor>`__.
In order to ease the deployment for you, the developer, only a new tag needs to
be created and a new release is uploaded to `Github
<https://github.com/fossasia/kniteditor/releases>`__ and `PyPi
<https://pypi.python.org/pypi/kniteditor>`__.
Travis and AppVeyor build the corresponding executables and upload them
automatically. No special setup is required to create the executables yourself.
However, in case you wish to create the executables yourself, have a look into the
corresponding build folders in the repository root.
How To Deploy
~~~~~~~~~~~~~
Before you put something on `Pypi
<https://pypi.python.org/pypi/kniteditor>`__, ensure the following:
1. The version is in the master branch on github.
2. The tests run by travis-ci run successfully.
Pypi is automatically deployed by travis. `See here
<https://docs.travis-ci.com/user/deployment/pypi>`__.
To upload new versions, tag them with git and push them.
.. code:: bash
setup.py tag_and_deploy
The tag shows up as a `travis build
<https://travis-ci.org/fossasia/kniteditor/builds>`__.
If the build succeeds, it is automatically deployed to `Pypi
<https://pypi.python.org/pypi/kniteditor>`__.
Manual Upload to the Python Package Index
-----------------------------------------
However, here you can see how to upload this package manually.
Version
~~~~~~~
Throughout this chapter, ``<new_version>`` refers to a a string of the form ``[0-9]+\.[0-9]+\.[0-9]+[ab]?`` or ``<MAYOR>.<MINOR>.<STEP>[<MATURITY>]`` where ``<MAYOR>``, ``<MINOR>`` and, ``<STEP>`` represent numbers and ``<MATURITY>`` can be a letter to indicate how mature the release is.
1. Create a new branch for the version.
.. code:: bash
git checkout -b <new_version>
2. Increase the ``__version__`` in `__init__.py <kniteditor/__init__.py#L3>`__
- no letter at the end means release
- ``b`` in the end means Beta
- ``a`` in the end means Alpha
3. Commit and upload this version.
.. _commit:
.. code:: bash
git add kniteditor/__init__.py
git commit -m "version <new_version>"
git push origin <new_version>
4. Create a pull-request.
5. Wait for `travis-ci <https://travis-ci.org/fossasia/kniteditor>`__ to pass the tests.
6. Merge the pull-request.
7. Checkout the master branch and pull the changes from the commit_.
.. code:: bash
git checkout master
git pull
8. Tag the version at the master branch with a ``v`` in the beginning and push it to github.
.. code:: bash
git tag v<new_version>
git push origin v<new_version>
9. Upload_ the code to Pypi.
Upload
~~~~~~
.. Upload:
First ensure all tests are running:
.. code:: bash
setup.py pep8
From `docs.python.org
<https://docs.python.org/3.1/distutils/uploading.html>`__:
.. code:: bash
setup.py sdist bdist_wininst upload register
Classifiers
-----------
You can find all Pypi classifiers `here
<http://pypi.python.org/pypi?%3Aaction=list_classifiers>`_.