Skip to content

Latest commit

 

History

History
127 lines (97 loc) · 3.86 KB

CONTRIBUTING.md

File metadata and controls

127 lines (97 loc) · 3.86 KB

Contributing

Get Source Code

Clone the repo from github:

$ git clone [email protected]:python-cmd2/cmd2-abbrev.git

Create Python Environments

This project uses tox to run the test suite against multiple python versions. I recommend pyenv with the pyenv-virtualenv plugin to manage these various versions. If you are a Windows user, pyenv won't work for you, but conda can also be used to solve this problem.

This distribution includes a shell script build-pyenvs.sh which automates the creation of these environments.

If you prefer to create these virtual envs by hand, do the following:

$ cd cmd2_abbrev
$ pyenv install 3.8.0
$ pyenv virtualenv -p python3.8 3.8.0 cmd2-3.8
$ pyenv install 3.7.0
$ pyenv virtualenv -p python3.7 3.7.5 cmd2-3.7
$ pyenv install 3.6.5
$ pyenv virtualenv -p python3.6 3.6.9 cmd2-3.6
$ pyenv install 3.5.5
$ pyenv virtualenv -p python3.5 3.5.8 cmd2-3.5

Now set pyenv to make all three of those available at the same time:

$ pyenv local cmd2-3.8 cmd2-3.7 cmd2-3.6 cmd2-3.5

Whether you ran the script, or did it by hand, you now have isolated virtualenvs for each of the major python versions. This table shows various python commands, the version of python which will be executed, and the virtualenv it will utilize.

Command python virtualenv
python 3.8.0 cmd2-3.8
python3 3.8.0 cmd2-3.8
python3.7 3.7.5 cmd2-3.7
python3.6 3.6.9 cmd2-3.6
python3.5 3.5.8 cmd2-3.5
pip 3.8.0 cmd2-3.8
pip3 3.8.0 cmd2-3.8
pip3.7 3.7.5 cmd2-3.7
pip3.6 3.6.9 cmd2-3.6
pip3.5 3.5.8 cmd2-3.5

Install Dependencies

Install all the development dependencies:

$ pip install -e .[dev]

This command also installs cmd2-abbrev "in-place", so the package points to the source code instead of copying files to the python site-packages folder.

All the dependencies now have been installed in the cmd2-3.8 virtualenv. If you want to work in other virtualenvs, you'll need to manually select it, and install again::

$ pyenv shell cmd2-3.6 $ pip install -e .[dev]

Common Development Tasks

This project uses many other python modules for various development tasks, including testing, linting, building wheels, and distributing releases. These modules can be configured many different ways, which can make it difficult to learn the specific incantations required for each project you are familiar with.

This project uses invoke to provide a clean, high level interface for these development tasks. To see the full list of functions available:

$ invoke -l

You can run multiple tasks in a single invocation, for example:

$ invoke clean docs sdist wheel

That one command will remove all superflous cache, testing, and build files, render the documentation, and build a source distribution and a wheel distribution.

For more information, read tasks.py.

Make a Release

To make a release and deploy it to PyPI, do the following:

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

  2. Run tox to make sure the tests pass in all the supported python versions.

  3. Review and update CHANGELOG.md.

  4. Push the master branch to github.

  5. Tag the master branch with the new version number, and push the tag.

  6. Build source distribution, wheel distribution, and upload them to Test PyPI:

    $ invoke pypi-test

    Check on test.pypi.org to make sure the package looks good.

  7. Build source distribution, wheel distribution, and upload them to PyPI:

    $ invoke pypi