diff --git a/docs/source/dev-doc-message.txt b/docs/source/dev-doc-message.txt new file mode 100644 index 0000000000..c1505ba97a --- /dev/null +++ b/docs/source/dev-doc-message.txt @@ -0,0 +1,3 @@ +.. note:: + + This page is intended for developers of zipline. diff --git a/docs/source/index.rst b/docs/source/index.rst index 53046515ce..29b94bb83c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -9,3 +9,4 @@ Index beginner-tutorial releases appendix + release-process diff --git a/docs/source/release-process.rst b/docs/source/release-process.rst new file mode 100644 index 0000000000..af5565dbad --- /dev/null +++ b/docs/source/release-process.rst @@ -0,0 +1,197 @@ +Zipline Release Process +----------------------- + +.. include:: dev-doc-message.txt + + +Updating the Release Notes +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When we are ready to ship a new release of zipline, edit the :doc:`releases` +page. We will have been maintaining a whatsnew file while working on the release +with the new version. First, find that file in: +``docs/source/whatsnew/.txt``. It will be the highest version number. +Edit the release date field to be today's date in the format: + +:: + + , + + +then include this file in ``docs/source/releases.rst``. New releases should +appear at the top. The syntax for this is: + +:: + + .. include:: whatsnew/.txt + + +Updating the ``__version__`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We use `versioneer `__ to +manage the ``__version__`` and ``setup.py`` version. This means that we pull +this information from our version control's tags to ensure that they stay in +sync and to have very fine grained version strings for development installs. + +To upgrade the version use the git tag command like: + +.. code-block:: bash + + $ git tag .. + $ git push + $ git push --tags + + +This will push the the code and the tag information. + + +Uploading PyPI packages +~~~~~~~~~~~~~~~~~~~~~~~ + +``sdist`` +^^^^^^^^^ + +To build the ``sdist`` (source distribution) run: + +.. code-block:: bash + + $ python setup.by sdist + + +from the zipline root. This will create a gzipped tarball that includes all the +python, cython, and miscellaneous files needed to install zipline. To test that +the source dist worked correctly, ``cd`` into an empty directory, create a new +virtualenv and then run: + + +.. code-block:: bash + + $ pip install /dist/zipline-...tar.gz + $ python -c 'import zipline;print(zipline.__version__)' + +This should print the version we are expecting to release. + +.. note:: + + It is very important to both ``cd`` into a clean directory and make a clean + virtualenv. Changing directories ensures that we have included all the needed + files in the manifest. Using a clean virtualenv ensures that we have listed + all the required packages. + +Now that we have tested the package locally, it should be tested using the test +PyPI server. + +Edit your ``~/.pypirc`` file to look like: + +:: + + [distutils] + index-servers = + pypi + pypitest + + [pypi] + username: + password: + + [pypitest] + repository: https://testpypi.python.org/pypi + username: + password: + +after that, run: + +.. code-block:: bash + + $ python setup.py sdist upload -r pypitest + + +.. note:: + + If the package version has been taken: locally update your setup.py to + override the version with a new number. Do not use the next version, just + append a ``.`` section to the current version. PyPI prevents the same + package version from appearing twice, so we need to work around this when + debugging packaging problems on the test server. + + .. warning:: + + Do not commit the temporary version change. + + +This will upload zipline to the pypi test server. To test installing from pypi, +create a new virtualenv, ``cd`` into a clean directory and then run: + +.. code-block:: bash + + $ pip install -i https://testpypi.python.org/pypi zipline + $ python -c 'import zipline;print(zipline.__version__)' + + +This should pull the package you just uploaded and then print the version +number. + +Now that we have tested locally and on PyPI test, it is time to upload to PyPI: + +.. code-block:: bash + + $ python setup.py sdist upload + +``bdist`` +^^^^^^^^^ + +.. note:: + + If you are running on GNU/Linux, then you cannot upload any binary wheels. + +First, build the wheels locally with: + +.. code-block:: bash + + $ python setup.py bdist_wheel + + +Just like the ``sdist``, we need to ``cd`` into a clean directory and use a +clean virtualenv. Then, test that the wheel was built successfully with: + +.. code-block:: bash + + $ pip install /dist/ + $ python -c 'import zipline;print(zipline.__version__)' + +The version number should be the same as the version you are releasing. +We must repeat this process for both python 2 and 3. +Once you have tested the package, it can be uploaded to PyPI with: + +.. code-block:: bash + + $ python setup.py bdist_wheel upload + +Documentation +~~~~~~~~~~~~~ + +To update `zipline.io `__, run: + +.. code-block:: bash + + $ cd /docs + $ make html + $ cp -r build/html /tmp/zipline-doc + $ git checkout gh-pages + $ mv /tmp/zipline-doc/* . + $ rm /tmp/zipline-doc + + +Now, using our browser of choice, view the ``index.html`` page and verify that +the docs look correct. + +Once we are happy, run: + +.. code-block:: bash + + $ git add . + $ git commit -m "DOC: update zipline.io" + $ git push + +`zipline.io `__ will update in a few moments. diff --git a/docs/source/whatsnew/0.8.4.txt b/docs/source/whatsnew/0.8.4.txt index d6e17e8c2d..33849bf855 100644 --- a/docs/source/whatsnew/0.8.4.txt +++ b/docs/source/whatsnew/0.8.4.txt @@ -55,4 +55,4 @@ Build Documentation ~~~~~~~~~~~~~ -None +* Document the release process for developers (:issue:`835`).