Thank you for your interest in contributing to the kraken-lib project. We welcome all kinds of contributions: ideas, code, patches, bug reports, feature requests and documentation edits. Before diving in, please review this process summary. We did our best to make it as painless as possible!
Below we outline the workflows for contributing. We use GitHub to manage all contributions, so please open an account if you don’t already have one.
An easy way to start is to work on issues we’ve labeled as “Help Wanted” because they:
- Are easy to complete
- Require little time and minimal context for kraken-lib
To get started, search Help Wanted issues and assign one to yourself, or add a comment to one so we can prevent multiple simultaneous contributors and help you out.
Before requesting a new feature, please check open issues for any similar requests to avoid duplicates. When you don’t find any, simply open an issue and summarize the desired functionality of your requested feature. Provide as much detail as possible and reference related issues, if any. And please apply the label 'Feature Request'.
To report a bug, open an issue and summarize the bug. To help us understand and fix it, please provide the following:
- Detailed steps to reproduce the bug
- The version of kraken-lib you’re using
- The expected behavior
- The actual, incorrect behavior
- Apply the label 'Bug'
Search our issue tracker for existing issues (aka tickets) similar to yours. If you find one, please add your information to it as a comment.
If you want to provide a patch with your bug report, please do so by sending us a pull request (PR) as described in the section below.
We use GitHub issue labels to help us organize our workflow. As such, this section is for helping the kraken development team push work through in an orderly fashion. If you choose to help out by labeling, great! If not, we will do it during our bi-weekly backlog grooming meetings.
All issues must be labeled as one of the three following types. Ideally, the person creating the issue assigns the label at the time of creation. Otherwise, a label will be assigned in the next grooming meeting. The issue types are:
- Bug
- Feature Request
- Research Spike
All issues must have a priority label applied as "priority-p[0-3]'. Use the following definitions when prioritizing issues:
- p0: highest priority, most critical issues. p0 implies kraken-lib is broken and should have someone assigned immediately. If you believe you've hit a p0 issue, link the issue into the #kraken Slack channel (link at bottom of this page) so we can quickly triage.
- p1: to be addressed in the next sprint or two. These issues will be completed regardless of larger project goals.
- p2: will only be completed as part of a larger project (e.g. CI, multi-cluster support, code cleanup, etc.) and will be triaged monthly to reprioritize up or down.
- p3: lowest priority, will only be completed as part of a larger project and will be triaged quarterly to reprioritize up or close altogether.
For all issues, commenting on why they're important to you may prompt reprioritizing, so please speak up if you need something.
Some issues are part of larger projects or program areas, such as the creation of a new provider (e.g. BareMetal, Azure), fully supporting multiple clusters specified in a single config (multi-cluster support), CI, etc. Use a project label, as appropriate, to ensure we're working effectively by targeting a specific larger goal and heading towards completing the entire project.
Use this label for any issue not requiring much knowledge of the kraken-lib codebase and that can be completed in a few hours. These are a great place to get started.
This label should be applied to any issue requiring further analysis from an experienced kraken engineer and possibly a design proposal. Anyone can apply this label. We don't have a monitor for this label, so if you're interested in working in this area or have applied this label, please ping the #kraken Slack channel for support.
Before contributing code, please familiarize yourself with the kraken codebase and our general guidelines below:
- Install pre-commit to check your code against the ansible linter
- If you don’t know where to start, browse for open issues and tasks or start with Help Wanted issues, as mentioned above
- After you find an issue, create a pull request following the PR process below
- Because we rely on CI and end-to-end tests to validate the integrity of the clusters we create, please monitor the results of CI jobs (available in the PR) to verify your code is passing
- Contribute to the kraken-lib codebase via GitHub pull requests (if any problems arise with the PR, we can discuss via GitHub comments)
- For small patches, feel free to submit PRs directly for those patches
Please submit all contributions as pull requests, using this process:
- Create a fork of the kraken-lib repo to your personal account (refrain from working in the kraken-lib master)
- Create a topic branch from where you want to base your work
- Usually your fork’s master branch
- To quickly create a topic branch based on the master:
git checkout -b fix/master/my_contribution master - Avoid working directly on the master branch * If your change probably affects backwards compatability, please include 'test-all' in the feature branch name. This will cause our CI to run against all supported versions of kubernetes. Example branch name: 'support-k8s-1.10-test-all'
- Commit your changes to a topic branch in your fork
- Check for unnecessary whitespace with
git diff --checkbefore committing - Make sure your commit messages are in the proper format
- Check for unnecessary whitespace with
Make the example in CONTRIBUTING imperative and concrete
Without this patch applied, the example commit message in the CONTRIBUTING
document is not a concrete example. This is a problem because the
contributor is left to imagine what the commit message should look like
based on a description rather than an example. This patch fixes the
problem by making the example concrete and imperative.
Fixes: #<github issue number filed to describe the problem>
- Submit a PR to the kraken-lib repo
- Address only one issue per PR
- For multiple issues, submit multiple PRs
- If your PR is related to or depends on an existing one, note the PR number(s) in your comment
- All PRs must pass CI testing before approval
- Once we approve your PR, we’ll merge it into the kraken-lib master
Our core team continuously reviews and monitors open PRs. We also assign reviewers to open PRs during weekly meetings. If your PR has been open for over a week with no one assigned, ping @coffeepac.
After the kraken team provides feedback, please respond within two weeks. After which, if the PR shows no activity, we may close the PR or take it over ourselves.
See GitHub documentation for creating pull requests, forking repos and syncing forks, for more help with this process.
You can access the recommended kraken-lib developer tool in the /hack directory. Called dockerdev, it pulls down a kraken-tools image and lands the user into a Bash prompt with a number of useful host directories mounted into the container including the local kraken-lib checkout, ~/.ssh, ~/.aws and more depending on the config file used.
The intent is to mitigate version issues and requirements, allowing you, the developer, to focus on coding and not worry about dependencies.
Here we document how to use kraken-tools to work with a cluster.
- You’ve used either kraken-lib or kraken to generate a config file
- You’ve pulled the latest kraken-lib master branch on your machine and are working on a fork (
docker pull quay.io/samsung_cnct/kraken-tools) - You’re currently on the your local kraken-lib GitHub fork directory
- Generate latest configuration file, for example:
kraken generate - Create a Docker container that points to you (and mount your kraken-lib workspace) cluster config (generated earlier):
hack/dockerdev -c <PATH_TO_CONFIGS>/<YOUR_CONFIG>.yaml - In 15 to 45 seconds, you will be in the Bash terminal of the container
- Bring up your cluster as you would normally when developing kraken-lib (including any flags you require):
/bin/up.sh -c <PATH_TO_CONFIGS>/<YOUR_CONFIG>.yaml
Now that you’ve mounted your workspace, you can make changes to kraken-lib here and access Git commands.
For changes of a trivial nature to comments and documentation, you don’t need to create a new issue. Just start the first line of a commit with '(doc)' instead of a ticket number.
[doc] Add documentation commit example to CONTRIBUTING
There is no example for contributing a documentation commit
to the kraken-lib repository. This is a problem because the contributor
is left to assume how a commit of this nature may appear.
The first line is a real life imperative statement with '(doc)' in
place of what would have been the ticket number in a
non-documentation related commit. The body describes the nature of
the new documentation or comments added.
For more substantive, content-related changes, commit your edits in your repo fork and create a PR for our team to review.
Thanks again for your contributions! Here are some resources you might find handy:
- #kraken Slack on k8s.slack.com
- kraken-lib issue tracker
- kraken-tools
- kraken codebase
- General GitHub documentation
- GitHub pull request documentation
This document is maintained by Patrick Christopher (@coffeepac) at Samsung SDS.