3. Developers Guide

3.1. Contributing Guide

Contributions are welcome and greatly appreciated!

3.1.1. Workflow

A bug-fix or enhancement is delivered using a pull request. A good pull request should cover one bug-fix or enhancement feature. This ensures the change set is easier to review and less likely to need major re-work or even be rejected.

The workflow that developers typically use to fix a bug or add enhancements is as follows.

  • Fork the ronto repo into your account.

  • Obtain the source by cloning it onto your development machine.

    $ git clone git@github.com:your_name_here/ronto.git
    $ cd ronto
    
  • Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature
    

    Now you can make your changes locally.

  • Familiarize yourself with the developer convenience rules in the Makefile.

    $ make help
    
  • Create and activate a Python virtual environment for local development.

    $ make venv
    $ source path/to/<venv-name>/bin/activate
    (venv) $
    

    The rule creates the virtual environment outside the project directory so that it never accidentally gets added to the change set.

    Note

    (venv) is used to indicate when the commands should be run within the virtual environment containing the development dependencies.

  • Prepare your virtual environment for development:

    (venv) $ python setup.py develop
    (venv) $ pip install -r requirements.dev.txt
    

    The requirements.dev.txt contains tools like coverage that are needed to test, docs, etc.

  • Develop fix or enhancement:

    • Make a fix or enhancement (e.g. modify a class, method, function, module, etc).

    • Update an existing unit test or create a new unit test module to verify the change works as expected.

    • Run the test suite.

      (venv) $ make test
      

      See the Testing section for more information on testing.

    • Check code coverage of the area of code being modified.

      (venv) $ make check-coverage
      

      Review the output produced in docs/source/coverage/coverage.html. Add additional test steps, where practical, to improve coverage.

    • Fix any errors or regressions.

  • The docs and the change log should be updated for anything but trivial bug fixes. Perform docs check.

    (venv) $ make docs
    

    See the Documentation section for more information.

  • Commit and push changes to your fork.

    $ git add .
    $ git commit -m "A detailed description of the changes."
    $ git push origin name-of-your-bugfix-or-feature
    

    A pull request should preferably only have one commit upon the current master HEAD, (via rebases and squash).

  • Submit a pull request through the service website (e.g. Github, Gitlab).

  • Check automated continuous integration steps all pass. Fix any problems if necessary and update the pull request.

3.2. Testing

The ronto project implements a regression test suite that improves developer productivity by identifying capability regressions early.

Developers implementing fixes or enhancements must ensure that they have not broken existing functionality. The ronto project provides some convenience tools so this testing step can be quickly performed.

Developer unit tests are supported with py.test as well as component tests are supported with behave.

The unit tests are specified in the tests folder. The component tests are specified in the features folder.

Use the Makefile convenience rules to run the tests.

(venv) $ make test

To run tests verbosely use:

(venv) $ make test-verbose

Alternatively, you may want to run the tests suites directly. The following steps assume you are running in a virtual environment in which the ronto package has been installed. If this is not the case then you will likely need to set the PYTHONPATH environment variable so that the ronto package can be found.

(venv) $ py.test  # unit tests
(venv) $ behave  # component tests

3.3. Code Style

Adopting a consistent code style assists with maintenance. This project uses the code style formatter called Black. A Makefile convenience rule to enforce code style compliance is available.

(venv) $ make style

3.4. Type Annotations

The code base contains type annotations to provide helpful type information that can improve code maintenance.

Use the Makefile convenience rule to check no issues are reported.

(venv) $ make check-types

3.5. Documentation

To rebuild this project’s documentation, developers should use the Makefile in the top level directory. It performs a number of steps to create a new set of sphinx html content.

(venv) $ make docs

To quickly check consistency of ReStructuredText files use the dummy run which does not actually generate HTML content.

(venv) $ make check-docs

To quickly view the HTML rendered docs, start a simple web server and open a browser to http://127.0.0.1:8000/.

(venv) $ make serve-docs

3.6. Versioning

This project is a command line tool. Semantic versioning is applied and interpreted as follow:

  • major change: New commands, new ronto.yml version - or just something
    important
  • minor change: Additional options, additional fields in ronto.yml
    no behavior change.
  • patch change: Same behavior, bug-fixes applied

Versions with major equal to zero imply an expectation of sematic instability in cli and ronto file.

3.7. Release Process

The following steps are used to make a new software release.

The steps assume they are executed from within a development virtual environment.

  • Check that the package version label in __init__.py is correct.

  • Create and push a repo tag to Github.

    $ git checkout master
    $ git tag vMajor.Minor.Patch -m "A meaningful release tag comment"
    $ git tag  # check release tag is in list
    $ git push --tags origin master
    
    • This will trigger Github to create a release at:

      https://github.com/{username}/ronto/releases/{tag}
      
  • Create the release distribution. This project produces an artefact called a pure Python wheel. The wheel file will be created in the dist directory.

    (venv) $ make dist
    
  • Test the release distribution. This involves creating a virtual environment, installing the distribution into it and running project tests against the installed distribution. These steps have been captured for convenience in a Makefile rule.

    (venv) $ make dist-test
    
  • Upload the release to PyPI using

    (venv) $ make dist-upload
    

    The package should now be available at https://pypi.org/project/ronto/