Skip to content

Latest commit

 

History

History
184 lines (137 loc) · 7.52 KB

CONTRIBUTING.md

File metadata and controls

184 lines (137 loc) · 7.52 KB

Contributing to Ockam

Discuss Ockam

Thank you for taking the time to contribute! ❤️ ❤️ ❤️

Ask a question

If you have a question about how Ockam works or how to use it, please join the Ockam Slack to discuss with the Ockam team and community.

Report an issue or a bug

If you’ve found a bug, please create an issue on Github. In the issue description, please include:

  • details on what you were expecting to happen
  • what actually happened
  • simple steps to reproduce what you observed ... with any code examples, if possible.
  • details about the environment in which you were running ockam

Share an idea for a new feature

If you have a new idea about how Ockam can be more useful, please create a feature request as a Github issue. Explain the feature in detail, why it would be useful and how it will impact the Ockam codebase and community.

Contribute code

Build environments

The primary way to build Ockam code is by using the included ./build bash script. This script requires recent versions of Bash and Docker (or Docker Toolbox) installed on your development machine.

Alternatively, if you have Vagrant and Virtualbox installed on your development machine, you can create a Debian virtual machine that includes Docker and Bash. The Vagrantfile to create this virtual machine is included; just run:

vagrant up && vagrant ssh

to work inside the Debian virtual machine.

Building

./build uses Docker's multistage builds to create several tool images that always run the build in a predictable, pinned environment and deliver reproducible builds.

To run a full build, run:

./build

This will download any dependencies to /vendor and create /.build, placing compiled binaries in it.

On OSX or Linux you can also run ./build install to place your operating system-specific ockam binary in the system path.

You can then run:

ockam --version

To see verbose output for what the build script is doing, prefix TRACE=1 before any build command. For example:

TRACE=1 ./build

For more options see ./build help.

Lint

To run code linters, run:

./build lint

By default this will run all linters (namely, eclint, commitlint, shellcheck, and gometalinter).

For more options see ./build help lint

Test

To run tests and display test coverage, run:

./build test

Project conventions

Spacing and indentation

Our spacing conventions are specified in our editorconfig file and are enforced by eclint during builds. Any files that do not comply will cause the build to fail. The easiest way to follow the conventions is to use an editorconfig plugin for your code editor, most popular editors have one.

Code format

All Go code must be formatted using gofmt. This is enforced by gometalinter during builds. Any files that do not comply will cause the build to fail.

Commit messages

All commit messages must follow Conventional Commits v1.0.0-beta.2. This is enforced using commitlint during build. The exact rules that are enforced are specified in the commitlint.config.js.

Allowed, type values:

  • build: Changes that affect the build system or external dependencies
  • ci: Changes to our CI configuration files and scripts
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests

In addition, commit messages should be described in imperative mood, with the first word in lowercase and the total length of the first line being no longer than 50 characters.

Git workflow

We try to avoid noisy merge commits as much as possible and follow a rebase workflow against our "develop" branch, so please ensure that your pull requests can be rebased onto this branch. Also, see the section below regarding pull requests.

Signed commits

We only include GPG Signed Commits. All commits included in a pull request must be signed with your GPG key, and your public key must be published somewhere we can easily verify, preferably on Keybase.

In addition, we recommend that you don't store your private key on your development machine. Instead, use hardware-based key storage like Yubikey or Kryptonite.

Error handling

When dealing with errors returned within the code:

  • Import github.com/pkg/errors
  • When creating a new error use errors.New("error message")
  • When dealing with an external error, that did not originate in Ockam's code, use errors.WithStack(err) to add a stack trace to the error.
  • always return errors and don't ignore them
  • when printing errors, use fmt.Printf("%+v", err) to display the stack trace.
  • never call panic()

Effective Go

Use Go programming best practices defined in Effective Go

Send a pull request

When creating a pull request:

  • Create a feature/bugfix branch from ockam-network/ockam’s develop branch.
  • Add your changes to this branch.
  • Send the pull request from your feature/bugfix branch. Don't send a pull from your master branch.
  • Send the pull request against ockam-network/ockam’s develop branch.
  • Make sure that there are no conflicts with develop and the code in your pull request can be rebased.
  • Make sure all code convention described above are followed. Many of these are enforced by linter tools that are called when you invoke ./build.
  • Makes sure the build succeeds ./build with no linter warnings or test failures.

Code of conduct

All Ockam community interactions follow our Code of Conduct. Please be polite and respectful to all.

Thank you! 🏆 🎉 🎊

— Ockam Team