Contribution Guidelines

• 1: Contributor Overview
• 2: Design Documents
• 3: Development Environment
• 4: Testing Drycc
• 5: Submitting a Pull Request
• 6: Community
• 7: Triaging Issues
• 8: Conduct
• 9: Drycc Maintainers

1 - Contributor Overview

File Bugs & Enhancements

Find a bug? Want to see a new feature? Have a request for the maintainers? Open a GitHub issue in the applicable repository and we’ll get the conversation started.

Our official support channel is the Drycc #community Slack channel.

Don’t know what the applicable repository for an issue is? Open an issue in workflow or chat with a maintainer in the Drycc #community Slack channel and we’ll make sure it gets to the right place.

Additionally, take a look at the troubleshooting documentation for common issues.

Before opening a new issue, it’s helpful to search and see if anyone else has already reported the problem. You can search through a list of issues for all Drycc projects here.

Write Documentation

We are always looking to improve and expand our documentation. Most docs reside in the drycc/workflow repository. Simply fork the project, update docs, and send us a pull request.

Contribute Code

We are always looking for help improving the core platform, other workloads, tooling, and test coverage. Interested in contributing code? Let’s chat in the Drycc #community Slack channel. Make sure to check out issues tagged easy fix or help wanted.

When you’re ready to begin writing code, review Design Documents and get your Development Environment set up.

By contributing to any Drycc project you agree to its Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution.

Triage Issues

If you don’t have time to code, consider helping with triage. The community will thank you for saving them time by spending some of yours. See Triaging Issues for more info.

Share your Experience

Interact with the community on our user mailing list or live in our Drycc #community Slack channel, where you can chat with other Drycc Workflow users any time of day.

2 - Design Documents

Before submitting a pull request that will significantly alter the behavior of any Drycc component, such as a new feature or major refactoring, contributors should first open an issue representing a design document.

Goals

Design documents help ensure project contributors:

• Involve stakeholders as early as possible in a feature’s development
• Ensure code changes accomplish the original motivations and design goals
• Establish clear acceptance criteria for a feature or change
• Enforce test-driven design methodology and automated test coverage

Contents

Design document issues should be named Design Doc: <change description> and contain the following sections:

Goal

This section should briefly describe the proposed change and the motivations behind it. Tests will be written to ensure this design goal is met by the change.

This section should also reference a separate GitHub issue tracking the feature or change, which will typically be assigned to a release milestone.

Code Changes

This section should detail the code changes necessary to accomplish the change, as well as the proposed implementation. This should be as detailed as necessary to help reviewers understand the change.

Tests

All changes should be covered by automated tests, either unit or integration tests (ideally both). This section should detail how tests will be written to validate that the change accomplishes the design goals and doesn’t introduce any regressions.

If a change cannot be sufficiently covered by automated testing, the design should be reconsidered. If there is no test coverage whatsoever for an affected section of code, a separate issue should be filed to integrate automated testing with that section of the codebase.

The tests described here also form the acceptance criteria for the change, so that when it’s completed maintainers can merge the pull request after confirming the tests pass CI.

Approval

A design document follows the same merge approval review process as final pull requests do, and maintainers will take extra care to ensure that any stakeholders for the change are included in the discussion and review of the design document.

Once the design is accepted, the author can complete the change and submit a pull request for review. The pull request should close both the design document for the change as well as any issues that either track the issue or are closed as a result of the change.

See Submitting a Pull Request for more information on pull request and commit message formatting.

3 - Development Environment

In this guide, we walk you through the process of setting up a development environment that is suitable for hacking on most Drycc components.

We try to make it simple to hack on Drycc components. However, there are necessarily several moving pieces and some setup required. We welcome any suggestions for automating or simplifying this process.

If you’re just getting into the Drycc codebase, look for GitHub issues with the label easy-fix. These are more straightforward or low-risk issues and are a great way to become more familiar with Drycc.

Prerequisites

In order to successfully compile and test Drycc binaries and build Container images of Drycc components, the following are required:

• git
• Go 1.5 or later, with support for compiling to linux/amd64
• glide
• golint
• shellcheck
• Podman (in a non-Linux environment, you will additionally want [Podman Machine][machine])

For drycc/controller, in particular, you will also need:

• Python 2.7 or later (with pip)
• virtualenv (sudo pip install virtualenv)

In most cases, you should simply install according to the instructions. There are a few special cases, though. We cover these below.

Configuring Go

If your local workstation does not support the linux/amd64 target environment, you will have to install Go from source with cross-compile support for that environment. This is because some of the components are built on your local machine and then injected into a container.

Homebrew users can just install with cross compiling support:

$ brew install go --with-cc-common

It is also straightforward to build Go from source:

$ sudo su
$ curl -sSL https://golang.org/dl/go1.5.src.tar.gz | tar -v -C /usr/local -xz
$ cd /usr/local/go/src
$ # compile Go for our default platform first, then add cross-compile support
$ ./make.bash --no-clean
$ GOOS=linux GOARCH=amd64 ./make.bash --no-clean

Once you can compile to linux/amd64, you should be able to compile Drycc components as normal.

Fork the Repository

Once the prerequisites have been met, we can begin to work with Drycc components.

Begin at GitHub by forking whichever Drycc project you would like to contribute to, then clone that fork locally. Since Drycc is predominantly written in Go, the best place to put it is under $GOPATH/src/github.com/drycc/.

$ mkdir -p  $GOPATH/src/github.com/drycc
$ cd $GOPATH/src/github.com/drycc
$ git clone git@github.com:<username>/<component>.git
$ cd <component>

If you are going to be issuing pull requests to the upstream repository from which you forked, we suggest configuring Git such that you can easily rebase your code to the upstream repository’s main branch. There are various strategies for doing this, but the most common is to add an upstream remote:

$ git remote add upstream https://github.com/drycc/<component>.git

For the sake of simplicity, you may want to point an environment variable to your Drycc code - the directory containing one or more Drycc components:

$ export DRYCC=$GOPATH/src/github.com/drycc

Throughout the rest of this document, $DRYCC refers to that location.

Alternative: Forking with a Pushurl

A number of Drycc contributors prefer to pull directly from drycc/<component>, but push to <username>/<component>. If that workflow suits you better, you can set it up this way:

$ git clone git@github.com:drycc/<component>.git
$ cd drycc
$ git config remote.origin.pushurl git@github.com:<username>/<component>.git

In this setup, fetching and pulling code will work directly with the upstream repository, while pushing code will send changes to your fork. This makes it easy to stay up to date, but also make changes and then issue pull requests.

Make Your Changes

With your development environment set up and the code you wish to work on forked and cloned, you can begin making your changes.

Test Your Changes

Drycc components each include a comprehensive suite of automated tests, mostly written in Go. See testing for instructions on running the tests.

Deploying Your Changes

Although writing and executing tests are critical to ensuring code quality, most contributors will also want to deploy their changes to a live environment, whether to make use of those changes or to test them further. The remainder of this section documents the procedure for running officially released Drycc components in a development cluster and replacing any one of those with your customizations.

Running a Kubernetes Cluster for Development

To run a Kubernetes cluster locally or elsewhere to support your development activities, refer to Drycc installation instructions here.

Using a Development Registry

To facilitate deploying Container images containing your changes to your Kubernetes cluster, you will need to make use of a Container registry. This is a location to where you can push your custom-built images and from where your Kubernetes cluster can retrieve those same images.

If your development cluster runs locally (in Minikube, for instance), the most efficient and economical means of achieving this is to run a Container registry locally as a Container container.

To facilitate this, most Drycc components provide a make target to create such a registry:

$ make dev-registry

In a Linux environment, to begin using the registry:

export DRYCC_REGISTRY=<IP of the host machine>:5000

In non-Linux environments:

export DRYCC_REGISTRY=<IP of the drycc Container Machine VM>:5000

If your development cluster runs on a cloud provider such as Google Container Engine, a local registry such as the one above will not be accessible to your Kubernetes nodes. In such cases, a public registry such as [DockerHub][dh] or quay.io will suffice.

To use DockerHub for this purpose, for instance:

$ export DRYCC_REGISTRY="registry.drycc.cc"
$ export IMAGE_PREFIX=<your DockerHub username>

To use quay.io:

$ export DRYCC_REGISTRY=quay.io
$ export IMAGE_PREFIX=<your quay.io username>

Note the importance of the trailing slash.

Dev / Deployment Workflow

With a functioning Kubernetes cluster and the officially released Drycc components installed onto it, deployment and further testing of any Drycc component you have made changes to is facilitated by replacing the officially released component with a custom built image that contains your changes. Most Drycc components include Makefiles with targets specifically intended to facilitate this workflow with minimal friction.

In the general case, this workflow looks like this:

1. Update source code and commit your changes using git
2. Use make build to build a new Container image
3. Use make dev-release to generate Kubernetes manifest(s)
4. Use make deploy to restart the component using the updated manifest

This can be shortened to a one-liner using just the deploy target:

$ make deploy

Useful Commands

Once your customized Drycc component has been deployed, here are some helpful commands that will allow you to inspect your cluster and to troubleshoot, if necessary:

See All Drycc Pods

$ kubectl --namespace=drycc get pods

Describe a Pod

This is often useful for troubleshooting pods that are in pending or crashed states:

$ kubectl --namespace=drycc describe -f <pod name>

Tail Logs

$ kubectl --namespace=drycc logs -f <pod name>

Django Shell

Specific to drycc/controller

$ kubectl --namespace=drycc exec -it <pod name> -- python manage.py shell

Have commands other Drycc contributors might find useful? Send us a PR!

Pull Requests

Satisfied with your changes? Share them!

Please read Submitting a Pull Request. It contains a checklist of things you should do when proposing a change to any Drycc component.

4 - Testing Drycc

Each Drycc component includes its own suite of style checks, unit tests, and black-box type functional tests.

Integration tests verify the behavior of the Drycc components together as a system and are provided separately by the drycc/workflow-e2e project.

GitHub pull requests for all Drycc components are tested automatically by the Travis CI continuous integration system. Contributors should run the same tests locally before proposing any changes to the Drycc codebase.

Set Up the Environment

Successfully executing the unit and functional tests for any Drycc component requires that the Development Environment is set up first.

Run the Tests

The style checks, unit tests, and functional tests for each component can all be executed via make targets:

To execute style checks:

$ make test-style

To execute unit tests:

$ make test-unit

To execute functional tests:

$ make test-functional

To execute style checks, unit tests, and functional tests all in one shot:

$ make test

To execute integration tests, refer to drycc/workflow-e2e documentation.

5 - Submitting a Pull Request

Design Document

Before opening a pull request, ensure your change also references a design document if the contribution is substantial. For more information, see Design Documents.

Single Issue

It’s hard to reach agreement on the merit of a PR when it isn’t focused. When fixing an issue or implementing a new feature, resist the temptation to refactor nearby code or to fix that potential bug you noticed. Instead, open a separate issue or pull request. Keeping concerns separated allows pull requests to be tested, reviewed, and merged more quickly.

Squash and rebase the commit or commits in your pull request into logical units of work with git. Include tests and documentation changes in the same commit, so that a revert would remove all traces of the feature or fix.

Most pull requests will reference a GitHub issue. In the PR description - not in the commit itself - include a line such as “closes #1234”. The issue referenced will automatically be closed when your PR is merged.

Include Tests

If you significantly alter or add functionality to a component that impacts the broader Drycc Workflow PaaS, you should submit a complementary PR to modify or amend end-to-end integration tests. These integration tests can be found in the drycc/workflow-e2e repository.

See testing for more information.

Include Docs

Changes to any Drycc Workflow component that could affect a user’s experience also require a change or addition to the relevant documentation. For most Drycc components, this involves updating the component’s own documentation. In some cases where a component is tightly integrated into drycc/workflow, its documentation must also be updated.

Cross-repo commits

If a pull request is part of a larger piece of work involving one or more additional commits in other Workflow repositories, these commits can be referenced in the last PR to be submitted. The downstream e2e test job will then supply every referenced commit (derived from PR issue number supplied) to the test runner so it can source the necessary Container images for inclusion in the generated Workflow chart to be tested.

For example, consider paired commits in drycc/controller and drycc/workflow-e2e. The commit body for the first PR in drycc/workflow-e2e would look like:

feat(foo_test): add e2e test for feature foo

[skip e2e] test for controller#42

Adding [skip e2e] forgoes the e2e tests on this commit. This and any other required PRs aside from the final PR should be submitted first, so that their respective build and image push jobs run.

Lastly, the final PR in drycc/controller should be created with the required PR number(s) listed, in the form of [Rr]equires <repoName>#<pullRequestNumber>, for use by the downstream e2e run.

feat(foo): add feature foo

Requires workflow-e2e#42

Code Standards

Drycc components are implemented in Go and Python. For both languages, we agree with The Zen of Python, which emphasizes simple over clever. Readability counts.

Go code should always be run through gofmt on the default settings. Lines of code may be up to 99 characters long. Documentation strings and tests are required for all exported functions. Use of third-party go packages should be minimal, but when doing so, such dependencies should be managed via the glide tool.

Python code should always adhere to PEP8, the python code style guide, with the exception that lines of code may be up to 99 characters long. Docstrings and tests are required for all public methods, although the flake8 tool used by Drycc does not enforce this.

Commit Style

We follow a convention for commit messages borrowed from CoreOS, who borrowed theirs from AngularJS. This is an example of a commit:

feat(scripts/test-cluster): add a cluster test command

this uses tmux to setup a test cluster that you can easily kill and
start for debugging.

To make it more formal, it looks something like this:

{type}({scope}): {subject}
<BLANK LINE>
{body}
<BLANK LINE>
{footer}

The allowed {types} are as follows:

• feat -> feature
• fix -> bug fix
• docs -> documentation
• style -> formatting
• ref -> refactoring code
• test -> adding missing tests
• chore -> maintenance

The {scope} can be anything specifying the location(s) of the commit change(s).

The {subject} needs to be an imperative, present tense verb: “change”, not “changed” nor “changes”. The first letter should not be capitalized, and there is no dot (.) at the end.

Just like the {subject}, the message {body} needs to be in the present tense, and includes the motivation for the change, as well as a contrast with the previous behavior. The first letter in a paragraph must be capitalized.

All breaking changes need to be mentioned in the {footer} with the description of the change, the justification behind the change and any migration notes required.

Any line of the commit message cannot be longer than 72 characters, with the subject line limited to 50 characters. This allows the message to be easier to read on GitHub as well as in various git tools.

Merge Approval

Any code change - other than a simple typo fix or one-line documentation change - requires at least two Drycc maintainers to accept it. Maintainers tag pull requests with “LGTM1” and “LGTM2” (Looks Good To Me) labels to indicate acceptance.

No pull requests can be merged until at least one core maintainer signs off with an LGTM. The other LGTM can come from either a core maintainer or contributing maintainer.

If the PR is from a Drycc maintainer, then he or she should be the one to close it. This keeps the commit stream clean and gives the maintainer the benefit of revisiting the PR before deciding whether or not to merge the changes.

An exception to this is when an errant commit needs to be reverted urgently. If necessary, a PR that only reverts a previous commit can be merged without waiting for LGTM approval.

6 - Community

Drycc software is fully open source. As such, the “Drycc community” consists of anyone who uses the Drycc software and participates in its evolution, whether by answering questions, finding bugs, suggesting enhancements, or writing documentation or code.

Drycc development is coordinated through numerous project repositories on GitHub. Anyone can check out the source code for any Drycc component, fork it, make improvements, and create a pull request to offer those changes back to the Drycc community.

Engine Yard maintains the numerous Drycc projects, and as such, decides what ends up in the official GitHub repositories. Drycc depends on the contributions of the community; the maintainers will not ignore pull requests or issues.

Drycc uses the timeless, highly efficient, and totally unfair system known as “Benevolent Dictator for Life” (BDFL). Gabriel Monroy, the creator of Drycc, is our BDFL and has final say over all decisions related to Drycc.

Open Source Bounties

Drycc projects are bounty-friendly. We believe open source bounty sites can be constructive tools in the development of open source software. Community members are encouraged to a) offer bounties and b) receive bounties for open source contributions that benefit everyone. The Drycc maintainers, however, will not accept bounties on this project but are more than happy to help community members attempting bounties.

7 - Triaging Issues

Triage helps ensure issues resolve quickly by:

• Describing the issue’s intent and purpose is conveyed precisely. This is necessary because it can be difficult for an issue to explain how an end user experiences a problem and what actions they took.
• Giving a contributor the information they need before they commit to resolving an issue.
• Lowering the issue count by preventing duplicate issues.
• Streamlining the development process by preventing duplicate discussions.

If you don’t have time to code, consider helping with triage. The community will thank you for saving them time by spending some of yours.

Ensure the Issue Contains Basic Information

Before triaging an issue very far, make sure that the issue’s author provided the standard issue information. This will help you make an educated recommendation on how to categorize the issue. Standard information that should be included in most issues are things such as:

• the version(s) of Drycc this issue affects
• a reproducible case if this is a bug
• page URL if this is a docs issue or the name of a man page

Depending on the issue, you might not feel all this information is needed. Use your best judgment. If you cannot triage an issue using what its author provided, explain kindly to the author that they must provide the above information to clarify the problem.

If the author provides the recommended information but you are still unable to triage the issue, request additional information. Do this kindly and politely because you are asking for more of the author’s time.

If the author does not respond with requested information within the timespan of a week, close the issue with a kind note stating that the author can request for the issue to be reopened when the necessary information is provided.

Classifying the Issue

An issue can have multiple of the following labels:

Issue Kind

Functional Area

• builder
• cache
• contrib and provisioning
• client
• controller
• database
• docs
• kubernetes
• registry
• router
• store (Ceph)
• tests

Easy Fix

“Easy Fix” issues are a way for a new contributor to find issues that are fit for their experience level. These issues are typically for users who are new to Drycc, and possibly Go, and are looking to help while learning the basics.

Prioritizing issues

When attached to a specific milestone, an issue can be attributed one of the following labels to indicate their degree of priority.

And that’s it. That should be all the information required for a new or existing contributor to come in and resolve an issue.

8 - Conduct

Conduct

The Drycc community welcomes and encourages participation by everyone.

No matter how you identify yourself or how others perceive you: we welcome you. We welcome contributions from everyone as long as they interact constructively with our community.

The Drycc developer community continues to grow, and it is inevitable that disagreements and conflict will arise. We ask that participants conduct themselves according to these principles:

1. Be welcoming, friendly, and patient.

2. Be considerate.

Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we’re a world-wide community, so you might not be communicating in someone else’s primary language.

3. Be respectful.

Not all of us will agree all the time, but disagreement is no excuse for poor behavior and bad manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one.

4. Be careful in the words that you choose.

Be kind to others. Do not insult or put down other participants. Behave professionally. Remember that harassment and sexist, racist, or exclusionary jokes are never appropriate for the community.

(Thanks to the Debian and Django communities for their text and inspiration.)

9 - Drycc Maintainers

What is a maintainer?

(Unabashedly stolen from the Podman project)

There are different types of maintainers, with different responsibilities, but all maintainers have 3 things in common:

1. They share responsibility in the project’s success.
2. They have made a long-term, recurring time investment to improve the project.
3. They spend that time doing whatever needs to be done, not necessarily what is the most interesting or fun.

Maintainers are often under-appreciated, because their work is harder to appreciate. It’s easy to appreciate a really cool and technically advanced feature. It’s harder to appreciate the absence of bugs, the slow but steady improvement in stability, or the reliability of a release process. But those things distinguish a good project from a great one.

Drycc maintainers

Drycc has two groups of maintainers in addition to our beloved Benevolent Dictator for Life.

BDFL

Drycc follows the timeless, highly efficient and totally unfair system known as Benevolent dictator for life.

Gabriel Monroy (@gabrtv), as creator of the Drycc project, serves as our project’s BDFL. While the day-to-day project management is carried out by the maintainers, Gabriel serves as the final arbiter of any disputes and has the final say on project direction.

Core maintainers

Core maintainers are exceptionally knowledgeable about all areas of Drycc. Some maintainers work on Drycc full-time, although this is not a requirement.

The duties of a core maintainer include:

• Classify and respond to GitHub issues and review pull requests
• Help to shape the Drycc roadmap and lead efforts to accomplish roadmap milestones
• Participate actively in feature development and bug fixing
• Answer questions and help users in the Drycc #community Slack channel

The current list of core maintainers can be seen here.

No pull requests can be merged until at least one core maintainer signs off with an LGTM. The other LGTM can come from either a core maintainer or contributing maintainer.

Contributing maintainers

Contributing maintainers are exceptionally knowledgeable about some but not necessarily all areas of Drycc, and are often selected due to specific domain knowledge that complements the project (but a willingness to continually contribute to the project is most important!). Often, core maintainers will ask a contributing maintainer to weigh in on issues, pull requests, or conversations where the contributing maintainer is knowledgeable.

The duties of a contributing maintainer are very similar to those of a core maintainer, but they are limited to areas of the Drycc project where the contributing maintainer is knowledgeable.

Contributing maintainers are defined in practice as those who have write access to the Drycc repository. All maintainers can review pull requests and add LGTM labels as appropriate.

Becoming a maintainer

The Drycc project wouldn’t be where it is today without its community. Many of the project’s community members embody the spirit of maintainership, and have contributed substantially to the project.

The contributing maintainers group was created in part so that exceptional members of the community who have an interest in the continued success of the project have the opportunity to join the core maintainers in guiding the future of Drycc.

Generally, potential contributing maintainers are selected by the Drycc core maintainers based in part on the following criteria:

• Sustained contributions to the project over a period of time (usually months)
• A willingness to help Drycc users on GitHub and in the Drycc #community Slack channel
• A friendly attitude :)

The Drycc core maintainers must unanimously agree before inviting a community member to join as a contributing maintainer, although in many cases the candidate has already been acting in the capacity of a contributing maintainer for some time, and has been consulted on issues, pull requests, etc.