|
Packit |
95bb47 |
# Contributing to the Persistent Memory Development Kit
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
Here you'll find instructions on how to contribute to the
|
|
Packit |
95bb47 |
Persistent Memory Development Kit.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
Your contributions are most welcome! You'll find it is best to begin
|
|
Packit |
95bb47 |
with a conversation about your changes, rather than just writing a bunch
|
|
Packit |
95bb47 |
of code and contributing it out of the blue.
|
|
Packit |
95bb47 |
There are several good ways to suggest new features, offer to add a feature,
|
|
Packit |
95bb47 |
or just begin a dialog about the Persistent Memory Development Kit:
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
* Open an issue in our [GitHub Issues Database](https://github.com/pmem/issues/issues)
|
|
Packit |
95bb47 |
* Suggest a feature, ask a question, start a discussion, etc. in our [pmem Google group](http://groups.google.com/group/pmem)
|
|
Packit |
95bb47 |
* Chat with members of the PMDK team real-time on the **#pmem** IRC channel on [OFTC](http://www.oftc.net)
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
**NOTE: If you do decide to implement code changes and contribute them,
|
|
Packit |
95bb47 |
please make sure you agree your contribution can be made available
|
|
Packit |
95bb47 |
under the [BSD-style License used for the Persistent Memory Development Kit](https://github.com/pmem/pmdk/blob/master/LICENSE).**
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
**NOTE: Submitting your changes also means that you certify the following:**
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
Developer's Certificate of Origin 1.1
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
By making a contribution to this project, I certify that:
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
(a) The contribution was created in whole or in part by me and I
|
|
Packit |
95bb47 |
have the right to submit it under the open source license
|
|
Packit |
95bb47 |
indicated in the file; or
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
(b) The contribution is based upon previous work that, to the best
|
|
Packit |
95bb47 |
of my knowledge, is covered under an appropriate open source
|
|
Packit |
95bb47 |
license and I have the right under that license to submit that
|
|
Packit |
95bb47 |
work with modifications, whether created in whole or in part
|
|
Packit |
95bb47 |
by me, under the same open source license (unless I am
|
|
Packit |
95bb47 |
permitted to submit under a different license), as indicated
|
|
Packit |
95bb47 |
in the file; or
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
(c) The contribution was provided directly to me by some other
|
|
Packit |
95bb47 |
person who certified (a), (b) or (c) and I have not modified
|
|
Packit |
95bb47 |
it.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
(d) I understand and agree that this project and the contribution
|
|
Packit |
95bb47 |
are public and that a record of the contribution (including all
|
|
Packit |
95bb47 |
personal information I submit with it, including my sign-off) is
|
|
Packit |
95bb47 |
maintained indefinitely and may be redistributed consistent with
|
|
Packit |
95bb47 |
this project or the open source license(s) involved.
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
In case of any doubt, the gatekeeper may ask you to certify the above in writing,
|
|
Packit |
95bb47 |
i.e. via email or by including a `Signed-off-by:` line at the bottom
|
|
Packit |
95bb47 |
of your commit comments.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
To improve tracking of who is the author of a contribution, we kindly ask you
|
|
Packit |
95bb47 |
to use your real name (not an alias) when committing your changes to the
|
|
Packit |
95bb47 |
Persistent Memory Development Kit:
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
Author: Random J Developer <random@developer.example.org>
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
### Code Contributions
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
Please feel free to use the forums mentioned above to ask
|
|
Packit |
95bb47 |
for comments & questions on your code before submitting
|
|
Packit |
95bb47 |
a pull request. The Persistent Memory Development Kit project uses the common
|
|
Packit |
95bb47 |
*fork and merge* workflow used by most GitHub-hosted projects.
|
|
Packit |
95bb47 |
The [Git Workflow blog article](http://pmem.io/2014/09/09/git-workflow.html)
|
|
Packit |
95bb47 |
describes our workflow in more detail.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
#### Linux/FreeBSD
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
Before contributing please remember to run:
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
$ make cstyle
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
This will check all C/C++ files in the tree for style issues. To check C++
|
|
Packit |
95bb47 |
files you have to have clang-format version 3.8+, otherwise they will be
|
|
Packit |
95bb47 |
skipped. If you want to run this target automatically at build time, you can
|
|
Packit |
95bb47 |
pass CSTYLEON=1 to make. If you want cstyle to be run, but not fail the build,
|
|
Packit |
95bb47 |
pass CSTYLEON=2 to make.
|
|
Packit |
95bb47 |
There is also a target for automatic C++ code formatting, to do this run:
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
$ make format
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
There are cases, when you might have several clang-format-X.Y binaries and either
|
|
Packit |
95bb47 |
no clang-format or it pointing to an older version. In such case run:
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
$ make CLANG_FORMAT=/path/to/clang-format cstyle|format
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
#### Windows
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
On Windows to check the code for style issues, please run:
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
$ pmdk\utils\CSTYLE.ps1
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
To check or format C++ files, you may use a standalone Visual Studio plugin
|
|
Packit |
95bb47 |
for clang-format. The plugin installer can be downloaded from
|
|
Packit |
95bb47 |
[LLVM Builds](http://llvm.org/builds) page.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
If you are actively working on an PMDK feature, please let other
|
|
Packit |
95bb47 |
developers know by [creating an issue](https://github.com/pmem/issues/issues).
|
|
Packit |
95bb47 |
Use the label `Type: Feature` and assign it to yourself (due to the way
|
|
Packit |
95bb47 |
GitHub permissions work, you may need to ask a team member to assign it to you).
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
### Bug Reports
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
Bugs for the PMDK project are tracked in our
|
|
Packit |
95bb47 |
[GitHub Issues Database](https://github.com/pmem/issues/issues).
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
When creating a bug report issue, please provide the following information:
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
#### PMDK version
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
Put the release name of the version of PMDK running when the
|
|
Packit |
95bb47 |
bug was discovered in a bug comment. If you saw this bug in multiple PMDK
|
|
Packit |
95bb47 |
versions, please put at least the most recent version and list the others
|
|
Packit |
95bb47 |
if necessary.
|
|
Packit |
95bb47 |
- Stable release names are in the form `#.#` (where `#` represents
|
|
Packit |
95bb47 |
an integer); for example `0.3`.
|
|
Packit |
95bb47 |
- Release names from working versions look like `#.#+b#` (adding a build #)
|
|
Packit |
95bb47 |
or `#.#-rc#` (adding a release candidate number)
|
|
Packit |
95bb47 |
If PMDK was built from source, the version number can be retrieved
|
|
Packit |
95bb47 |
from git using this command: `git describe`
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
For binary PMDK releases, use the entire package name.
|
|
Packit |
95bb47 |
For RPMs, use `rpm -q pmdk` to display the name.
|
|
Packit |
95bb47 |
For Deb packages, run `dpkg-query -W pmdk` and use the
|
|
Packit |
95bb47 |
second (version) string.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
#### Milestone field
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
Optionally, assign the milestone the issue needs to be fixed before.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
#### Type: Bug label
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
Assign the `Type: Bug` label to the issue
|
|
Packit |
95bb47 |
(see [GitHub Help](https://help.github.com/articles/applying-labels-to-issues-and-pull-requests) for details).
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
#### Priority label
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
Optionally, assign one of the Priority labels (P1, P2, ...).
|
|
Packit |
95bb47 |
The Priority attribute describes the urgency to resolve a defect
|
|
Packit |
95bb47 |
and establishes the time frame for providing a verified resolution.
|
|
Packit |
95bb47 |
These Priority labels are defined as:
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
* **P1**: Showstopper bug, requiring resolution before the next release of the library.
|
|
Packit |
95bb47 |
* **P2**: High-priority bug, requiring resolution although it may be decided that the bug does not prevent the next release of the library.
|
|
Packit |
95bb47 |
* **P3**: Medium-priority bug. The expectation is that the bug will be evaluated and a plan will be made for when the bug will be resolved.
|
|
Packit |
95bb47 |
* **P4**: Low-priority bug, the least urgent. Fixed as resources are available.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
Then describe the bug in the comment fields.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
#### Type: Feature label
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
Assign the `Type: Feature` label to the issue, then describe the feature request in comment fields.
|