Skip to content

DEV.md

Latest commit

 

History

History
181 lines (129 loc) · 4.67 KB

DEV.md

File metadata and controls

181 lines (129 loc) · 4.67 KB

How to Contribute to Solo

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

Table of Contents

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

  1. Clone the repository:
git clone https://github.com/hiero-ledger/solo.git
cd solo
  1. Install dependencies:
$ npm install
  1. 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>
  1. 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)

Refer to the Hiero Ledger contributing docs under sign-off: https://github.com/hiero-ledger/.github/blob/main/CONTRIBUTING.md#sign-off

(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.