Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (82 loc) · 4.32 KB

CONTRIBUTING.md

File metadata and controls

105 lines (82 loc) · 4.32 KB
Raw

Contributing to orb-agent

orb-agent hosts the discovery backends (device, network, snmp, gnmi) and the worker alongside the agent in a single repository. To keep versioning and release notes coherent across all of these, the release pipeline keys off PR titles — so titles must follow the convention below.

How releases work

  • PRs are squash-merged into develop; the PR title becomes the single commit message. develop is later promoted to release.
  • A versioned agent release fires only on agent-scoped changes (under agent/ or cmd/) or via a manual workflow_dispatch. A backend-only change does not cut a new agent version — backends release on their own cadence, and a small backend release should not force an agent version bump.
  • When an agent release does fire, it aggregates everything: the release notes include every commit since the last vX.Y.Z tag — agent changes and any interim backend changes — grouped by type and scope.
  • Per-backend releases cut their own version from commits scoped to that backend (filtered by orb-discovery/<backend>/**), tagged <backend>/v<version> (e.g. snmp-discovery/v1.2.3). The semantic-release-monorepo plugin renders the GitHub Release title with a dash (snmp-discovery-v1.2.3); this is cosmetic — the git tag and ref keep the slash form. worker and device-discovery also publish to PyPI.
  • Pushing to develop rebuilds and publishes the orb-agent:develop image. This fires on changes under agent/, cmd/, or orb-discovery/ (the backends), so a backend-only change still refreshes the develop image continuously.
  • The Validate PR title check runs on every PR targeting develop. Once it is marked a required status check in branch protection, it blocks merge when the title doesn't match the convention; until then it reports status without blocking.

PR title convention (enforced)

Use a Conventional Commits title with one scope from the allowlist:

<type>(<scope>): <subject>

The automated check requires an allowlisted scope and rejects unknown scopes or a subject that starts with an uppercase letter.

Allowed types

feat, fix, perf, refactor, chore, docs, test, build, ci, revert

Allowed scopes

Agent:

  • agent — the orb-agent itself. feat/fix/perf here cuts an agent release.

Releasable backends (each cuts its own release and contributes to the aggregated agent release):

  • device-discovery
  • gnmi-discovery (experimental)
  • network-discovery
  • snmp-discovery
  • worker

Other scopes:

  • deps / deps-dev — dependency bumps (e.g. from Dependabot). chore(deps) cuts a patch; chore(deps-dev) does not release.
  • ci — CI / workflow changes (no release)
  • docs — documentation (no release)
  • repo — repo-wide / cross-cutting changes (no release)

Type → release mapping

Type / commit Release
breaking (! suffix or BREAKING CHANGE: footer) major
feat minor
fix patch
perf patch
chore(deps) patch
everything else (docs, ci, test, refactor, build, other chore) none

Agent version vs. non-agent scopes. The mapping above is the per-component rule. For the agent release specifically, both the backend scopes (device-discovery, network-discovery, snmp-discovery, gnmi-discovery, worker) and the no-release scopes (repo, ci, docs, deps-dev) are set to release: false, so even a releasing type on those scopes (e.g. feat(repo), fix(ci)) does not bump the agent version. Backend commits still appear in the aggregated agent release notes. The one exception is a backend breaking change (BREAKING CHANGE: footer), which semantic-release always treats as major; such a change bumps the agent to a major as well.

Keep PRs scoped

Prefer one component per PR so the scope is unambiguous. Cross-cutting work should use the repo scope or be split into per-component PRs.

Examples

  • feat(agent): add fleet-mode backend restart backoff
  • fix(agent): respect context cancellation in policy apply
  • docs(device-discovery): lead with supported driver and vendor counts
  • chore(deps): bump go.opentelemetry.io/otel/sdk
  • ci(repo): bump GitHub Actions to Node 24-compatible releases