Skip to content

Contributing to Hitch Libraries

Thanks for getting involved!

All contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome.

If you have an idea for a new feature or a bug fix and wish to start working on it, please raise a new ticket before starting. This helps prevent wasted work.

Getting started with development

Hitch libraries are developed and tested with the hitch framework rather than, say, pytest. The main reason for this is that one story can triple as specification, test and generate readable documentation.

There are a a number of other principles that the framework tries to follow as well.

Below is a step by step guide to get started:

Mac set up getting started

To run integration tests / environment on a Mac, you need to first ensure that brew is installed (note that this will require XCode from the Mac App store is installed, and, subsequently, that "xcode-select --install" is run).

Once brew is installed, at a minimum you will need to install python and pipx:

$ brew install python python3 pipx

Followed by:

$ pipx install hitchkey

Note that hitchkey is a bootstrap script that sets up virtual environments. It has zero dependencies and very little code.

Git clone the repository somewhere new (e.g. a temporary directory) and switch to the branch you want.

Then, run hk in any folder inside the repo:

$ hk

It should install some packages and then output something similar to what you see below.

Please, if you experience any issues with the above steps, raise a ticket here and describe what happened.

This is vitally important to the health and future development of the framework.

Linux set up prerequisites

To set up:

$ sudo apt-get install python3 python-pip python-virtualenv pipx

$ pipx install hitchkey

Note that hitchkey is a bootstrap script with zero dependencies and will not interfere with other software.

Please, if you experience any issues with the above steps, raise a ticket here and describe what happened.

This is vitally important to the health and future development of the framework.

Using hitchkey

You should be presented with a list of available commands similar to this:

Usage: hk command [args]

          bdd - Run story matching keywords.
       docgen - Build documentation.
     doctests - Run doctests in utils.py in python 2 and 3.
         rbdd - Run story matching keywords and rewrite story if code changed.
    readmegen - Build documentation.
   regression - Run regression testing - lint and then run all tests.
         lint - Lint project code and hitch code.
       deploy - Deploy to pypi as specified version.

The only commands you really need to worry about (at least initially) are "hk bdd" and "hk regression".

  • To regression test the application, run "hk regression". Please run this as a smoke test before writing any code and raise a ticket if it fails for any reason with details.

  • To run an individual test run "hk bdd keyword" where the keyword or keywords are case insensitive words or parts of words that appear in the names of stories. For example, "hk bdd dirty" will run this story and "hk bdd exception" will run the exception variation story listed here the exception variation story here.