Contributing
Want to work on Akri with us? 🎉 We are actively looking for new contributors along all stages of the contribution journey, from casual contributors to reviewers and maintainers.
Akri utilizes a variety of technologies, and different background knowledge is more or less useful depending on what you are interested in contributing.
- All of Akri's components run on Linux, so you will need to set up an Ubuntu VM if you do not already have a Linux environment.
- Sample brokers and end applications can be written in any language and are individually containerized.
- Discovery handlers can be written in any language and can be deployed in their own Pods. However, if you would like your discovery handler to be embedded in the Akri Agent Pods, it must be written in Rust.
Contributions can be made by forking the repository and creating a pull request. Ideally, every pull request should have a corresponding issue that it is resolving. Each pull request will kick off a set of CI builds to validate that:
- the code adheres to standard Rust formatting (
cargo fmt) - the code builds properly (
cargo build) - the code is free of common mistakes (
cargo clippy) - the Akri tests all pass (
cargo test) - the inline documentation builds (
cargo doc)
See the developer guide for more information on how to set up your environment and build Akri components locally.
We follow the SymVer versioning strategy: [MAJOR].[MINOR].[PATCH]. Our current version can be found in
version.txt.- For non-breaking bug fixes and small code changes, [PATCH] should be incremented. This can be accomplished by running
./version.sh -u -p - For non-breaking feature changes, [MINOR] should be incremented. This can be accomplished by running
./version.sh -u -n - For major and/or breaking changes, [MAJOR] should be incremented. This can be accomplished by running
./version.sh -u -m
To ensure that all product versioning is consistent, our CI builds will execute
./version.sh -c to check all known instances of version in our YAML, TOML, and code. This will also check to make sure that version.txt has been changed. If a pull request is needed where the version should not be changed, add same version label to the pull request by commenting /add-same-version-label.Note for MacOS users:version.shuses the GNUsedcommand under-the-hood, but MacOS has built-in its own version. We recommend installing the GNU version viabrew install gnu-sed. Then follow the brew instructions on how to use the installed GNUsedinstead of the MacOS one.
Alternatively, you could skip running
version.sh file altogether. Once you make a pull request, you should comment any one of:/add-same-version-labelto not change version/version patchfor non-breaking bug fixes and small code changes/version minorfor non-breaking feature changes/version majorfor major and/or breaking changes
Commenting these commmands on your pull request will automatically update the version for you and push the changes to your pull request branch.
Akri follows similar logging conventions as defined by the Tracing crate. When adding logging to new code, follow the verbosity guidelines.
verbosity | when to use? |
|---|---|
error | Unrecoverable fatal errors |
warn | Unexpected errors that may/may not lead to serious problems |
info | Useful information that provides an overview of the current state of things (ex: config values, state change) |
debug | Verbose information for high-level debugging and diagnoses of issues |
trace | Extremely verbose information for developers of Akri |
Akri's workflows check for two labels in the PRs in order to decide whether to execute certain checks.
The version check workflow will run, ensuring you have increased the version number, unless you (A) only change a file that is on an ignored path of the workflow, such as all
*.md files OR (B) add the same version label to the pull request. Use this label if your change will trigger the workflow and the version should not be changed by your PR. The label will cause the check to automatically succeed.Akri has some intermediate containers that decrease the build time of the more frequently built final containers. These intermediate builds are long running and should only be run when absolutely needed. If your PR triggers a workflow to build them, you will see the workflow fail and get a message that requests that you add
build dependency containers label to your PR to start the build.You can add labels by commenting:
/add-build-dependency-containers-label/add-same-version-label
The Developer Certificate of Origin (DCO) is a legal statement used in open source software development. Contributors use it to confirm that they have the right to submit their code changes to a project and that they agree to license their contributions under the project's open source license. This helps protect the project and its maintainers from potential legal issues.
The DCO requires contributors to use a real name for identification purposes, which need not be their legal or birth name. This name should be one by which they are recognized in the community to enable future communication if necessary. Importantly, the real name should not be an anonymous or false identity..
When you submit a pull request, the DCO-bot will automatically assess whether your commits include the required
Signed-off-by line, ensuring compliance with the Developer Certificate of Origin (DCO). If any commits lack the necessary sign-off, the bot may prompt you to add it, guiding you through the process. It's important to note that you'll generally need to sign off on every commit you create.Last modified 19d ago