Contributing

New contributors are welcome. We’d love your help. Even if you’re new to Rust or Kubernetes, or open source in general. This page will help you out with the basics and also give you a couple of guidelines.

There’s lots of ways to contribute:

• Issues
  • Test things out and file bugs
  • Submit an issue to request a new feature
  • Comment and provide your thoughts on an existing issues
  • Show off an operator that uses roperator as an example for others
• Code
  • Fix a bug
  • Implement a feature
• Documentation
  • Update existing docs
  • Add a guide on a specific topic
• Mentoring new contributors

If you want to contribute, but for whatever reason you’d like some help or mentorship, then please reach out and ask. I’d be happy to help, regardless of your level of experience.

General Guidelines

Be kind to all others at all times. This wonderful thing where strangers on the internet collaborate to build and share the tools of the future is only possible if we maintain a high level of mutual respect and consideration toward each other. We won’t tolerate comments that are rude, hateful, judgemental, or condescending.

Our general workflow is:

1. File an Issue describing the bug or enhancement
2. Most non-trivial issues will require some discussion before they’re ready to be worked on. These will have the “Discussion Needed” label.
3. Fork the repo and work on a branch based off of the master branch
4. Create a Pull Request back to master

Issues

We use issues for reporting and tracking bugs, discussing ways to enhace the project, and for asking and answering questions. Communication in issues is the most important ways to contribute. Before we can write any code, we need to make decisions about the desired behavior of the system, which often requires balancing various trade offs or navigating around tricky obstacles. The trickiest part is often times communicating these sometimes complex and subtle considerations to others. Your comments on issues are hugely important and greatly appreciated! Even if your idea is not implemented in code, the discussion around it is still valualble to the project and to others who are interested in learning.

• For bug reports, please try to include details about the environment, steps to reproduce, what happened, and what did you expect to happen.
• For enhancements, please include information about your use cases. If you have a recommended approach for solving the problem, please alsoinclude some information about alternative approaches, to help others gain a better understanding of the overall issue.

Code

• Any non-trivial PRs should reference an existing issue. Please create an issue first, if there isn’t one already.
• Before starting on code, please leave a comment on the associated issue so that somebody else doesn’t start working on the same issue.
• The Continuous integration checks need to pass before we merge a pull request
• It’s always appreciated when documentation changes come along with the code, but it’s not required. Please just call out the need for documentation changes if you didn’t update them yourself, so we can make sure to update them prior to releasing.

Checks

The continuous integration checks are run on each PR. Here’s how to run them locally:

• cargo test --features test : will run ONLY the unit tests (not the integration tests)
• cargo test --features 'testkit test' will run all the tests, including integration tests. You’ll need to have a few prerequisites:
  • Have a kubernetes cluster running. We use kind in the CI environment, but just about any local or remote cluster will work, as long as it’s a test cluster. Don’t run these tests on a production cluster, or any cluster that you feel attached to.
  • Ensure that you have a kubeconfig file that has the current context set to the cluster you want to use. You can set the KUBECONFIG environment variable if you don’t want to use the default one in your home directory.
  • Run kubectl apply -f tests/resources/ to create the CRDs that are used in tests
• cargo fmt --all -- --check : will assert that the code is formatted properly. You can omit the --check to have it just reformat the code
• cargo clippy --all-features -- -D warnings will run the linter and fail on any warnings.

Documentation

Documentation is a really important part of the project, and help is always appreciated! You don’t need to file an issue for most documentation changes, but it’s certainly okay to do so if you want to discuss the changes prior to working on them. There’s three types of documentation in roperator:

• API documentation is generated by rustdoc and hosted by docs.rs
• The guide is generated and hosted by github pages. You can use the github-pages ruby gem to test this out locally
• The README is often times peoples’ first introduction to the project, so feel free to give it some love, too