Contributing to Hera

Thank you for considering a contribution to Hera!

Your time is the ultimate currency, and the community highly appreciates your willingness to dedicate some time to Hera for the benefit of everyone! Remember to star the repo on GitHub and share Hera with your colleagues to grow our community!

New Contributor Guide

We welcome code contributions for new features and bug fixes that address issues labeled with “good-first-issue” or “ideal-for-contribution”.

We also encourage contributions in the form of: * Adding your organization as a user of Hera! * Answering questions on GitHub Discussions and Slack * Blog Posts / Social Media featuring Hera * Attending the Hera working group meeting (bi-weekly on Fridays, 3pm GMT / 3pm BST) * Add notes to our community agenda doc for the meeting

If you have an idea for a large feature, please reach out to us on the Slack channel or attend the working group meetings first, and then we can help you propose the feature using the CNCF design proposal template.

Setting up

If you plan to submit contributions to Hera you can install Hera in a virtual environment managed by poetry:

poetry install

Once the dependencies are installed, you can use the various make targets to replicate the CI jobs.

make help
check-codegen                  Check if the code is up to date
ci                             Run all the CI checks
codegen                        Generate all the code
events-models                  Generate the Events models portion of Argo Workflows
events-service                 Generate the events service option of Hera
examples                       Generate all the examples
format                         Format and sort imports for source, tests, examples, etc.
help                           Showcase the help instructions for all the available `make` commands
lint                           Run a `lint` process on Hera and report problems
models                         Generate all the Argo Workflows models
services                       Generate the services of Hera
test                           Run tests for Hera
workflows-models               Generate the Workflows models portion of Argo Workflows
workflows-service              Generate the Workflows service option of Hera

Working in VSCode

If your preferred IDE is VSCode, you may have an issue using the integrated Testing extension where breakpoints are not respected. To solve this, add the following as a config in your .vscode/launch.json file:

{
   "name": "Debug Tests",
   "type": "debugpy", // "python" is now deprecated
   "request": "launch",
   "purpose": ["debug-test"],
   "console": "integratedTerminal",
   "justMyCode": false,
   "env": {"PYTEST_ADDOPTS": "--no-cov"}
}

Contributing checklist

Please keep in mind the following guidelines and practices when contributing to Hera:

Your commit must be signed (git commit --signoff). Hera uses the DCO application that enforces the Developer Certificate of Origin (DCO) on commits.
Use make format to format the repository code. make format maps to a usage of ruff, and the repository adheres to whatever ruff uses as its strict pep8 format. No questions asked!
Use make lint test to lint, run tests, and typecheck on the project.
Add unit tests for any new code you write.
Add an example, or extend an existing example, with any new features you may add. Use make examples to ensure that the documentation and examples are in sync.

Adding new Workflow YAML generation tests

Hera has an automated-test harness that is coupled with our documentation. In order to add new tests, please follow these steps -

Local Hera examples

Tests that do not correspond to any upstream Argo Workflow examples should live in examples/workflows/*.py

In order to add a new workflow test to test Hera functionality, do the following -

Create a new file under examples/workflows, for example - my_test.py
Define your new workflow. Make sure that the target workflow you wish to export and test against is named w
Run tests using make test. Hera tests will generate a golden copy of the output YAML with the name my-test.yaml if it does not exist already
If you would like to update the golden copy of the test files, you can run make regenerate-test-data
The golden copies must be checked in to ensure that regressions may be caught in the future

Upstream Hera examples

Tests that correspond to any upstream Argo Workflow examples should live in examples/workflows/upstream/*.py. These tests exist to ensure that Hera has complete parity with Argo Workflows and also to catch any regressions that might happen.

In order to add a new workflow test to test Hera functionality, do the following -

Create a new file under examples/workflows/upstream that corresponds with the name of the upstream example yaml file. If the yaml file has a hyphen, your python file name should replace those with an underscore. eg. if you are trying to replicate archive-location.yaml your python file should be called archive_location.py
Define your new workflow. Make sure that the target workflow you wish to export and test against is named w
Run tests using make test. Hera tests will generate a golden copy of the output YAML with the name archive-location.yaml and also generate a local copy of the upstream yaml file with the name archive-location.upstream.yaml
If you would like to update the golden copy of the test files, you can run make regenerate-test-data
The golden copies must be checked in to ensure that regressions may be caught in the future

Adding new Workflow on-cluster tests

Hera’s CICD spins up Argo Workflows on a local Kubernetes cluster, which runs tests decorated with @pytest.mark.on_cluster. If you want to add more on-cluster tests, the easiest way is through a GitHub Codespace. You can then run the same make commands that run in CICD:

make install-k3d

This will install the k3d CLI.

make run-argo

This will create a cluster using k3d called test-cluster, then create a namespace called argo on it, applying the argo configuration, and patching the deployment to use server as the auth-mode, meaning the connection to submit the workflow doesn’t require an authentication mechanism.

You can then run existing on-cluster tests to ensure everything is set up correctly. This command also ports-forward the server’s port.

make test-on-cluster

Viewing the Argo UI from a Codespace

Before doing this, note that anyone will be able to connect using the Argo UI URL!

Ensure Argo Workflows is running using the make command:

make run-argo

Forward the Server’s port using kubectl:

kubectl -n argo port-forward deployment/argo-server 2746:2746

Then, go to the PORTS panel in VSCode, and add the 2746 port. You should see a green circle to the left of the port. Then right click on the 2746 row and set Port Visibility to public. You can then open the URL in your browser to view the Argo UI.

Code of Conduct

Please be mindful of, and adhere to, the CNCF’s Code of Conduct when contributing to hera.