projects / ceph.git / blame
| Commit | Line | Data |
|---|---|---|
| f67539c2 TL |
1 | Development |
| 2 | =========== | |
| 3 | Development for libkmip is open to all contributors. Use the information | |
| 4 | provided here to inform your contributions and help the project maintainers | |
| 5 | review and accept your work. | |
| 6 | ||
| 7 | Getting Started | |
| 8 | --------------- | |
| 9 | File a new issue on the project `issue tracker`_ on GitHub describing the | |
| 10 | work you intend on doing. This is especially recommended for any sizable | |
| 11 | contributions, like adding support for a new KMIP operation or object type. | |
| 12 | Provide as much information on your feature request as possible, using | |
| 13 | information from the KMIP specifications or existing feature support in | |
| 14 | libkmip where applicable. | |
| 15 | ||
| 16 | The issue number for your new issue should be included at the end of the | |
| 17 | commit message of each patch related to that issue. | |
| 18 | ||
| 19 | If you simply want to request a new feature but do not intend on working on | |
| 20 | it, file your issue as normal and the project maintainers will triage it for | |
| 21 | future work. | |
| 22 | ||
| 23 | .. _writing-code: | |
| 24 | ||
| 25 | Writing Code | |
| 26 | ------------ | |
| 27 | New code should be written in its own ``git`` branch, ideally branched from | |
| 28 | ``HEAD`` on ``master``. If other commits are merged into ``master`` after your | |
| 29 | branch was created, be sure to rebase your work on the current state of | |
| 30 | ``master`` before submitting a pull request to GitHub. | |
| 31 | ||
| 32 | New code should generally follow the style used in the surrounding libkmip | |
| 33 | codebase. | |
| 34 | ||
| 35 | .. _writing-docs: | |
| 36 | ||
| 37 | Writing Documentation | |
| 38 | --------------------- | |
| 39 | Like new code, new documentation should be written in its own ``git`` branch. | |
| 40 | All libkmip documentation is written in `RST`_ format and managed using | |
| 41 | ``sphinx``. It can be found under ``docs/source``. | |
| 42 | ||
| 43 | If you are interested in contributing to the project documentation, install | |
| 44 | the project documentation requirements: | |
| 45 | ||
| 46 | .. code:: console | |
| 47 | ||
| 48 | $ pip install -r doc-requirements.txt | |
| 49 | ||
| 50 | To build the documentation, navigate into the ``docs`` directory and run: | |
| 51 | ||
| 52 | .. code:: console | |
| 53 | ||
| 54 | $ make html | |
| 55 | ||
| 56 | This will build the libkmip documentation as HTML and place it under the new | |
| 57 | ``docs/build/html`` directory. View it using your preferred web browser. | |
| 58 | ||
| 59 | Commit Messages | |
| 60 | --------------- | |
| 61 | Commit messages should include a single line title (75 characters max) followed | |
| 62 | by a blank line and a description of the change, including feature details, | |
| 63 | testing and documentation updates, feature limitations, known issues, etc. | |
| 64 | ||
| 65 | The issue number for the issue associated with the commit should be included | |
| 66 | at the end of the commit message, if it exists. If the commit is the final one | |
| 67 | for a specific issue, use ``Closes #XXX`` or ``Fixes #XXX`` to link the issue | |
| 68 | and close it simultaneously. | |
| 69 | ||
| 70 | Bug Fixes | |
| 71 | --------- | |
| 72 | If you have found a bug in libkmip, file a new issue and use the title format | |
| 73 | ``Bug: <brief description here>``. In the body of the issue please provide as | |
| 74 | much information as you can, including platform, compiler version, dependency | |
| 75 | version, and any stacktraces or error information produced by libkmip related | |
| 76 | to the bug. See `What to put in your bug report`_ for a breakdown of bug | |
| 77 | reporting best practices. | |
| 78 | ||
| 79 | If you are working on a bug fix for a bug in ``master``, follow the general | |
| 80 | guidelines above for branching and code development (see :ref:`writing-code`). | |
| 81 | ||
| 82 | If you are working on a bug fix for an older version of libkmip, your branch | |
| 83 | should be based on the latest commit of the repository branch for the version | |
| 84 | of libkmip the bug applies to (e.g., branch ``release-0.1.0`` for libkmip 0.1). | |
| 85 | The pull request for your bug fix should also target the version branch in | |
| 86 | question. If appliable, it will be pulled forward to newer versions of libkmip, | |
| 87 | up to and including ``master``. | |
| 88 | ||
| 89 | .. running-tests: | |
| 90 | ||
| 91 | Running Tests | |
| 92 | ------------- | |
| 93 | libkmip comes with its own testing application that primarily covers the | |
| 94 | encoding/decoding functionality of the library. It is built with the default | |
| 95 | ``make`` target and can be run locally by invoking the ``tests`` binary: | |
| 96 | ||
| 97 | .. code-block:: console | |
| 98 | ||
| 99 | $ cd libkmip | |
| 100 | $ make | |
| 101 | $ ./tests | |
| 102 | ||
| 103 | .. _`issue tracker`: https://github.com/openkmip/libkmip/issues | |
| 104 | .. _`RST`: http://docutils.sourceforge.net/rst.html | |
| 105 | .. _`What to put in your bug report`: http://www.contribution-guide.org/#What-to-put-in-your-bug-report |