Contributing

Ways to get involved with the development of ksonnet

Contributing to ksonnet

Contributions, suggestions, feature requests, or bug reports are welcomed!

Issues are tracked in Github with labels such as good first issue for new contributors.

Changes to how ksonnet generates Kubernetes objects is done through ksonnet-lib. Such issues should be filed under the appropriate upstream repository.

For any additional questions or issues, visit the #ksonnet Slack channel.

Feature requests and bug reports

Before submitting an issue, check to make sure there is not an existing issue.

Building ksonnet from the master branch to see if the bug has already been resolved is highly recommended.

When opening an issue, tag the issue as a bug report or feature request.

If opening a bug report, follow the template to provide a short summary on how to reproduce the issue. Add the relevant version information by copying the output of ks version. Finally, add a couple notes on the desired behavior.

Setting up a development environment

The current stable version of Go is recommended for development. Make sure the $GOPATH envrionment variable is set.

Git workflow

Fork ksonnet from Github. Download ksonnet locally with go get github.com/ksonnet/ksonnet.

Navigate to the project directory. This will be working directory for running tests and using the Makefile.

cd $GOPATH/src/github.com/ksonnet/ksonnet

Add a new remote pointing to the fork.

git remote add $REMOTE_NAME https://github.com/$GITHUB_USERNAME/ksonnet.git

git remote add $REMOTE_NAME git@github.com:$GITHUB_USERNAME/ksonnet.git

Checkout a new branch then make your code changes.

git checkout -b shiny-new-feature

When committing changes, remember to signoff your work with --signoff as work without a DCO cannot be accepted.

git commit -m "Added shiny new feature" --signoff

Push the branch to your remote and open a pull request for review.

Building the binary

Build the binary in the project directory with make ks.

Running ksonnet via Docker is also an option. Set an alias for the Docker command and rebuild a new image to capture code changes.

Updating documentation

Changes to the CLI contains two steps: updating the docstrings and rebuilding the documentation through the Makefile.

Documentation for the CLI reference are located in pkg/clicmd/.

Several notes:

  • Multi-line strings are wrapped by backticks.
  • Inline code wrapped with back-ticks must be concatenated and wrapped outermost with double quotes.

Rebuild the documentation with make docs prior to committing the changes.

Documentation pages without an Edit this page link such as the tutorial belong to a private repository. Open an issue to propose changes or enhancements on the ksonnet Github page along with the relevant URL(s).

Running tests

There are two types of tests for ksonnet. New features and bug fixes are encouraged to have added tests to maintain code coverage and prevent regressions.

Unit Testing

Run all of the tests with go test ./...

Individual functions can be run with a path to a package and test function name. Pass the -v verbosity flag to see more information about each test.

$ go test -v ./pkg/actions -run TestApply
=== RUN   TestApply
=== RUN   TestApply/with_a_supplied_env
=== RUN   TestApply/with_a_current_env
=== RUN   TestApply/without_supplied_or_current_env
--- PASS: TestApply (0.00s)
    --- PASS: TestApply/with_a_supplied_env (0.00s)
    --- PASS: TestApply/with_a_current_env (0.00s)
    --- PASS: TestApply/without_supplied_or_current_env (0.00s)
=== RUN   TestApply_invalid_input
--- PASS: TestApply_invalid_input (0.00s)
=== RUN   TestApply_requires_app
--- PASS: TestApply_requires_app (0.00s)
PASS
ok      github.com/ksonnet/ksonnet/pkg/actions  0.040s

End-to-end

End-to-end testing checks to make sure the overall behavior of ksonnet is performing as intended. Install Ginkgo before running the tests.

The tests will also require a cluster. To run these tests locally, download the latest release of Minikube and start the single-node cluster with minikube start.

Run the shell script which will parallelize testing by default: ./e2e/e2e.sh -- --kubeconfig ~/.kube/config --context $CLUSTER_CONTEXT.

Limit the resources used by specifying the number of nodes:

./e2e/e2e.sh --nodes 2 -- --kubeconfig ~/.kube/config --context $CLUSTER_CONTEXT
Last updated on: August 28, 2018