Development

Development for libkmip is open to all contributors. Use the information provided here to inform your contributions and help the project maintainers review and accept your work.

Getting Started

File a new issue on the project issue tracker on GitHub describing the work you intend on doing. This is especially recommended for any sizable contributions, like adding support for a new KMIP operation or object type. Provide as much information on your feature request as possible, using information from the KMIP specifications or existing feature support in libkmip where applicable.

The issue number for your new issue should be included at the end of the commit message of each patch related to that issue.

If you simply want to request a new feature but do not intend on working on it, file your issue as normal and the project maintainers will triage it for future work.

Writing Code

New code should be written in its own git branch, ideally branched from HEAD on master. If other commits are merged into master after your branch was created, be sure to rebase your work on the current state of master before submitting a pull request to GitHub.

New code should generally follow the style used in the surrounding libkmip codebase.

Writing Documentation

Like new code, new documentation should be written in its own git branch. All libkmip documentation is written in RST format and managed using sphinx. It can be found under docs/source.

If you are interested in contributing to the project documentation, install the project documentation requirements:

$ pip install -r doc-requirements.txt

To build the documentation, navigate into the docs directory and run:

$ make html

This will build the libkmip documentation as HTML and place it under the new docs/build/html directory. View it using your preferred web browser.

Commit Messages

Commit messages should include a single line title (75 characters max) followed by a blank line and a description of the change, including feature details, testing and documentation updates, feature limitations, known issues, etc.

The issue number for the issue associated with the commit should be included at the end of the commit message, if it exists. If the commit is the final one for a specific issue, use Closes #XXX or Fixes #XXX to link the issue and close it simultaneously.

Bug Fixes

If you have found a bug in libkmip, file a new issue and use the title format Bug: <brief description here>. In the body of the issue please provide as much information as you can, including platform, compiler version, dependency version, and any stacktraces or error information produced by libkmip related to the bug. See What to put in your bug report for a breakdown of bug reporting best practices.

If you are working on a bug fix for a bug in master, follow the general guidelines above for branching and code development (see Writing Code).

If you are working on a bug fix for an older version of libkmip, your branch should be based on the latest commit of the repository branch for the version of libkmip the bug applies to (e.g., branch release-0.1.0 for libkmip 0.1). The pull request for your bug fix should also target the version branch in question. If appliable, it will be pulled forward to newer versions of libkmip, up to and including master.

Running Tests

libkmip comes with its own testing application that primarily covers the encoding/decoding functionality of the library. It is built with the default make target and can be run locally by invoking the tests binary:

$ cd libkmip
$ make
$ ./tests