Skip to content

Development Instructions

Jump to bottom
Kesara Rathnayake edited this page Jul 21, 2022 · 4 revisions

Home | GettingStarted | Contributing | Development Instructions | Code of Conduct

Development Instructions

Read GettingStarted and Contributing guides first.

xml2rfc Docker image

The easiest way to set up a development environment is using the provided Docker image. Run the following command on a separate terminal to build and start a docker environment:

./run.sh

This brings up a bash shell and the Docker image is equipped with all the dependencies required for xml2rfc including fonts. This binds your current working directory to the docker image using -v ${PWD}:/root/xml2rfc.

Create a working branch

Next, create a working branch from your fork and switch to the working branch. See Creating a Fork and Create a Local Branch sections in the Contributing guide for more information.

Run yestests

The xml2rfc test suite updates the dates of valid test results every time you run the test suite. Because of this reason, run the yestests before you change anything. You can run yestests with the following command.

tox -e py38 yestests

py38 is the Python version (Python 3.8) that you want to run tests on this can be anything from py37, py38, py39, py310. For the purpose of running yestests and initial testing, running tests on a single Python version is sufficient.

When yestests are complete, commit the changes from tests to your branch. NOTE: You have to do this from your different terminal on your working directory or using your favourite git tool.

git commit tests -m "chore: Run yestests"

Change, test & carry on

Now your branch is ready for changes. Do the appropriate changes and test them with the Python version of your choosing. If you use: tox -e py38, tox will wait for your input on any output changes. It might be easier to run tox -e py38 yestests and inspect the test output for differences.

You can run only a certain set of tests with tox. Inspect Makefile for test names. For example, run only index tests:

tox -e py39 indextest

When you are happy with the changes. Run tests on all supported python environments with the following command:

tox -e py37,py38,py39,py310

Push your changes and create PR. See Create a Pull Request section in the Contributing guide for more information.

Clone this wiki locally