Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
312 lines (243 loc) · 13.9 KB

CONTRIBUTING.md

File metadata and controls

312 lines (243 loc) · 13.9 KB

This document provides an overview for all who contribute to NeonConductor.

Branch Gate Strategy

NeonConductor uses three primary branches:

  • dev: integration branch for day-to-day work
  • prev: staging branch for beta candidates
  • main: stable branch for production releases

Expected promotion path: dev -> prev -> main.

Release Channel Risk Notices

Caution

Alpha channel (dev tags: vX.Y.Z-alpha.N) Alpha builds are for evaluation and testing. They can include unfinished features, weaker stability guarantees, and temporary security hardening gaps while development is in progress. Do not use alpha builds for critical workloads or sensitive data handling.

Warning

Beta channel (prev tags: vX.Y.Z-beta.N) Beta builds are closer to stable, but still pre-release. Regressions, breaking behavior changes, and late fixes are still possible. Use beta when you want early validation before stable.

Note

Stable channel (main) Stable builds are the most reliable channel in this project. Bugs and regressions can still occur, but the likelihood is lower than alpha and beta.

Automation by Event

  • PR to dev, prev, or main touching Project/**: review and checks run.
  • PR title validation runs only for PRs targeting dev and enforces semantic format: type: short lowercase subject or type(scope): short lowercase subject.
  • PR type labels are auto-managed from the PR title (including type: breaking when ! is used).
  • New issues and PRs are auto-labeled with status: needs-triage when no status:* label exists yet.
  • PR to dev, prev, or main touching Project/**: Changeset Check runs.
  • Changeset Check validates non-doc changes. Docs-only changes in Project (for example markdown/docs paths) are skipped.
  • Changeset Check comment includes changeset file inventories for base vs PR snapshots, PR delta (A/M/D/R), and total bump math (base, PR-only, post-merge).
  • Changes in Project/.changeset/** always trigger changeset validation.
  • Merged same-repo PR to main touching Project/.changeset/** runs Changeset Version, unless the PR is a release wrapper or cleanup-sync wrapper.
  • Merged PR to main that changes both Project/package.json and Project/CHANGELOG.md: stable build workflow runs and publishes.
  • Merged same-repo hotfix PRs trigger adjacent-hop lane sync PRs so the fix can move through the remaining long-lived branches.
  • After stable consumes a hotfix changeset on main, selective cleanup PRs remove only that consumed hotfix changeset from prev and dev when the file identity still matches.
  • Push tag matching v*-alpha.* or v*-beta.*: prerelease build workflow runs and publishes.
  • Create prerelease tags only when a publicly updatable build is needed: alpha (dev) can be cut more frequently, while beta (prev) should be cut only when it meaningfully supports release validation.
  • Pre-release branch guard: alpha tag commit must be contained in dev, beta tag commit must be contained in prev.

Version Field Ownership (Project/package.json)

  • Do not manually edit Project/package.json version in normal feature/fix/chore/docs PRs.
  • Pre-release workflows inject the tagged version at build time using --config.extraMetadata.version.
  • Stable version bumps are generated by the Changeset Version workflow and merged as a version PR.
  • Any manually edited version value outside the release automation flow should be treated as invalid and reverted.

Updater Behavior in Development

  • In local development mode, updater and release-channel switch features are disabled by default.
  • This is expected behavior: update checks and channel downloads are intended for packaged builds.
  • For explicit local updater testing only, set UPDATER_ENABLED=1 before launching the app.
  • Release automation publishes channel metadata to GitHub Pages from the gh-pages branch under updates/stable/, updates/beta/, and updates/alpha/.
  • Before testing packaged auto-updates, enable GitHub Pages to serve from the gh-pages branch.

Note

The window resize dimension overlay in development is caused by open DevTools, not by app window/title bar logic.

Direct Access Contributor Rules

If you are an invited contributor with direct repo access:

  • Open normal work PRs to dev.
  • Use branch names in this format: username/type/short-description.
  • Keep short-description lowercase kebab-case.
  • Use username/hotfix/short-description when the work must target dev, prev, or main directly as a release hotfix.
  • Direct hotfix targeting for prev or main is reserved for same-repo contributors with write access.
  • hotfix is a branch-routing type only. Keep PR titles on the existing semantic type: format.
  • Use type=proto for demo/testing/spike branches.
  • proto branches are usually not merged.

Allowed type values:

  • build

  • ci

  • chore

  • docs

  • feat

  • fix

  • hotfix

  • perf

  • refactor

  • test

  • proto

Examples:

  • neonsy/feat/onboarding-flow
  • neonsy/fix/window-crash-on-startup
  • neonsy/hotfix/windows-installer-regression
  • neonsy/chore/update-eslint-config
  • neonsy/docs/release-process
  • neonsy/proto/new-sidebar-concept

Fork PRs are currently outside the enforced branch-flow automation and may be triaged manually. Request invited access first if you need the normal branch-flow path.

PR Title and Breaking Marker Rules

PR titles must follow:

  • type: short lowercase subject
  • type(scope): short lowercase subject

Allowed PR title type values:

  • build
  • ci
  • chore
  • docs
  • feat
  • fix
  • perf
  • refactor
  • revert
  • test
  • ui-ux

Optional PR title scope values:

  • Any lowercase kebab-case scope is allowed (examples: api, frontend, backend, electron, provider, agent, tools, infra, deps).

Breaking marker behavior:

  • Use ! before : to mark breaking intent.
  • Example: feat(api)!: remove legacy config format
  • Automation applies labels: type: feature and type: breaking.
  • ! affects release-note categorization only. Changesets still determine semver/version bump behavior.

Tag Security

  • Tag permissions are enforced in GitHub repository rulesets, not by this repo's workflows.
  • Configure a tag ruleset for v* and restrict create/update/delete to release maintainers only.
  • External users should not have bypass permissions for tag rulesets.

Changesets and Release Flow (Step-by-Step)

  1. Create a feature/fix/docs/chore PR to dev.
  • If the PR changes non-doc files in Project/**, include a changeset in Project/.changeset/.
  • Docs-only changes in Project/** (markdown/docs paths) are exempt.
  • No stable release happens from dev PRs.

Hotfix exception:

  • A same-repo contributor with write access may open username/hotfix/short-description directly to dev, prev, or main.
  • Any non-doc hotfix must include a changeset even when it targets prev or main directly.
  • The hotfix changeset is treated as stable-release material and must be consumed exactly once on main.
  • Automation opens adjacent-hop sync PRs so the hotfix can move across the other long-lived lanes.
  • After main consumes the hotfix changeset in the stable version flow, automation selectively cleans that consumed changeset from prev and dev without touching unrelated promotion-flow changesets.
  1. Publish alpha from dev.
  • Create and push an alpha tag: vX.Y.Z-alpha.N.
  • Do this only when a publicly updatable build is needed. On dev, alpha tags can be created more often during active testing/iteration.
  • The tagged commit must be in dev.
  • Prerelease workflow builds and publishes for all target OSes.
  1. Promote to prev.
  • Open PR from dev to prev.
  • If Project/** changed, Changeset Check runs on the PR.
  • Docs-only changes are skipped by the check.
  • .changeset and non-doc code/config changes are validated.
  1. Publish beta from prev.
  • Create and push a beta tag: vX.Y.Z-beta.N.
  • Do this only when a publicly updatable build is needed. On prev, cut beta tags only when it makes release-validation sense.
  • The tagged commit must be in prev.
  • Prerelease workflow builds and publishes for all target OSes.
  1. Promote to main.
  • Open PR from prev to main.
  • If Project/** changed, Changeset Check runs on this PR too.
  • Docs-only changes are skipped by the check.
  • .changeset and non-doc code/config changes are validated.
  1. Merge a same-repo PR into main with pending .changeset files.
  • Changeset Version workflow runs on merged PR close event targeting main.
  • This includes normal prev -> main promotions, direct hotfix -> main merges, and lane-sync PRs that carry a hotfix changeset into main.
  • It runs changeset version and opens or updates a version PR.
  1. Merge the version PR.
  • This updates Project/package.json and Project/CHANGELOG.md.
  • The stable build workflow detects those file changes and publishes the stable release.

Versioning notes:

  • For stable releases, do not manually edit version in Project/package.json. It is owned by release automation (the Changeset Version workflow and version PRs).
  • For alpha/beta prereleases, the tag version is injected during publish via --config.extraMetadata.version.
  • A direct hotfix -> main merge only becomes a stable release when it includes a changeset and the generated stable version PR is merged.

Release Notes Behavior

  • GitHub release-note categories are configured in .github/release.yml.
  • Release note categories are driven by type:* labels.
  • Each channel uses a single same-channel delta section:
    • alpha: Changes since previous alpha
    • beta: Changes since previous beta (entries include merged PRs targeting dev and direct hotfix/sync entries targeting prev, filtered to PR merge commits contained in the tagged beta commit ancestry)
    • stable: Changes since previous stable
  • Promotion wrapper PRs (dev -> prev, prev -> main) are excluded from grouped release-note entries.
  • Lane-sync wrappers and hotfix cleanup wrappers are excluded from grouped release-note entries, but lane-sync wrappers can resolve back to the origin hotfix PR so the fix still appears once in release notes.
  • When no entries are resolved, release notes keep the custom no-entry line, generated fallback blocks (including Full Changelog) are not injected.
  • Custom channel header text is preserved for alpha, beta, and stable notes.

Labels Guide

Automation / CI Status

Label Title When to use it
ci: failing CI failed on default checks
ci: flaky Intermittent CI failures observed
ci: blocked CI cannot run due to missing secrets or env
ci: passing All required checks passing
automation: dependabot Automated PR opened by Dependabot
automation: lane-sync Automation PR carrying a hotfix into another release lane
automation: changeset-cleanup Automation PR removing hotfix changesets after stable consumption
ignore-for-release Exclude PR from generated release notes

Release Routing

Label Title When to use it
release: hotfix Direct-lane hotfix PR intended for expedited release propagation

Issue Types

Label Title When to use it
type: bug Defect or regression
type: feature New user-facing capability
type: breaking Breaking change in behavior or interface
type: enhancement Improvement to existing behavior
type: chore Maintenance or refactor
type: build Build system changes
type: ci CI workflow or automation changes
type: docs Documentation-only change
type: dependencies Dependency updates or lockfile changes
type: refactor Code structure changes without behavior change
type: test Tests added or updated
type: performance Performance or cost improvements
type: ui-ux UI, UX, interaction, or visual design changes
type: style Formatting or style-only changes
type: revert Reverts a previous change
type: question Clarification or discussion
type: security Security-related issue

PR Scope / Areas

Label Title When to use it
scope: agent-core Agent lifecycle, state, prompts, policies
scope: orchestration Planning, routing, scheduling, coordination
scope: tools Tool registry, execution, adapters
scope: memory Memory store, embeddings, retrieval
scope: ui Desktop UI and interaction surfaces
scope: api Internal or external APIs
scope: integrations External services and providers
scope: infra Build, CI, deployment, scripts
scope: docs Docs specific to a PR’s area
scope: tests Test-only changes
scope: dependencies Package updates and lockfiles

Priority / Severity

Label Title When to use it
priority: p0 Must fix immediately
priority: p1 High priority, near-term
priority: p2 Normal priority
priority: p3 Low priority
severity: s0 System-wide or data-loss impact
severity: s1 Major user impact
severity: s2 Minor or localized impact

Status

Label Title When to use it
status: needs-triage New, unreviewed
status: triaged Initial triage completed
status: noted Reviewed by a contributor
status: confirmed Issue/behavior confirmed by maintainers
status: needs-reproduction Needs a reliable reproduction case
status: reproducible Reliable reproduction steps captured
status: needs-info Blocked on reporter details
status: accepted Approved to work on
status: in-progress Actively being worked
status: blocked External dependency or hard block
status: on-hold Paused pending decision or timing
status: ready-for-review Implementation done, needs review
status: done Completed and verified
status: duplicate Duplicate of an existing issue
status: wontfix Closed without planned changes