Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
145 lines (108 loc) · 4.24 KB

CONTRIBUTING.md

File metadata and controls

145 lines (108 loc) · 4.24 KB
Raw
# Clone the repository
git clone https://github.com/hyperpolymath/refugia.git
cd refugia

# Using Guix (recommended for reproducibility)
guix shell

# Or using toolbox/distrobox
toolbox create refugia-dev
toolbox enter refugia-dev
# Install dependencies manually

# Verify setup
just must-check    # Required repository invariants
just trust-verify  # Repository trust checks

Repository Structure

refugia/
├── 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.nix # Nix 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 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 if available
  2. Search existing issues and discussions
  3. Consider which perimeter the feature belongs to

When suggesting:

Use the feature request template 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:

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:

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. The ruleset checks every commit on the PR branch, not just the result, so one unsigned commit blocks the merge. Re-create such a branch with signed commits (git cherry-pick -S) and open a new PR. Rebase-merge replays commits unsigned and is disabled.