From bd2d82fd53df699b970ba7ba8864b3befd63c706 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 08:59:18 +0000 Subject: [PATCH] refactor(root): move root artefacts to their canonical locations Applies the estate root-shape rollout: files that are not root-level by necessity move to where their tooling and the estate canon expect them, and every reference to them is updated in the same change. * .machine_readable/root-allow.txt * RSR_OUTLINE.adoc * build/guix.scm (from guix.scm) -> build/guix.scm * .github/CONTRIBUTING.md (new) * CONTRIBUTING.adoc (deleted) * FUNDING.yml * Justfile Verified with `git apply --check` against current main before committing; no behaviour change intended, the Justfile entry points keep working. --- .github/CONTRIBUTING.md | 458 +++++++++++++++++++++++++++++++ .machine_readable/root-allow.txt | 1 + CONTRIBUTING.adoc | 382 -------------------------- FUNDING.yml | 2 +- Justfile | 6 +- RSR_OUTLINE.adoc | 2 +- guix.scm | 28 -- 7 files changed, 464 insertions(+), 415 deletions(-) create mode 100644 .github/CONTRIBUTING.md delete mode 100644 CONTRIBUTING.adoc delete mode 100644 guix.scm diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..f68eb5b --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,458 @@ +# Contributing to aggregate-library + +Thank you for your interest in contributing to the aggregate-library +(aLib) project! This document provides guidelines for contributing to +this cross-language Common Library specification. + +## Code of Conduct + +This project adheres to a Code of Conduct (see +[CODE_OF_CONDUCT.adoc](CODE_OF_CONDUCT.adoc)). By participating, you +agree to uphold this code. Please report unacceptable behavior to the +maintainers. + +## Getting Started + +### Prerequisites + +- Git for version control + +- Text editor or IDE + +- Familiarity with at least one of the seven target languages + +- Understanding of specification writing (helpful but not required) + +### Fork and Clone + +``` bash +# Fork on GitHub/GitLab, then clone your fork +git clone https://github.com/YOUR-USERNAME/aggregate-library.git +cd aggregate-library + +# Add upstream remote +git remote add upstream https://github.com/Hyperpolymath/aggregate-library.git +``` + +### Repository Structure + + aggregate-library/ + ├── specs/ # Operation specifications + │ ├── arithmetic/ # Math operations + │ ├── comparison/ # Comparison operations + │ ├── logical/ # Boolean logic + │ ├── string/ # String operations + │ ├── collection/ # Collection operations + │ └── conditional/ # Control flow + ├── SPEC_FORMAT.md # Specification format guide + ├── README.adoc # Project overview + └── CLAUDE.md # AI assistant guidelines + +## Contribution Types + +### Specification Improvements + +- Clarify ambiguous wording + +- Add missing edge cases + +- Improve behavioral semantics + +- Enhance property descriptions + +### Test Case Additions + +- Add more comprehensive test cases + +- Cover additional edge cases + +- Add test cases for different type combinations + +- Improve test descriptions + +### Documentation + +- Improve README or SPEC_FORMAT + +- Fix typos and grammar + +- Add examples and usage guides + +- Translate documentation + +### New Operations (Rare) + +- Propose new operations for Common Library + +- Must exist across ALL seven languages + +- Requires community discussion first + +- High bar for acceptance + +## Tri-Perimeter Contribution Framework (TPCF) + +This project follows the TPCF model with three contribution perimeters: + +### Perimeter 3: Community Sandbox (Current) + +- **Access**: Open to all contributors + +- **Scope**: Documentation, test cases, specification clarifications + +- **Review**: Standard pull request review + +- **Timeline**: 3-7 days for most contributions + +#### Requirements + +- Read and follow this CONTRIBUTING guide + +- Sign Developer Certificate of Origin (DCO) + +- Pass automated validation checks + +- Receive maintainer approval + +### Perimeter 2: Trusted Contributors (Future) + +- **Access**: Invitation-only after sustained contributions + +- **Scope**: Core specification changes, new operations + +- **Requirements**: + + - 6+ months of quality contributions + + - Deep understanding of specification methodology + + - Maintainer nomination + +### Perimeter 1: Maintainer Core + +- **Access**: Maintainers only + +- **Scope**: Governance decisions, release management, security + +- **Process**: See [GOVERNANCE.adoc](GOVERNANCE.adoc) + +## Development Process + +### 1. Create an Issue First + +Before starting work, create an issue describing: + +- What you want to change + +- Why it’s needed + +- Proposed approach + +This allows for discussion before you invest time. + +### 2. Create a Branch + +``` bash +# Update your fork +git fetch upstream +git checkout main +git merge upstream/main + +# Create feature branch +git checkout -b feat/your-feature-name +``` + +Branch prefixes: + +- `feat/` - New features or operations + +- `fix/` - Bug fixes or corrections + +- `docs/` - Documentation changes + +- `test/` - Test case additions + +- `refactor/` - Restructuring without behavior changes + +### 3. Make Changes + +Follow the Specification Guidelines below. + +### 4. Add SPDX Headers + +All new specification files must include SPDX headers: + +``` markdown + + +``` + +### 5. Test Your Changes + +``` bash +# Validate specifications +just validate + +# Run all tests +just test + +# Check documentation +just docs + +# Full compliance check +just check +``` + +### 6. Commit Your Changes + +Use conventional commit messages: + + type(scope): subject + + body + + footer + +**Types:** + +- `feat`: New features + +- `fix`: Bug fixes + +- `docs`: Documentation changes + +- `test`: Test additions + +- `refactor`: Code restructuring + +- `chore`: Maintenance tasks + +**Example:** + + feat(arithmetic): add edge case for add operation + + Added test case for very large number addition to clarify + overflow behavior expectations. + + Closes #123 + Signed-off-by: Your Name + +### 7. Sign Your Commits (DCO) + +We use the Developer Certificate of Origin (DCO): + +``` bash +git commit -s -m "feat: your commit message" +``` + +Or add to commit message: + + Signed-off-by: Your Name + +### 8. Push and Create Pull Request + +``` bash +git push origin feat/your-feature-name +``` + +Then create a pull request on GitHub/GitLab. + +## Specification Guidelines + +### Writing Specifications + +Follow the format defined in [SPEC_FORMAT.md](SPEC_FORMAT.md): + +1. **Interface Signature** + + - Use abstract, language-agnostic syntax + + - Specify input and output types clearly + + + +1. **Behavioral Semantics** + + - Write clear, unambiguous descriptions + + - Include mathematical properties where applicable + + - Document all edge cases + + - Mark implementation-defined behaviors + + + +1. **Executable Test Cases** + + - Use YAML format + + - Include diverse inputs + + - Cover edge cases + + - Write descriptive test descriptions + +### Quality Standards + +- **Clarity**: Specifications must be understandable by implementers + +- **Completeness**: Cover all important behaviors and edge cases + +- **Consistency**: Use consistent terminology across specifications + +- **Testability**: Provide concrete, executable test cases + +- **Language-Agnostic**: Avoid language-specific assumptions + +### What to Avoid + +- ❌ Language-specific syntax or terminology + +- ❌ Implementation details (memory management, performance) + +- ❌ Operations that don’t exist in all seven languages + +- ❌ Ambiguous or vague descriptions + +- ❌ Untestable requirements + +## Pull Request Process + +### Before Submitting + +- [ ] Read SPEC_FORMAT.md + +- [ ] Follow specification guidelines + +- [ ] Write clear commit messages + +- [ ] Sign commits (DCO) + +- [ ] Reference related issues + +- [ ] Self-review your changes + +- [ ] Check for typos and formatting + +- [ ] Run `just` `check` + +### PR Description Template + +``` markdown +## Description +[Brief description of changes] + +## Motivation +[Why this change is needed] + +## Changes +- [List of specific changes] +- [With bullet points] + +## Testing +[How you verified the changes] + +## Related Issues +Closes #[issue number] + +## Checklist +- [ ] Follows SPEC_FORMAT.md +- [ ] Test cases included +- [ ] Documentation updated +- [ ] Commit messages follow conventions +- [ ] Commits signed (DCO) +- [ ] `just check` passes +``` + +### Review Process + +1. **Automated Checks**: Must pass + +2. **Maintainer Review**: At least one maintainer approval required + +3. **Community Feedback**: Allow time for community input (3-7 days for + major changes) + +4. **Revisions**: Address reviewer feedback + +5. **Merge**: Maintainer will merge when ready + +### Review Timeline + +- **Minor changes** (typos, formatting): 1-3 days + +- **Test additions**: 3-7 days + +- **Specification changes**: 1-2 weeks + +- **New operations**: 1-3 months (requires extensive discussion) + +## Communication + +### Where to Discuss + +- **GitHub/GitLab Issues**: Bug reports, feature requests, discussions + +- **Pull Requests**: Code review and specification changes + +- **Email**: security@\[project-domain\] for security issues only + +### Response Times + +We aim to respond within: + +- **Security issues**: 72 hours + +- **Bug reports**: 1 week + +- **Feature requests**: 2 weeks + +- **Pull requests**: 1 week for initial review + +### Getting Help + +1. Read SPEC_FORMAT.md and existing specifications + +2. Search existing issues and PRs + +3. Create a new issue if you can’t find answers + +4. Be patient and respectful + +## Recognition + +Contributors are recognized in multiple ways: + +- Listed in [MAINTAINERS.md](MAINTAINERS.md) (for significant + contributions) + +- Mentioned in [CHANGELOG.md](CHANGELOG.md) + +- Credited in release notes + +- Acknowledged in `.well-known/humans.txt` + +## License + +By contributing, you agree that your contributions will be licensed +under the project’s dual license (MIT / Palimpsest v0.8). See +[LICENSE.txt](LICENSE.txt) for details. + +All contributions must include appropriate SPDX headers. + +## Questions? + +If you have questions about contributing, please: + +1. Read this guide thoroughly + +2. Check existing issues and discussions + +3. Create a new issue with the `question` label + +4. Be patient and respectful + +Thank you for contributing to aggregate-library! 🎉 + +------------------------------------------------------------------------ diff --git a/.machine_readable/root-allow.txt b/.machine_readable/root-allow.txt index ceb2b98..3b3fccb 100644 --- a/.machine_readable/root-allow.txt +++ b/.machine_readable/root-allow.txt @@ -1 +1,2 @@ CLAUDE.md +build/ # build orchestration: guix.scm relocated here (canon 1.2.1 guix-primary template_ref = "build/") diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 455c742..0000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,382 +0,0 @@ -= Contributing to aggregate-library -:toc: left -:toclevels: 3 -:sectnums: - -Thank you for your interest in contributing to the aggregate-library (aLib) project! This document provides guidelines for contributing to this cross-language Common Library specification. - -== Code of Conduct - -This project adheres to a Code of Conduct (see link:CODE_OF_CONDUCT.adoc[]). By participating, you agree to uphold this code. Please report unacceptable behavior to the maintainers. - -== Getting Started - -=== Prerequisites - -* Git for version control -* Text editor or IDE -* Familiarity with at least one of the seven target languages -* Understanding of specification writing (helpful but not required) - -=== Fork and Clone - -[source,bash] ----- -# Fork on GitHub/GitLab, then clone your fork -git clone https://github.com/YOUR-USERNAME/aggregate-library.git -cd aggregate-library - -# Add upstream remote -git remote add upstream https://github.com/Hyperpolymath/aggregate-library.git ----- - -=== Repository Structure - -[source] ----- -aggregate-library/ -├── specs/ # Operation specifications -│ ├── arithmetic/ # Math operations -│ ├── comparison/ # Comparison operations -│ ├── logical/ # Boolean logic -│ ├── string/ # String operations -│ ├── collection/ # Collection operations -│ └── conditional/ # Control flow -├── SPEC_FORMAT.md # Specification format guide -├── README.adoc # Project overview -└── CLAUDE.md # AI assistant guidelines ----- - -== Contribution Types - -=== Specification Improvements - -* Clarify ambiguous wording -* Add missing edge cases -* Improve behavioral semantics -* Enhance property descriptions - -=== Test Case Additions - -* Add more comprehensive test cases -* Cover additional edge cases -* Add test cases for different type combinations -* Improve test descriptions - -=== Documentation - -* Improve README or SPEC_FORMAT -* Fix typos and grammar -* Add examples and usage guides -* Translate documentation - -=== New Operations (Rare) - -* Propose new operations for Common Library -* Must exist across ALL seven languages -* Requires community discussion first -* High bar for acceptance - -== Tri-Perimeter Contribution Framework (TPCF) - -This project follows the TPCF model with three contribution perimeters: - -=== Perimeter 3: Community Sandbox (Current) - -* **Access**: Open to all contributors -* **Scope**: Documentation, test cases, specification clarifications -* **Review**: Standard pull request review -* **Timeline**: 3-7 days for most contributions - -==== Requirements - -* Read and follow this CONTRIBUTING guide -* Sign Developer Certificate of Origin (DCO) -* Pass automated validation checks -* Receive maintainer approval - -=== Perimeter 2: Trusted Contributors (Future) - -* **Access**: Invitation-only after sustained contributions -* **Scope**: Core specification changes, new operations -* **Requirements**: -** 6+ months of quality contributions -** Deep understanding of specification methodology -** Maintainer nomination - -=== Perimeter 1: Maintainer Core - -* **Access**: Maintainers only -* **Scope**: Governance decisions, release management, security -* **Process**: See link:GOVERNANCE.adoc[] - -== Development Process - -=== 1. Create an Issue First - -Before starting work, create an issue describing: - -* What you want to change -* Why it's needed -* Proposed approach - -This allows for discussion before you invest time. - -=== 2. Create a Branch - -[source,bash] ----- -# Update your fork -git fetch upstream -git checkout main -git merge upstream/main - -# Create feature branch -git checkout -b feat/your-feature-name ----- - -Branch prefixes: - -* `feat/` - New features or operations -* `fix/` - Bug fixes or corrections -* `docs/` - Documentation changes -* `test/` - Test case additions -* `refactor/` - Restructuring without behavior changes - -=== 3. Make Changes - -Follow the Specification Guidelines below. - -=== 4. Add SPDX Headers - -All new specification files must include SPDX headers: - -[source,markdown] ----- - - ----- - -=== 5. Test Your Changes - -[source,bash] ----- -# Validate specifications -just validate - -# Run all tests -just test - -# Check documentation -just docs - -# Full compliance check -just check ----- - -=== 6. Commit Your Changes - -Use conventional commit messages: - -[source] ----- -type(scope): subject - -body - -footer ----- - -**Types:** - -* `feat`: New features -* `fix`: Bug fixes -* `docs`: Documentation changes -* `test`: Test additions -* `refactor`: Code restructuring -* `chore`: Maintenance tasks - -**Example:** - -[source] ----- -feat(arithmetic): add edge case for add operation - -Added test case for very large number addition to clarify -overflow behavior expectations. - -Closes #123 -Signed-off-by: Your Name ----- - -=== 7. Sign Your Commits (DCO) - -We use the Developer Certificate of Origin (DCO): - -[source,bash] ----- -git commit -s -m "feat: your commit message" ----- - -Or add to commit message: - -[source] ----- -Signed-off-by: Your Name ----- - -=== 8. Push and Create Pull Request - -[source,bash] ----- -git push origin feat/your-feature-name ----- - -Then create a pull request on GitHub/GitLab. - -== Specification Guidelines - -=== Writing Specifications - -Follow the format defined in link:SPEC_FORMAT.md[]: - -. **Interface Signature** -** Use abstract, language-agnostic syntax -** Specify input and output types clearly - -. **Behavioral Semantics** -** Write clear, unambiguous descriptions -** Include mathematical properties where applicable -** Document all edge cases -** Mark implementation-defined behaviors - -. **Executable Test Cases** -** Use YAML format -** Include diverse inputs -** Cover edge cases -** Write descriptive test descriptions - -=== Quality Standards - -* **Clarity**: Specifications must be understandable by implementers -* **Completeness**: Cover all important behaviors and edge cases -* **Consistency**: Use consistent terminology across specifications -* **Testability**: Provide concrete, executable test cases -* **Language-Agnostic**: Avoid language-specific assumptions - -=== What to Avoid - -* ❌ Language-specific syntax or terminology -* ❌ Implementation details (memory management, performance) -* ❌ Operations that don't exist in all seven languages -* ❌ Ambiguous or vague descriptions -* ❌ Untestable requirements - -== Pull Request Process - -=== Before Submitting - -* [ ] Read SPEC_FORMAT.md -* [ ] Follow specification guidelines -* [ ] Write clear commit messages -* [ ] Sign commits (DCO) -* [ ] Reference related issues -* [ ] Self-review your changes -* [ ] Check for typos and formatting -* [ ] Run `just check` - -=== PR Description Template - -[source,markdown] ----- -## Description -[Brief description of changes] - -## Motivation -[Why this change is needed] - -## Changes -- [List of specific changes] -- [With bullet points] - -## Testing -[How you verified the changes] - -## Related Issues -Closes #[issue number] - -## Checklist -- [ ] Follows SPEC_FORMAT.md -- [ ] Test cases included -- [ ] Documentation updated -- [ ] Commit messages follow conventions -- [ ] Commits signed (DCO) -- [ ] `just check` passes ----- - -=== Review Process - -. **Automated Checks**: Must pass -. **Maintainer Review**: At least one maintainer approval required -. **Community Feedback**: Allow time for community input (3-7 days for major changes) -. **Revisions**: Address reviewer feedback -. **Merge**: Maintainer will merge when ready - -=== Review Timeline - -* **Minor changes** (typos, formatting): 1-3 days -* **Test additions**: 3-7 days -* **Specification changes**: 1-2 weeks -* **New operations**: 1-3 months (requires extensive discussion) - -== Communication - -=== Where to Discuss - -* **GitHub/GitLab Issues**: Bug reports, feature requests, discussions -* **Pull Requests**: Code review and specification changes -* **Email**: security@[project-domain] for security issues only - -=== Response Times - -We aim to respond within: - -* **Security issues**: 72 hours -* **Bug reports**: 1 week -* **Feature requests**: 2 weeks -* **Pull requests**: 1 week for initial review - -=== Getting Help - -. Read SPEC_FORMAT.md and existing specifications -. Search existing issues and PRs -. Create a new issue if you can't find answers -. Be patient and respectful - -== Recognition - -Contributors are recognized in multiple ways: - -* Listed in link:MAINTAINERS.md[] (for significant contributions) -* Mentioned in link:CHANGELOG.md[] -* Credited in release notes -* Acknowledged in `.well-known/humans.txt` - -== License - -By contributing, you agree that your contributions will be licensed under the project's dual license (MIT / Palimpsest v0.8). See link:LICENSE.txt[] for details. - -All contributions must include appropriate SPDX headers. - -== Questions? - -If you have questions about contributing, please: - -. Read this guide thoroughly -. Check existing issues and discussions -. Create a new issue with the `question` label -. Be patient and respectful - -Thank you for contributing to aggregate-library! 🎉 - ---- diff --git a/FUNDING.yml b/FUNDING.yml index d564404..01066a5 100644 --- a/FUNDING.yml +++ b/FUNDING.yml @@ -47,7 +47,7 @@ # - OpenCollective dashboard (when active): https://opencollective.com/aggregate-library # Thank you for your interest in supporting aggregate-library! -# For now, the best way to support is through contributions (see CONTRIBUTING.adoc) +# For now, the best way to support is through contributions (see .github/CONTRIBUTING.md) # Last Updated: 2025-11-22 # Status: Funding not yet active diff --git a/Justfile b/Justfile index dfc71fa..4de4c82 100644 --- a/Justfile +++ b/Justfile @@ -127,7 +127,7 @@ docs-required: @test -f LICENSE.txt || (echo "❌ Missing LICENSE.txt" && exit 1) @test -f CLAUDE.md || (echo "❌ Missing CLAUDE.md" && exit 1) @test -f SPEC_FORMAT.md || (echo "❌ Missing SPEC_FORMAT.md" && exit 1) - @test -f CONTRIBUTING.md -o -f CONTRIBUTING.adoc || (echo "❌ Missing CONTRIBUTING.md or CONTRIBUTING.adoc" && exit 1) + @test -f CONTRIBUTING.md -o -f .github/CONTRIBUTING.md || (echo "❌ Missing CONTRIBUTING.md or .github/CONTRIBUTING.md" && exit 1) @test -f CODE_OF_CONDUCT.md || (echo "❌ Missing CODE_OF_CONDUCT.md" && exit 1) @test -f SECURITY.md || (echo "❌ Missing SECURITY.md" && exit 1) @test -f MAINTAINERS.md || (echo "❌ Missing MAINTAINERS.md" && exit 1) @@ -166,7 +166,7 @@ rsr-documentation: @(test -f README.md || test -f README.adoc) && echo " ✅ README" || echo " ❌ README" @test -f LICENSE.txt && echo " ✅ LICENSE.txt" || echo " ❌ LICENSE.txt" @test -f SECURITY.md && echo " ✅ SECURITY.md" || echo " ❌ SECURITY.md" - @(test -f CONTRIBUTING.md || test -f CONTRIBUTING.adoc) && echo " ✅ CONTRIBUTING" || echo " ❌ CONTRIBUTING" + @(test -f CONTRIBUTING.md || test -f .github/CONTRIBUTING.md) && echo " ✅ CONTRIBUTING" || echo " ❌ CONTRIBUTING" @test -f CODE_OF_CONDUCT.md && echo " ✅ CODE_OF_CONDUCT.md" || echo " ❌ CODE_OF_CONDUCT.md" @test -f MAINTAINERS.md && echo " ✅ MAINTAINERS.md" || echo " ❌ MAINTAINERS.md" @(test -f CHANGELOG.md || test -f CHANGELOG.adoc) && echo " ✅ CHANGELOG" || echo " ❌ CHANGELOG" @@ -183,7 +183,7 @@ rsr-infrastructure: rsr-metadata: @echo "📦 RSR Metadata:" @grep -q "Dual MIT / Palimpsest" LICENSE.txt && echo " ✅ Dual license (MIT + Palimpsest)" || echo " ⚠️ License check" - @(grep -q "TPCF" CONTRIBUTING.md 2>/dev/null || grep -q "TPCF" CONTRIBUTING.adoc 2>/dev/null) && echo " ✅ TPCF Perimeter designation" || echo " ⚠️ TPCF designation" + @(grep -q "TPCF" CONTRIBUTING.md 2>/dev/null || grep -q "TPCF" .github/CONTRIBUTING.md 2>/dev/null) && echo " ✅ TPCF Perimeter designation" || echo " ⚠️ TPCF designation" @test -d specs && echo " ✅ Specification directory" || echo " ❌ specs/ directory" # Show RSR compliance level diff --git a/RSR_OUTLINE.adoc b/RSR_OUTLINE.adoc index 63243fd..2215481 100644 --- a/RSR_OUTLINE.adoc +++ b/RSR_OUTLINE.adoc @@ -35,7 +35,7 @@ git init sed -i 's/RSR-template-repo/my-project/g' Justfile guix.scm README.adoc # Enter development environment -guix shell -D -f guix.scm +guix shell -D -f build/guix.scm # Validate compliance just validate-rsr diff --git a/guix.scm b/guix.scm deleted file mode 100644 index d0e89d8..0000000 --- a/guix.scm +++ /dev/null @@ -1,28 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0 -;; Guix development environment. -;; Usage: guix shell -D -f guix.scm - -(use-modules (guix packages) - (guix build-system gnu) - (guix licenses) - (gnu packages base) - (gnu packages bash) - (gnu packages base) - (gnu packages java) - (gnu packages rust) - (gnu packages cmake) - (gnu packages zig) - (gnu packages golang) - (gnu packages node) - (gnu packages python)) - -(package - (name "aggregate-library") - (version "0.1.0") - (source #f) - (build-system gnu-build-system) - (inputs (list coreutils bash make openjdk rust cmake zig go node python)) - (synopsis "aggregate-library") - (description "aggregate-library — part of the hyperpolymath ecosystem.") - (home-page "https://github.com/hyperpolymath/aggregate-library") - (license ((@@ (guix licenses) license) "MPL-2.0" "https://github.com/hyperpolymath/palimpsest-license")))