--- /dev/null
+How to Contribute to the libcgroup Project
+===============================================================================
+https://github.com/libcgroup/libcgroup
+
+This document outlines the steps to help you contribute to the libcgroup project.
+As with the libcgroup code itself, the process is a work in progress.
+Improvements and suggestions are welcome and encouraged.
+
+## Interacting with the Community
+
+> "When you are kind to others, it not only changes you, it changes the
+> world." - Harold Kushner
+
+The libcgroup project strives to be an inclusive and welcoming place.
+If you interact with the libcgroup project, we request that you treat others
+with dignity and respect. Failure to do so will result in a warning. In
+extreme cases, we reserve the right to block the individual from the project.
+
+Examples of inappropriate behavior includes: profane, abusive, or prejudicial
+language directed at another person, vandalism (e.g. GitHub issue/PR "litter"),
+or spam.
+
+## Test Your Code Using Existing Tests
+
+The libcgroup project utilizes unit and functional tests. These tests must
+successfully pass prior to a commit being merged.
+
+You can run both the unit and functional tests with the following command:
+
+ # make check
+
+You can invoke only the unit tests with the following commands:
+
+ # cd tests/gunit
+ # make check
+
+If there are unit test failures, running the unit tests outside of the
+automake framework will provide more information.
+
+ # cd tests/gunit
+ # ./gtest
+
+You can invoke only the functional tests with the following commands:
+
+ # cd tests/ftests
+ # make check
+
+Note that the functional tests can be run within a container or directly on
+your system. For the containerized tests, libcgroup utilizes LXC/LXD
+containers. If your system or distro doesn't support LXC/LXD, you can
+utilize the continuous integration infrastructure to test your changes. A
+successful continuous integration run is required for each pull request.
+
+Many tests can also be run outside of a container. Use caution with these
+tests though, as they will modify your host's cgroup hierarchy. This could
+significantly and negatively affect your system.
+
+We encourage utilizing a VM for libcgroup development work. The continuous
+integration suite utilizes the latest Ubuntu LTS.
+
+To run the containerized tests only:
+
+ # cd tests/ftests
+ # ./ftests.sh
+
+To run the non-containerized tests only:
+
+ # cd tests/ftests
+ # ./ftests-nocontainer.sh
+
+After the run is complete, the ftests.sh.log and ftests-nocontainer.sh.log
+contain the full debug log for each run.
+
+## Add New Tests for New Functionality
+
+The libcgroup project utilizes automated tests, code coverage, and continuous
+integration to maintain a high level of code quality. Any pull requests that
+add functionality or significantly change existing code should include
+additional tests to verify the proper operation of the proposed changes. Note
+that functional tests are preferred over unit tests.
+
+The continuous integration tools run the automated tests and automatically
+gather code coverage numbers. Pull requests that cause the code coverage
+numbers to decrease are strongly discouraged.
+
+## Explain Your Work
+
+At the top of every patch you should include a description of the problem you
+are trying to solve, how you solved it, and why you chose the solution you
+implemented. If you are submitting a bug fix, it is also incredibly helpful
+if you can describe/include a reproducer for the problem in the description as
+well as instructions on how to test for the bug and verify that it has been
+fixed.
+
+## Sign Your Work
+
+The sign-off is a simple line at the end of the patch description, which
+certifies that you wrote it or otherwise have the right to pass it on as an
+open-source patch. The "Developer's Certificate of Origin" pledge is taken
+from the Linux Kernel and the rules are pretty simple:
+
+ 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 the bottom of your patch description, with
+your real name, saying:
+
+ Signed-off-by: Random J Developer <random@developer.example.org>
+
+You can add this to your commit description in `git` with `git commit -s`
+
+## Submitting Patches
+
+libcgroup was initially hosted on Sourceforge and at that time only accepted
+patches via the mailing list. In 2018, libcgroup was moved to github and now
+accepts patches via email or github pull request. Over time the libcgroup
+project will likely fully transition to gitub pull requests and issues.
+
+### Post Your Patches Upstream
+
+The sections below explain how to contribute via either method. Please read
+each step and perform all steps that apply to your chosen contribution method.
+
+### Submitting via Email
+
+Depending on how you decided to work with the libcgroup code base and what
+tools you are using there are different ways to generate your patch(es).
+However, regardless of what tools you use, you should always generate your
+patches using the "unified" diff/patch format and the patches should always
+apply to the libcgroup source tree using the following command from the top
+directory of the libcgroup sources:
+
+ # patch -p1 < changes.patch
+
+If you are not using git, stacked git (stgit), or some other tool which can
+generate patch files for you automatically, you may find the following command
+helpful in generating patches, where "libcgroup.orig/" is the unmodified
+source code directory and "libcgroup/" is the source code directory with your
+changes:
+
+ # diff -purN libcgroup.orig/ libcgroup/
+
+When in doubt please generate your patch and try applying it to an unmodified
+copy of the libcgroup sources; if it fails for you, it will fail for the rest
+of us.
+
+Finally, you will need to email your patches to the mailing list so they can
+be reviewed and potentially merged into the main libcgroup repository. When
+sending patches to the mailing list it is important to send your email in text
+form, no HTML mail please, and ensure that your email client does not mangle
+your patches. It should be possible to save your raw email to disk and apply
+it directly to the libcgroup source code; if that fails then you likely have
+a problem with your email client. When in doubt try a test first by sending
+yourself an email with your patch and attempting to apply the emailed patch to
+the libcgrup repository; if it fails for you, it will fail for the rest of
+us trying to test your patch and include it in the main libcgroup repository.
+
+### Submitting via GitHub Pull Requests
+
+See [this guide](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) if you've never done this before.
+
projects / thirdparty / libcgroup.git / commitdiff
