DEVELOPMENT.rst

Development And Publishing
==========================

Environment Setup
-----------------

To create a local virtualenv, run::

    make setup

This will create a virtualenv at ``./venv``, install dependencies with pip,
and install pyright using npm.

To activate the environment in your shell::

    . ./venv/bin/activate

Alternately, run everything with the make tasks, which source the activate
script before running commands.

conda
~~~~~

To create a Conda environment, run::

    conda env create
    npm i

To update the environment, run::

    conda env update
    npm i --update

To activate the environment, run::

    conda activate pyee

The other Makefile tasks should operate normally if the environment is
activated.

Formatting, Linting and Testing
-------------------------------

The basics are wrapped with a Makefile::

    make format  # runs black
    make lint  # runs flake8
    make test  # runs pytest

Generating Docs
---------------

Docs for published projects are automatically generated by readthedocs, but
you can also preview them locally by running::

    make build_docs

Then, you can serve them with Python's dev server with::

    make serve_docs

Publishing
----------

Do a Final Check
~~~~~~~~~~~~~~~~

Make sure that formatting looks good and that linting and testing are passing.

Update the Changelog
~~~~~~~~~~~~~~~~~~~~

Update the CHANGELOG.rst file to detail the changes being rolled into the new
version.

Update the Version in setup.py
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This project *used* to use ``vcversioner`` and versioning of the package
would automatically leverage the appropriate git tag, but that is no longer the
case.

I do my best to follow `semver <https://semver.org>` when updating versions.

Add a Git Tag
~~~~~~~~~~~~~

This project uses git tags to tag versions::

    git tag -a {version} -m 'Release {version}'

You don't need to prefix the version with a ``v``.

Build and Publish
~~~~~~~~~~~~~~~~~

To package everything, run::

    make package

To publish::

    make publish

Push the Tag to GitHub
~~~~~~~~~~~~~~~~~~~~~~

::

    git push origin main --tags

Check on RTD
~~~~~~~~~~~~

RTD should build automatically but I find there's a delay so I like to kick it
off manually. Log into `RTD <https://readthedocs.org>`, log in, then go
to `the pyee project page <https://readthedocs.org/projects/pyee/>` and build
latest and stable.

Announce on Twitter
~~~~~~~~~~~~~~~~~~~

It's not official, but I like to announce the release on Twitter.