Contributing

Here you will find how to contribute to the project, setting up an environment, submit modifications & report bugs.

Setting up the local copy of the code

1. If you are a new contributor, you will have to fork the repository (https://github.com/ysard/libre-printer), clone it, and then add an upstream repository.

   More information on: GitHub doc: forking workflow.

   Note

   Please note that the active branch of development is named dev. The master branch is the stable release branch; please avoid proposing pull-requests on this branch except for bugfixes.

   $ # Clone your fork
   $ git clone -b dev git@github.com:<your_username>/libre-printer.git
   $ # Add upstream repository
   $ git remote add upstream git@github.com:ysard/libre-printer.git
   

   Now, you should have 2 remote repositories named (git branch):

   • upstream, which refers to the Libre-Printer repository

   • origin, which refers to your personal fork

2. Develop your contribution:

   Pull the latest changes from upstream:

   $ git checkout <branch_of_reference>
   $ git pull upstream <branch_of_reference>
   

   Create a branch for the feature you want to work on; the branch name should be explicit and if possible related to an opened issue (Ex: Issue number 000 in the following).

   $ git checkout -b bugfix-#000
   

   Make small commits with explicit messages about why you do things as you progress (git add and git commit).

   Cover your code with unit tests and run them before submitting your contribution.

   The following Make command is here to run all the tests & produce coverage stats:

   $ make coverage
   

3. Submit your contribution:

   Push your changes to your fork:

   $ git push origin bugfix-#000
   

   Go to the GitHub website. The new branch and a green pull-request button should appear. To facilitate reviewing and approval, it is strongly encouraged to add a full description of your changes to the pull-request.

Setting up the build environment

Once you’ve cloned your fork of the Libre-Printer repository, you should set up a Python development environment tailored for the project.

See the chapter Setting up a Python virtual environment for a manual installation of the installation process.

Then see the chapter Install the development version.

Documentation

Documentation is built using Sphinx.

Documentation is mostly written as reStructuredText (.rst) files.

reStructuredText enables python-generated text to fill your documentation as in the auto-importing of modules or usage of plugins like sphinx-argparse.

Here’s a subset of reStructuredText to help you get started writing these files:

• Full specification

• Quick references for Sphinx

Folder structure

The documentation source-files are located in ./doc/source/, with ./doc/source/index.rst being the main entry point. Each subsection of the documentation is a .rst file inside ./doc/source/.

Html files are generated in ./doc/build/.

Building documentation

Building the documentation locally is useful to test changes. First, make sure you have the development dependencies installed; See Setting up the build environment

Then build the HTML output format by running:

make doc
# or
make -C ./doc html

Sphinx caches built documentation by default, which is generally great, but can cause the sidebar of pages to be stale. You can clean out the cache with:

make -C ./doc clean

Reporting bugs

Please report bugs on GitHub.

Test the project

The project frequently uses tricks to simulate the behavior of the hardware interface without having it on hand. This allows for many tests to be executed quickly and independently of the hardware.

For this purpose, unit tests use a virtual serial interface initialized with the socat tool.

It is also possible to run the service with a virtual interface during manual tests.

• The following command will create a virtual interface named virtual-tty in the project directory:

$ make test_tty_to_tty

• Configure the path to the virtual interface via the serial_port= parameter in the libreprinter.conf file.

• Start the service:

$ make run

• Once launched, the service awaits an acknowledgment from the interface. This is something you can simulate with the following command:

$ make send_end_config

• Then send the data as a computer does to a printer, use the input_tty_generator.py script located in tools/:

$ ./input_tty_generator.py

In addition, you can easily connect a USB-TTL (UART) converter to your computer and using it as a Serial printer once connected to the physical interface.

As it is presented in the chapter About the USB/Centronics adapters, many printers can be configured in CUPS to send their data to a custom tty or LPT interface.