Contributing to python-ldap

Thank you for your interest in python-ldap! If you’d like to contribute (be it code, documentation, maintenance effort, or anything else), this guide is for you.

Communication

Always keep in mind that python-ldap is developed and maintained by volunteers. We’re happy to share our work, and to work with you to make the library better, but (until you pay someone), there’s obligation to provide assistance.

So, keep it friendly, respectful, and supportive!

Mailing list

Discussion about the use and future of python-ldap occurs in the python-ldap@python.org mailing list.

It’s also the channel to use if documentation (including this guide) is not clear to you. Do try searching around before you ask on the list, though!

You can subscribe or unsubscribe to this list or browse the list archive.

Issues

Please report bugs, missing features and other issues to the bug tracker at GitHub. You will need a GitHub account for that.

If you prefer not to open a GitHub account, you’re always welcome to use the mailing list.

Security Contact

If you found a security issue that should not be discussed publicly, please e-mail the maintainer at pviktori@redhat.com. If required, write to coordinate a more secure channel.

All other communication should be public.

Contributing code

If you’re used to open-source Python development with Git, here’s the gist:

  • git clone https://github.com/python-ldap/python-ldap
  • Use GitHub for the bug tracker and pull requests.
  • Run tests with tox; ignore Python interpreters you don’t have locally.

Or, if you prefer to avoid closed-source services:

  • git clone https://pagure.io/python-ldap
  • Send bug reports and patches to the mailing list.
  • Run tests with tox; ignore Python interpreters you don’t have locally.
  • Read the documentation directly at Read the Docs.

If you’re new to some aspect of the project, you’re welcome to use (or adapt) our sample workflow.

Additional tests and scripts

We use several specialized tools for debugging and maintenance.

Make targets

Make targets currently use the python3 executable. Specify a different one using, for example:

make PYTHON=/usr/local/bin/python

Notable targets are:

make autoformat

Automatically re-formats C and Python code to conform to Python style guides (PEP 7 and PEP 8). Note that no backups are made – please commit any other changes before using this target.

Requires the indent program and the black Python module.

make lcov lcov-open
Generate and view test coverage for C code. Requires LCOV.
make scan-build
Run static analysis. Requires clang.
make valgrind

Run Valgrind to check for memory leaks. Requires valgrind and a Python suppression file, which you can specify as PYTHON_SUPP, e.g.:

make valgrind PYTHON_SUPP=/your/path/to/valgrind-python.supp

The suppression file is Misc/valgrind-python.supp in the Python source distribution, and it’s frequently packaged together with Python development headers.

Reference leak tests

Reference leak tests require a pydebug build of CPython and pytest with pytest-leaks plugin. A pydebug build has a global reference counter, which keeps track of all reference increments and decrements. The leak plugin runs each test multiple times and checks if the reference count increases.

Download and compile the pydebug build:

$ curl -O https://www.python.org/ftp/python/3.6.3/Python-3.6.3.tar.xz
$ tar xJf Python-3.6.3.tar.xz
$ cd Python-3.6.3
$ ./configure --with-pydebug
$ make

Create a virtual environment with the pydebug build:

$ ./python -m venv /tmp/refleak
$ /tmp/refleak/bin/pip install pytest pytest-leaks

Run reference leak tests:

$ cd path/to/python-ldap
$ /tmp/refleak/bin/pip install --upgrade .
$ /tmp/refleak/bin/pytest -v -R:

Run /tmp/refleak/bin/pip install --upgrade . every time a file outside of Tests/ is modified.

Instructions for core committers

If you have the authority (and responsibility) of merging changes from others, remember:

  • All code changes need to be reviewed by someone other than the author.
  • Tests must always pass. New features without tests shall not pass review.
  • Make sure commit messages don’t use GitHub-specific link syntax. Use the full URL, e.g. https://github.com/python-ldap/python-ldap/issues/50 instead of #20.
    • Exception: it’s fine to use the short form in the summary line of a merge commit, if the full URL appears later.
    • It’s OK to use shortcuts in GitHub discussions, where they are not hashed into immutable history.
  • Make a merge commit if the contribution contains several well-isolated separate commits with good descriptions. Use squash-and-merge (or fast-forward from a command line) for all other cases.
  • It’s OK to push small changes into a pull request. If you do this, document what you have done (so the contributor can learn for the future), and get their ACK before merging.
  • When squashing, do edit commit messages to add references to the pull request and relevant discussions/issues, and to conform to Git best practices.
    • Consider making the summary line suitable for the CHANGES document, and starting it with a prefix like Lib: or Tests:.
  • Push to Pagure as well.

If you have good reason to break the “rules”, go ahead and break them, but mention why.

Instructions for release managers

If you are tasked with releasing python-ldap, remember to:

  • Bump all instances of the version number.
  • Go through all changes since last version, and add them to CHANGES.
  • Run Additional tests and scripts as appropriate, fix any regressions.
  • Change the release date in CHANGES.
  • Update __version__ tags where appropriate (each module ldap, ldif, ldapurl, slapdtest has its own copy).
  • Merge all that (using pull requests).
  • Run python setup.py sdist, and smoke-test the resulting package (install in a clean virtual environment, import ldap).
  • Create GPG-signed Git tag: git tag -s python-ldap-{version}. Push it to GitHub and Pagure.
  • Release the sdist on PyPI.
  • Announce the release on the mailing list. Mention the Git hash.
  • Add the release’s log from CHANGES on the GitHub release page.
  • Check that python-ldap.org shows the latest version; if not, adjust things at readthedocs.org