Skip to content

CONTRIBUTING.adoc

Latest commit

 

History

History
139 lines (103 loc) · 4.39 KB

CONTRIBUTING.adoc

File metadata and controls

139 lines (103 loc) · 4.39 KB
Raw

Contributing — dicta-task

Table of Contents

Contributors work on the spine: the template every RSR repo is minted from. Changes here propagate to the whole estate at mint time, so the bar is the estate’s bar.

Local-dev setup

# Clone the repository
git clone https://github.com/hyperpolymath/dicta-task.git
cd dicta-task

# Using Guix (recommended for reproducibility)
guix shell -D -f build/guix.scm

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

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

Repository structure

The authoritative map is generated from the tree and checked in CI, so it cannot drift: docs/architecture/REPOSITORY-MAP.adoc. Regenerate it with just repo-map.

A hand-written tree used to live here. It described lib/, extensions/, plugins/ and spec/ directories that this repository has never contained, which is precisely why the map is now generated rather than typed.

How to contribute

Reporting bugs

Before reporting:

  1. Search existing issues.

  2. Check if it is 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

<type>(<scope>): <description>

[optional body]

[optional footer]

Cross-references

This root document exists because the estate docs gate (hyperpolymath/standards scripts/check-docs-presence.sh) requires CONTRIBUTING.md, CONTRIBUTING.adoc, or 3-practice/CONTRIBUTING.adoc at the repository root. The legacy copy at .github/CONTRIBUTING.md predates that gate; this document supersedes it.

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.