Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
138 lines (100 loc) · 4.34 KB

CONTRIBUTING.md

File metadata and controls

138 lines (100 loc) · 4.34 KB
Raw

Clone the repository

git clone https://github.com/hyperpolymath/conative-gating.git cd conative-gating

Using Guix (recommended for reproducibility)

guix develop

Or using toolbox/distrobox

toolbox create conative-gating-dev toolbox enter conative-gating-dev

Install dependencies manually

Verify setup

just check # or: cargo check / mix compile / etc. just test # Run test suite

Repository Structure

conative-gating/
├── src/ # Source code (Perimeter 1-2)
├── lib/ # Library code (Perimeter 1-2)
├── extensions/ # Extensions (Perimeter 2)
├── plugins/ # Plugins (Perimeter 2)
├── tools/ # Tooling (Perimeter 2)
├── docs/ # Documentation (Perimeter 3)
│   ├── architecture/ # ADRs, specs (Perimeter 2)
│   └── proposals/ # RFCs (Perimeter 3)
├── examples/ # Examples (Perimeter 3)
├── spec/ # Spec tests (Perimeter 3)
├── tests/ # Test suite (Perimeter 2-3)
├── .well-known/ # Protocol files (Perimeter 1-3)
├── .github/ # GitHub config (Perimeter 1)
│   ├── CONTRIBUTING.md # This file
│   ├── ISSUE_TEMPLATE/
│   └── workflows/
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── GOVERNANCE.md
├── LICENSE
├── MAINTAINERS.md
├── README.adoc
├── SECURITY.md
├── flake.guix # Guix flake (Perimeter 1)
└── Justfile # Task runner (Perimeter 1)

---

How to Contribute

Reporting Bugs

**Before reporting**:
1. Search existing issues
2. Check if it's already fixed in `main`
3. Determine which perimeter the bug affects

**When reporting**:

Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include:

- Clear, descriptive title
- Environment details (OS, versions, toolchain)
- Steps to reproduce
- Expected vs actual behaviour
- Logs, screenshots, or minimal reproduction

Suggesting Features

**Before suggesting**:
1. Check the [roadmap](ROADMAP.md) if available
2. Search existing issues and discussions
3. Consider which perimeter the feature belongs to

**When suggesting**:

Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include:

- Problem statement (what pain point does this solve?)
- Proposed solution
- Alternatives considered
- Which perimeter this affects

Your First Contribution

Look for issues labelled:

- [`good first issue`](https://github.com/hyperpolymath/conative-gating/labels/good%20first%20issue) — Simple Perimeter 3 tasks
- [`help wanted`](https://github.com/hyperpolymath/conative-gating/labels/help%20wanted) — Community help needed
- [`documentation`](https://github.com/hyperpolymath/conative-gating/labels/documentation) — Docs improvements
- [`perimeter-3`](https://github.com/hyperpolymath/conative-gating/labels/perimeter-3) — Community sandbox scope

---

Development Workflow

Branch Naming

docs/short-description # Documentation (P3) test/what-added # Test additions (P3) feat/short-description # New features (P2) fix/issue-number-description # Bug fixes (P2) refactor/what-changed # Code improvements (P2) security/what-fixed # Security fixes (P1-2)

Commit Messages

We follow [Conventional Commits](https://www.conventionalcommits.org/):

type(scope): description

Body: what changed and why.

Footer: issue reference, e.g. Closes #123 [optional body]

[optional footer]

Signed commits

Every commit that reaches the default branch must be signed; a ruleset refuses unsigned pushes. Estate policy: SIGNING-POLICY.

  • People and interactive agents sign with an SSH key registered on GitHub as a signing key (gpg.format=ssh, user.signingkey=<key>.pub, commit.gpgsign=true). The committer email must be verified on that account.
  • Apps, bots and workflows never git push local commits. They write through the API (createCommitOnBranch or the estate signed-push action) so that GitHub signs each commit.
  • Merge PRs with squash. GitHub signs the resulting squash commit, and the PR's individual commits do not reach the protected default branch. Contributors should still sign their own commits as required by estate policy. Rebase-merge replays commits unsigned and is disabled.