Contributing

This section explains the various ways users can participate in the development of Monkeysign, or get support when they find problems.

Support schedule

First, to know a bit more about the version you are using, understand that we adhere to Semantic Versioning, which is:

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backwards-compatible manner, and
  • PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

The 2.0.x branch is featured in Debian Jessie and Ubuntu Xenial and is therefore be maintained for security fixes for the lifetime of those releases or of any other distribution that picks it up.

Most development and major bug fixes are done directly in the 2.x branch and published as part of minor releases, which in turn become supported branches.

Major, API-changing development will happen on the 3.x branch.

Those milestones are collaboratively tracked on 0xACAB.

Documentation

We love documentation!

We maintain the documentation in the Git repository, in RST format. Documentation can be edited directly on the website and built locally with Sphinx with:

cd doc ; make html

The Sphinx project has a good tutorial on RST online. Documentation is automatically generated on RTD.io.

Translation

Monkeysign is translated using the standard Gettext translation system. Translation files are located in the source tree, in the po/ subdirectory and can be edited using standard translation tools or even a regular text editor. A new translation for your locale can be created with the msginit command, see the gettext manual for more information about how to use gettext directly.

You can also use the Weblate web interface to translate Monkeysign directly in your browser, without having to install any special software. New translations from Weblate need to be updated in our source tree by hand, so do let us know if you make a new translation, by filing an issue in our online issue tracker.

Note

We have chosen Weblate instead of other solutions because it integrates well with our git-based workflow: translations on the site are stored as commits in the git repository, and the server is just another remote that we can merge directly. It also merges our changes automatically and so requires minimal work on our part. We have also considered tools like Transifex (proprietary) and Pootle (no public instance, requires us to run our own).

Tip

We encourage our users and developers to support Weblate’s development. Thank you to Weblate’s people for hosting our project for free!.

Bug reports

We want you to report bugs you find in Monkeysign. It’s an important part of contributing to a project, and all bug reports will be read and replied to politely and professionally.

Bugs used to be tracked with the bugs-everywhere package, but this has proven to be too difficult to use and not transparent enough to most users, so we are now using Gitlab, where new bug reports should be sent.

A good bug report will include:

  • lsb_release -b: operating system name, version and codename (Debian GNU/Linux 8.4 (jessie))
  • uname -a: kernel version, architecture and build dates (Linux marcos 3.16.0-4-amd64 #1 SMP Debian 3.16.7-ckt25-1 (2016-03-06) x86_64 GNU/Linux)
  • monkeysign --version and how it was installed
  • python --version
  • gpg --version
  • the output of monkeysign --debug when the faulty behavior is found

Warning

The output of the --debug shows public key material used by Monkeysign. Special efforts have been made so that private key material is never displayed (or in fact accessed directly or copied) but you may want to avoid publicly disclosing which keys you are signing because that can reveal your social graph. If you are confident the signed user will publish the results on the public keyservers, this is not much of a concern. But otherwise, you should leave that decision to that user. This is particularly relevant if you do not want to publicly certify this (e.g. if you are using the --local flag). Do review the output before sending it in bug reports.

If you are using the graphical interface, try to also include the versions of the following libraries:

  • GTK
  • PyGTK
  • ZBar
  • QRencode
  • PIL

In newer Monkeysign versions (2.1.0 or later), the above (and more) is included on backtraces and in the --version output.

Tip

Please do make sure the bug you have found has not already been reported elsewhere. Do review the existing issues in the online issue tracker and the Debian BTS for Monkeysign.

Note

The GPG library used to do cryptographic operations was written from scratch for Monkeysign because none of the existing Python libraries supported key signing. In retrospect, this was a mistake, and there are plans to replace the builtin library with an external, better-maintained one (see 0xACAB issue #22). In the meantime, there may be problems with exotic keys or new versions of GnuPG. Do report those issues as bugs.

Debian BTS

You can also report bugs by email over the Debian BTS, even if you are not using Debian. Use the reportbug package to report a bug if you run Debian (or Ubuntu), otherwise send an email to submit@bugs.debian.org, with content like this:

To: submit@bugs.debian.org
From: you@example.com
Subject: fails to frobnicate

Package: monkeysign
Version: 1.0

Monkeysign fails to frobnicate.

I tried to do...

I was expecting...

And instead I had this backtrace...

I am running Arch Linux 2013.07.01, Python 2.7.5-1 under a amd64
architecture.

See also the complete instructions for more information on how to use the Debian bugtracker. You can also browse the existing bug reports in the Debian BTS for Monkeysign there.

Bug triage

Bug triage is a very useful contribution as well. You can review the issues on 0xACAB or in the Debian BTS for Monkeysign. What needs to be done is, for every issue:

  • try to reproduce the bug, if it is not reproducible, tag it with unreproducible
  • if information is missing, tag it with moreinfo
  • if a patch is provided, tag it with patch and test it
  • if the patch is incomplete, tag it with help (this is often the case when unit tests are missing)
  • if the patch is not working, remove the patch tag
  • if the patch gets merged into the git repository, tag it with pending
  • if the feature request is not within the scope of the project or should be refused for other reasons, use the wontfix tag and close the bug (with the close command or by CC’ing NNNN-done@bugs.debian.org)
  • feature requests should have a wishlist severity

Those directives apply mostly to the Debian BTS, but some tags are also useful in the 0xACAB site. See also the more complete directives on how to use the Debian BTS.

Patches

Patches can be submitted through merge requests on the Gitlab site.

If you prefer old school, offline email systems, you can also use the Debian BTS, as described above, or send patches to the mailing list for discussion.

Unit tests

Unit tests should be ran before sending patches. They can be ran with monkeysign --test (starting from Monkeysign 2.1.4, previously it was ./test.py and only from the source tree).

The tests expect a unicode locale, so if you do not have that configured already, do set one like this:

export LANG=C.UTF-8
monkeysign --test

It is possible that some keys used in the tests expire. The built-in keys do not have specific expiry dates, but some keys are provided to test some corner cases and those keys may have new expiration dates.

To renew the keys, try:

mkdir ~/.gpg-tmp
chmod 700 ~/.gpg-tmp
gpg --homedir ~/.gpg-tmp --import 7B75921E.asc
gpg --homedir ~/.gpg-tmp --refresh-keys 8DC901CE64146C048AD50FBB792152527B75921E
gpg --homedir ~/.gpg-tmp --export-options export-minimal --armor --export 8DC901CE64146C048AD50FBB792152527B75921E > 7B75921E.asc

It is also possible the key is just expired and there is no replacement. In this case the solution is to try and find a similar test case and replace the key, or simply disable that test.

Debian packaging

The Debian package requires backports of dh-python to operate properly, otherwise you will get errors like Debian BTS #839687:

LookupError: setuptools-scm was unable to detect version for '/tmp/buildd-...'.

A workaround is to hardcode the version with:

SETUPTOOLS_SCM_PRETEND_VERSION=x.y.z

Release process

  1. make sure tests pass:

    ./scripts/monkeysign --test
    
  2. create release notes with:

    git-dch
    dch -D unstable
    
  3. commit the results:

    git commit -m"prepare new release" -a
    
  4. create a signed and annotated tag:

    git tag -s x.y.z
    
  5. build and test Debian package:

    git-buildpackage
    dpkg -i ../monkeysign_*.deb
    monkeysign --version
    monkeysign --test
    monkeyscan
    
  6. build and test Python “wheel”:

    dpkg --remove monkeysign
    python setup.py bdist_wheel
    pip install dist/*.whl
    monkeysign --version
    monkeysign --test
    monkeyscan
    pip uninstall monkeysign
    
  7. push commits and tags to the git repository:

    git push
    git push --tags
    
  8. publish Python “wheel” on PyPI:

    twine upload dist/*
    
  9. upload Debian package:

    dput ../monkeysign*.changes
    
  10. add announcement on website and mailing list: monkeysphere@lists.riseup.net

  11. on 0xACAB: close the current milestone, create the next one and edit the release notes on the tag