From b78063ac05bd920c448175d32ce7692e91e4f6c0 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 09:05:53 +0000 Subject: [PATCH] refactor(root): relocate the contributing guide into .github/ The estate canonical location is .github/CONTRIBUTING.md, which GitHub auto-discovers; the root copy is removed and references are updated in the same change. * .github/CONTRIBUTING.md (new) * CONTRIBUTING.adoc (deleted) * MAINTAINERS.adoc --- .github/CONTRIBUTING.md | 123 ++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.adoc | 129 ---------------------------------------- MAINTAINERS.adoc | 2 +- 3 files changed, 124 insertions(+), 130 deletions(-) create mode 100644 .github/CONTRIBUTING.md delete mode 100644 CONTRIBUTING.adoc diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..63da749 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,123 @@ +# Contributing + +Thanks for your interest. + +This repo’s core deliverable is the **FFI contract** (the C ABI in +`include/bebop_v_ffi.h`). Implementations (Zig, Rust, …) must not change +that contract casually. + +## AI Assistance Policy + +AI assistance is welcome for design and documentation, but must not be +treated as an authoritative agent that directly mutates ABI, build +logic, or serialization. + +See `META.scm` for governance principles. + +’’’’’ + +## Getting Started + +# Clone the repository + +git clone cd bebop-ffi + +# Using Guix (recommended for reproducibility) + +guix develop + +# Or using toolbox/distrobox + +toolbox create bebop-v-ffi-dev toolbox enter bebop-v-ffi-dev \# Install +dependencies manually + +# Verify setup + +just check \# or: cargo check / mix compile / etc. just test \# Run test +suite + + + ### Repository Structure + +bebop-ffi/ ├── implementations/ \# Implementation code (Zig, Rust) +(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) │ ├── ISSUE_TEMPLATE/ │ └── workflows/ ├── +CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md \# This file ├── +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/bebop-v-ffi/labels/good%20first%20issue) — Simple Perimeter 3 tasks + - [`help wanted`](https://github.com/hyperpolymath/bebop-v-ffi/labels/help%20wanted) — Community help needed + - [`documentation`](https://github.com/hyperpolymath/bebop-v-ffi/labels/documentation) — Docs improvements + - [`perimeter-3`](https://github.com/hyperpolymath/bebop-v-ffi/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/): + +(): + +\[optional body\] + +\[optional footer\] diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 083a64a..0000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,129 +0,0 @@ -== Contributing - -Thanks for your interest. - -This repo’s core deliverable is the *FFI contract* (the C ABI in -`+include/bebop_v_ffi.h+`). Implementations (Zig, Rust, …) must not -change that contract casually. - -=== AI Assistance Policy - -AI assistance is welcome for design and documentation, but must not be -treated as an authoritative agent that directly mutates ABI, build -logic, or serialization. - -See `+META.scm+` for governance principles. - -''''' - -=== Getting Started - -== Clone the repository - -git clone https://github.com/hyperpolymath/bebop-ffi.git cd bebop-ffi - -== Using Guix (recommended for reproducibility) - -guix develop - -== Or using toolbox/distrobox - -toolbox create bebop-v-ffi-dev toolbox enter bebop-v-ffi-dev # Install -dependencies manually - -== Verify setup - -just check # or: cargo check / mix compile / etc. just test # Run test -suite - -.... - -### Repository Structure -.... - -bebop-ffi/ ├── implementations/ # Implementation code (Zig, Rust) -(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) │ ├── ISSUE_TEMPLATE/ │ └── workflows/ ├── -CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md # This file ├── -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/bebop-v-ffi/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/bebop-v-ffi/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/bebop-v-ffi/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/bebop-v-ffi/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/): -.... - -(): - -{empty}[optional body] - -{empty}[optional footer] diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc index daf8a78..97edfcd 100644 --- a/MAINTAINERS.adoc +++ b/MAINTAINERS.adoc @@ -62,4 +62,4 @@ For questions about project governance: * link:GOVERNANCE.adoc[Governance Model] * link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] +* link:.github/CONTRIBUTING.md[Contributing Guide]