How to Contribute

Thanks for your interest in contributing to OpenClarity! Here are a few general guidelines on contributing and reporting bugs that we ask you to review. Following these guidelines helps to communicate that you respect the time of the contributors managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests. In that spirit of mutual respect, we endeavor to review incoming issues and pull requests within 10 days, and will close any lingering issues or pull requests after 60 days of inactivity.

Please note that all of your interactions in the project are subject to our Code of Conduct. This includes creation of issues or pull requests, commenting on issues or pull requests, and extends to all interactions in any real-time space e.g., Slack, Discord, etc.

Table Of Contents

• Reporting Issues
• Development
  • Dependencies
  • Development Environment
  • Running the OpenClarity stack locally using Docker
  • Building OpenClarity Binaries
  • Building OpenClarity Containers
  • Linting
  • Unit Tests
  • Testing End to End
  • Troubleshooting and Debugging
• Sending Pull Requests
• Other Ways to Contribute

Reporting Issues

Before reporting a new issue, please ensure that the issue was not already reported or fixed by searching through our issues list.

When creating a new issue, please be sure to include a title and clear description, as much relevant information as possible, and, if possible, a test case.

If you discover a security bug, please do not report it through GitHub. Instead, please see security procedures in SECURITY.md.

Development

After cloning the repository, you can run make help to inspect the targets that are used for checking, generating, building, and publishing code.

Dependencies

• Docker (for local and e2e testing)
• Go for the backend (the current version used by the project can be found in the .go-version file)
• A Node package manager for the frontend, such as npm or yarn

Internal dependencies by make targets are automatically installed if not present locally.

Development Environment

Depending on your IDE/editor of choice, you might need a go.work file for the gopls language server to find all references properly, such as:

go 1.22.6

use (
  ./api/client
  ./api/server
  ./api/types
  ./cli
  ./containerruntimediscovery/client
  ./containerruntimediscovery/server
  ./containerruntimediscovery/types
  ./core
  ./e2e
  ./e2e/testdata
  ./installation
  ./orchestrator
  ./provider
  ./plugins/runner
  ./plugins/sdk-go
  ./plugins/sdk-go/example
  ./plugins/store/kics
  ./scanner
  ./testenv
  ./uibackend/client
  ./uibackend/server
  ./uibackend/types
  ./utils
  ./workflow
)

Running the OpenClarity stack locally using Docker

For testing the changes across the whole stack, OpenClarity can be ran with Docker provider locally, after the images have been built and their tags have been updated in the installation/docker/image_override.env file:

docker compose --project-name openclarity \
               --file installation/docker/docker-compose.yml \
               --env-file installation/docker/image_override.env \
               up -d --wait --remove-orphans

When working only on one stack component, the component in question can be commented out in the docker compose file and ran separately with go run, or in the case of the UI, with the following commands:

make ui-dev to create UI development environment. Alternatively you can run them separately with:

• make ui-install can be used to install the UI dependencies.
• make ui-start can be used to start the UI development server.

Update the NGINX config accordingly if the components in question are affected to ensure that Docker can communicate with them if they are ran on local network. Some environment variables could also be necessary for you to export in your shell before running the component, inspect the contents of the corresponding .env file in the installation/docker directory!

To clean up the OpenClarity stack locally, run:

docker compose --project-name openclarity \
               --file installation/docker/docker-compose.yml \
               down --remove-orphans --volumes

Building OpenClarity Binaries

Makefile targets are provided to compile and build the OpenClarity binaries. make build can be used to build all the components, while make build-all-go and make ui only builds the go modules or the UI.

Building OpenClarity Containers

make docker can be used to build the OpenClarity containers for all the components. Specific targets for example make docker-cli and make docker-ui-backend are also provided.

In order to also publish the OpenClarity containers to a registry, please set the DOCKER_PUSH environment variable to true. You can override the destination registry as well:

DOCKER_REGISTRY=docker.io/my-openclarity-images DOCKER_PUSH=true make docker

You must be logged into the docker registry locally before using this target.

Linting

make lint can be used to run all the required linting rules over the code. In this case, the following targets will be ran:

• make license-check can be used to validate that all the files in the repo have the correctly formatted license header.
• make lint-actions checks Github Actions workflow files.
• make lint-bicep lints Bicep files.
• make lint-cfn lints Cloudformation files.
• make lint-go runs golangci-lint on the Go files. Rules and config can be viewed in the .golangci.yml file in the root of the repo.
• make lint-js runs npm run lint on the frontend files. Rules and config can be viewed in the ui/.eslintrc file.
• make lint-helm lints the Helm chart.

make fix is also provided which can automatically resolve lint issues such as formatting.

Unit tests

make test to run both go and js unit tests. Alternatively you can run them separately with:

• make test-go can be used run all go unit tests in the repo. Alternatively you can use the standard go test CLI to run a specific package or test like:

go test ./cli/cmd/... -run Test_isSupportedFS

• make test-js can be used to run all js unit tests in the repo.

Generators

make gen runs the following targets that can be ran separately as well:

• After making changes to the API schema in api/openapi.yaml, you can run make gen-api-go and make gen-api-js to regenerate the models, client and server code.
• Run make gen-bicep for generating bicep files after modifying them for installing OpenClarity on Azure.
• Run make gen-helm-docs for generating the docs after making changes to OpenClarity’s Helm chart.

Formatting

Prettier is enabled (so you can use autoformatting plugins), and its use is enforced for files under the ui/ directory. For example you could use something similar in VSCode’s settings.json:

}
  "[javascriptreact]": {
    "editor.formatOnSave": true,
    "editor.formatOnType": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  ...
}

make format can be used to format everything at once with Prettier which is also being checked by the CI.

Testing End to End

make e2e-docker can be used run the end-to-end tests in the repository locally using Docker. make e2e-k8s can also be used to run end-to-end tests for Kubernetes provider using Docker.

For details on how to test OpenClarity, please check the testing guide here on how to perform a test on AWS and the instructions here on how to run and add new tests.

Troubleshooting and Debugging

Please see the troubleshooting and debugging guide here.

Sending Pull Requests

Before sending a new pull request, take a look at existing pull requests and issues to see if the proposed change or fix has been discussed in the past, or if the change was already implemented but not yet released.

We expect new pull requests to include tests for any affected behavior, and, as we follow semantic versioning, we may reserve breaking changes until the next major version release.

Other Ways to Contribute

We welcome anyone that wants to contribute to OpenClarity to triage and reply to open issues to help troubleshoot and fix existing bugs. Here is what you can do:

• Help ensure that existing issues follows the recommendations from the Reporting Issues section, providing feedback to the issue’s author on what might be missing.
• Review and update the existing content of our Wiki with up-to-date instructions and code samples.
• Review existing pull requests, and testing patches against real existing applications that use OpenClarity.
• Write a test, or add a missing test case to an existing test.

Thanks again for your interest on contributing to OpenClarity!

:heart: