Contributing to Solo

Instructions for developers working on the Solo project

How to Contribute to Solo

This document describes how to set up a local development environment and contribute to the Solo project.

Prerequisites

Node.js (use the version specified in the repository, if applicable)
npm
Docker or Podman
Kubernetes (local cluster such as kind, k3d, or equivalent)
task (Taskfile runner)
Git
K9s (optional)

Initial setup

Clone the repository:

git clone https://github.com/hiero-ledger/solo.git
cd solo

Install dependencies:

$ npm install

Install solo as a local CLI:

$ npm link

Notes:
This only needs to be done once.
If solo already exists in your PATH, remove it first.
Alternatively, you can run commands via: npm run solo-test -- <COMMAND> <ARGS>

Run the CLI:

$ solo

Logs and debugging

Solo logs are written to:

$HOME/.solo/logs/solo.log

A common debugging pattern is:

$ tail -f $HOME/.solo/logs/solo.log | jq

How to run the tests

Unit tests:
```
$ task test
```
All other Integration and E2E test tasks can be listed using
```
$ task --list-all
```

Code formatting

Before committing any changes, always run:

$ task format

How to Update Component Versions

Edit the component’s version inside /version.ts

How to Inspect the Cluster

When debugging, it helps to inspect resources and logs in the Kubernetes cluster.

Kubectl

Common kubectl commands:

kubectl get pods -A
kubectl get svc -A
kubectl get ingress -A
kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace>

Official Documentation: https://kubernetes.io/docs/reference/kubectl/

K9s (Recommended)

K9s is the primary tool used by the Solo team to inspect and debug Solo deployments.

Why K9s:

Terminal UI that makes it faster to navigate Kubernetes resources
Quickly view logs, events, and descriptions
Simple and intuitive

Start K9s:

$ k9s -A

Official Documentation: https://k9scli.io/topics/commands/

Pull Request Requirements

DCO (Developer Certificate of Origin) and Signed Commits

Two separate requirements are enforced on this repository:

1) DCO Sign-off (required)

All commits must include a DCO sign-off line. PRs with unsigned (no sign-off) commits will fail checks and cannot be merged.

Sign off commits with:

$ git commit -s -m "commit message"

This adds a line like, to your commit message:

Signed-off-by: Your Name <your@email.com>

(Optional) Configure Git to always add the sign-off automatically:

$ git config --global format.signoff true

2) Cryptographically Signed Commits (required)

In addition to the DCO sign-off, the repository also enforces a GitHub rule that blocks commits that are not signed and verified.

This means your commits must be cryptographically signed using GPG or SSH and show a Verified badge on GitHub.

If your commits are not signed, they will be rejected even if the DCO check passes.

To enable commit signing, see GitHub documentation:

After setup, verify signing is enabled:

$ git config --global commit.gpgsign true

Both are required:

DCO sign-off line (-s)
Cryptographic signature (Verified commit)

Conventional Commit PR titles (required)

Pull request titles must follow Conventional Commits.

Examples:
feat: add support for grpc-web fqdn endpoints
fix: correct version resolution for platform components
docs: update contributing guide
chore: bump dependency versions

This is required for consistent release notes and changelog generation.

Additional guidelines

Prefer small, focused PRs that are easy to review.
If you are unsure where to start, open a draft PR early to get feedback.
Add description and link all related issues to the PR.