Skip to content

Latest commit

 

History

History
144 lines (118 loc) · 6.2 KB

CONTRIBUTING.md

File metadata and controls

144 lines (118 loc) · 6.2 KB
Raw

How to Contribute to fscrypt

We'd love to accept your patches and contributions to this project. There are just a few small guidelines we ask you to follow.

Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution, this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.

Reporting an Issue, Discussing Design, or Asking a Question

IMPORTANT: Any significant security issues should NOT be reported in the public issue tracker. Practice responsible disclosure by emailing joerichey@google.com and tyhicks@canonical.com directly.

Any bugs, problems, or design discussion relating to fscrypt should be raised in the Github Issue Tracker.

When reporting an issue or problem, be sure to give as much information as possible. Also, make sure you are running the fscrypt and pam_fscrypt.so built from the current master branch.

If reporting an issue around the fscrypt command-line tool, post the relevant output from fscrypt, running with the --verbose flag. For the pam_fscrypt module, use the debug option with the module and post the relevant parts of the syslog (usually at /var/log/syslog).

Be sure to correctly tag your issue. The usage for the tags is as follows:

  • bug - General problems with the program's behavior
    • The program crashes or hangs
    • Directories cannot be locked/unlocked
    • Metadata corruption
    • Data loss/corruption
  • documentation
    • Typos or unclear explanations in README.md or man pages.
    • Outdated example output
    • Unclear or ambiguous error messages
  • enhancement - Things you want in fscrypt
  • question - You don't know how something works with fscrypt
    • This usally turns into a documentation issue.
  • testing - Strange test failures or missing tests

Submitting a Change to fscrypt

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

On every pull request, Travis CI runs unit tests, integration tests, code formatters, and linters. To pass these checks you should make sure that in your submission:

  • make properly builds fscrypt and pam_fscrypt.so.
  • All tests, including integration tests (see below), should pass.
  • make format has been run.
  • If you made any changes to files ending in .proto, the corresponding .pb.go files should be regenerated with make gen.
  • Any issues found by make lint have been addressed.
  • If any dependancies have changed, Gopkg.toml should be updated and dep ensure should be run.
  • make coverage.out can be used to generate a coverage report for all of the tests, but isn't required for submission (ideally most code would be tested, we are far from that ideal).

Essentially, if you run:

make test-setup
make all
make test-teardown
dep ensure

and everything succeeds, and no files are changed, you're good to submit.

The Makefile should automatically download and build whatever it needs. The only exceptions to this rule are:

  • make format requires clang-format.
  • make test-setup requires e2fsprogs version 1.43 or later (or any patched version that supports -O encrypt).

Running Integration Tests

Running make test will build each package and run the unit tests, but will skip the integration tests. To run the integration tests, you will need a filesystem that supports encryption. If you already have some empty filesystem at /foo/bar, just run:

make test MOUNT=/foo/bar

Otherwise, you can use the make test-setup/make test-teardown commands to create/destory a test filesystem for running integration tests. Note that these commands require sudo to mount/unmount the test filesystem. The fake filesystem generated by these commands will automatically be detected by make test, so running make test-setup then make test will run all the integration tests.

Changing dependencies

fscrypt vendors all of it's dependancies using dep. If you add or remove a dependency, be sure to update Gopkg.toml and run dep ensure.

Also, when adding a dependancy, the license of the package must be compatible with Apache 2.0. See the FSF's article for more information. This (unfortunately) means we cannot use external packages under the GPL or LGPL. We also cannot use packages with missing, misleading, or joke licenses (e.g. Unlicense, WTFPL, CC0).

Build System Details

Under the hood, the Makefile uses many go tools to generate, format, and lint your code.

make gen:

  • Downloads protoc to compile the .proto files.
  • Turns each .proto file into a matching .pb.go file using protoc-gen-go (built from source in vendor/).

make format runs:

make lint runs: