Contributing & Local Development
Relevant source files
The following files were used as context for generating this wiki page:
Kuberhealthy is a CNCF-hosted Kubernetes operator for synthetic monitoring and continuous process verification. Contributing to the project involves following a standard GitHub flow, adhering to specific legal requirements such as the Developer Certificate of Origin (DCO), and maintaining high standards for code quality and testing. This guide outlines the technical requirements and workflows for local development and community involvement.
Sources: README.md:5-9, CONTRIBUTING.md:1-5
Developer Workflow
Contributors are expected to use a fork-and-branch model. For significant features or breaking changes, a proposal issue should be submitted before development begins to ensure alignment with project maintenance goals.
Step-by-Step Contribution Process
- Fork and Clone: Fork the
Kuberhealthy/Kuberhealthyrepository and clone it to your local environment. - Branching: Create a feature branch that describes the proposed change.
- Development: Implement the feature or fix.
- Documentation: Add your name to the
CONTRIBUTORS.mdfile. - Pull Request: Submit a PR from your fork's branch to the master branch of the primary repository.
- Review: Wait for project maintainers to address the change and provide feedback.
Sources: CONTRIBUTING.md:7-17, CONTRIBUTORS.md:1-33
The diagram above illustrates the lifecycle of a contribution from initial proposal to final merge.
Sources: CONTRIBUTING.md:7-17
Local Development Environment
Kuberhealthy provides a pre-configured development environment using Hermit. This tool ensures that developers have access to consistent versions of Go and other required tooling without needing to install them manually on the host system.
Activating the Environment
To activate the Hermit environment, run the following command from the project root:
. ./bin/activate-hermit
Sources: README.md:143-154
General Requirements
All contributions must meet the following technical standards:
- Formatting: Code must be formatted using
go fmt. - Testing: Every change must include tests covering the new functionality.
- Continuous Integration: Code must pass all GitHub CI tests before being merged.
- Commit Signing: Every commit must be signed using
git commit -sto satisfy the DCO bot.
Sources: CONTRIBUTING.md:3-5, CONTRIBUTING.md:19-23
Helm Chart Development
Developing and updating the Kuberhealthy Helm charts involves specific automation scripts to maintain the repository index and package archives.
Versioning Logic
The project uses an automated shell script to manage Helm versions based on GitHub references.
| Component | Logic | Source Variable |
|---|---|---|
| appVersion | Updated when a Git tag is created. | ${GITHUB_REF##*/} |
| version | Updated on every merge to match the action number. | $GITHUB_RUN_NUMBER |
Sources: deploy/helm/helm-repo-update.sh:16-23
Repository Update Script
The helm-repo-update.sh script automates the packaging process:
- Lints the chart using
helm lint. - Packages the chart with the current run number.
- Merges the new package into
index.yaml. - Moves generated
.tgzfiles to the archives directory.
This flow represents the logic used in CI to update Helm metadata.
Sources: deploy/helm/helm-repo-update.sh:16-44
Developing Synthetic Checks
Developers contributing new checks can utilize various clients provided by the project. Synthetic checks are the core of Kuberhealthy's functionality and can be written in any language.
External Check Clients
Clients simplify the process of reporting success or failure back to the Kuberhealthy API.
- Go Client: Found in
pkg/checks/external/checkclient. - JavaScript Client: Available via NPM as
kuberhealthy.
Example JavaScript Usage
const kh = require("kuberhealthy");
try {
// Perform check logic here
kh.ReportSuccess();
} catch (err) {
kh.ReportFailure([err.message]);
process.exit(1);
}
Sources: clients/js/README.md:3-23, README.md:112-117
Community Standards
Kuberhealthy follows the Contributor Covenant Code of Conduct. All participants are expected to maintain a harassment-free experience and use inclusive language.
Key Standards
- Positive Behavior: Being respectful of differing viewpoints, accepting constructive criticism, and showing empathy.
- Unacceptable Behavior: Trolling, personal/political attacks, and publishing private information.
- Enforcement: Maintainers have the authority to remove comments, commits, or code that does not align with these standards.
Sources: CODE_OF_CONDUCT.md:1-40
Community Interaction
Project maintainers hold monthly community meetings on the 24th day of every month at 04:30 PM Pacific Time via Zoom to discuss ideas and code reviews.
Sources: README.md:156-163
Conclusion
Contributing to Kuberhealthy requires a commitment to signed commits (DCO), rigorous testing, and adherence to community standards. By utilizing tools like Hermit for local development and the provided client libraries for check creation, developers can efficiently extend Kuberhealthy's synthetic monitoring capabilities.
Sources: CONTRIBUTING.md:1-23, README.md:143-154