Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
96 lines (76 loc) · 2.7 KB

CONTRIBUTING.md

File metadata and controls

96 lines (76 loc) · 2.7 KB
Raw

Contributing to Sentinel

Thank you for contributing to Sentinel. We prioritize reliability, clear UX, and predictable APIs.

Before You Start

  • Check existing issues and pull requests to avoid duplicate work.
  • Open an issue first for large changes or API-affecting proposals.
  • Keep changes focused: one logical improvement per PR.

Local Setup

  1. Fork and clone your fork: 
    git clone https://github.com/<your-user>/sentinel.git
cd sentinel
  2. Create a feature branch: 
    git checkout -b feat/short-descriptive-name

Development Workflow

  • Implement changes with minimal complexity and clear behavior.
  • Add or update tests alongside code changes.
  • Run the quality pipeline before opening or updating a PR: 
    make ci-fast
  • For broader verification, also run: 
    make ci-full
  • Targeted test layers are available when iterating: 
    make test-unit
make test-contract
make test-integration
make test-e2e
make test-perf
  • For tmux terminal rendering changes, run the browser smoke. It starts a temporary Sentinel server, creates a real tmux session, attaches through a real browser, validates desktop and mobile terminal pixels, and checks runtime stability metrics: 
    make smoke-client-terminal
  • For changes that can affect long terminal sessions, also run the heavier soak: 
    make smoke-client-terminal-soak
    These targets require agent-browser, curl, go, npm, python3, and tmux on the local machine.
  • make ci remains the full local gate and should pass before merge.

Coding and Testing Expectations

  • Follow idiomatic Go and existing project conventions.
  • Prefer explicit, readable APIs over clever abstractions.
  • Keep tests deterministic and focused.
  • Avoid unnecessary dependencies.
  • Update docs when commands, APIs, or behavior change.

Commit Message Guidelines

Use Conventional Commits to keep automated versioning and changelogs consistent. Use concise, imperative commits. Preferred prefixes:

  • feat: add ...
  • fix: handle ...
  • test: cover ...
  • chore: ...
  • ci: ...
  • docs: ...

Breaking changes:

  • feat!: ... or fix!: ...
  • include BREAKING CHANGE: in the commit body when needed.

Pull Request Guidelines

  • Describe what changed, why, and how it was validated.
  • Link related issues (for example, Closes #42).
  • Include examples or output snippets when behavior changes.
  • Call out breaking changes clearly.

Code Review

Maintainers review PRs as time permits. Please keep discussions technical, objective, and collaborative.

License

By contributing, you agree that your contributions are licensed under the project LICENSE.