CONTRIBUTING

Contributing to this Project
============================

## License

This project is licensed under the terms and conditions of the 3-Clause BSD
[LICENSE](LICENSE).  By contributing to this project, you agree that you are
providing your contribution under the terms and conditions of that license.


## Patches

We accept patches to this project as pull requests on GitHub.  When submitting
patches, please keep each patch self-contained and as small as possible.  Please
address one topic per patch series.  Intermediate patches must build without
errors (with DEVBUILD=ON) and not introduce test fails.  Please describe what
each patch is doing in its commit message.

If you are contributing a patch series that addresses a GitHub Issue, the last
patch in the series should have 'fixes #<issue>' in its commit-message.

If the patch series addresses a bug that is not tracked, please provide a
detailed description of the issue in the commit-message, ideally with a
description of the 'before' and 'after' behavior.

The patch series should contain regression tests either as PTT tests or as
ptunit tests.  Please make sure that all tests are passing. This may require
re-ordering patches to introduce the regression test after the issue was fixed.

If the patch series adds a new feature, please make sure to add documentation.
Prior to submitting this type of contribution, it may be a good idea to first
discuss the feature as a GitHub issue or via email before implementing it.

This project is using the Linux coding style.


## Sign Your Patch

Please use the sign-off line at the end of each patch. Your signature
certifies that you wrote the patch or otherwise have the right to pass
it on as an open-source patch. The rules are pretty simple: if you can
certify the below (from
[developercertificate.org](http://developercertificate.org/)):

```
Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.
```

Then you just add a line to every git commit message:

    Signed-off-by: Joe Smith <joe.smith@email.com>

Use your real name (sorry, no pseudonyms or anonymous contributions.)

If you set your `user.name` and `user.email` git configs, you can sign your
commit automatically with `git commit -s`.


## Reporting Issues

If you want to report an issue or bug, please report them via the GitHub Issues
tracker.

When reporting a bug, please provide the steps to reproduce it with the ptdump
and ptxed tools contained in the tree.  Please include the command-line that was
used and the exact error message.  You may also attach a trace file and the
binaries necessary for reproducing the issue or write a small PTT test to
demonstrate the issue.

When providing trace snippets, please provide a few extra packets of context.

Please also provide the processor family and model on which the trace was
recorded and the version of the decoder that was used to decode the trace.