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 installedpython --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 theclose
command or by CC’ingNNNN-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¶
make sure tests pass:
./scripts/monkeysign --test
create release notes with:
git-dch dch -D unstable
commit the results:
git commit -m"prepare new release" -a
create a signed and annotated tag:
git tag -s x.y.z
build and test Debian package:
git-buildpackage dpkg -i ../monkeysign_*.deb monkeysign --version monkeysign --test monkeyscan
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
push commits and tags to the git repository:
git push git push --tags
publish Python “wheel” on PyPI:
twine upload dist/*
upload Debian package:
dput ../monkeysign*.changes
add announcement on website and mailing list: monkeysphere@lists.riseup.net
on 0xACAB: close the current milestone, create the next one and edit the release notes on the tag