diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 2777a72..16dfcb2 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,28 +1,8 @@ # Code of Conduct - - ## Our Pledge -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. +We as members, contributors, and leaders pledge to make participation in Eclexia a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. @@ -136,9 +116,8 @@ If you experience or witness unacceptable behaviour, or have any other concerns, | Method | Details | Best For | |--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | +| **GitHub** | [Open a private security advisory](https://github.com/hyperpolymath/eclexia/security/advisories/new) | Detailed reports, sensitive matters | | **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | **What to Include** @@ -152,8 +131,8 @@ If you experience or witness unacceptable behaviour, or have any other concerns, **What Happens Next** -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report +1. You will receive acknowledgment within **48 hours** +2. The maintainers will review the report 3. We may ask for additional information 4. We will determine appropriate action 5. We will inform you of the outcome (respecting others' privacy) @@ -169,7 +148,7 @@ All reports will be handled with discretion: ### Conflicts of Interest -If a {{CONDUCT_TEAM}} member is involved in an incident: +If a maintainer is involved in an incident: - They will recuse themselves from the process - Another maintainer or external party will handle the report @@ -179,7 +158,7 @@ If a {{CONDUCT_TEAM}} member is involved in an incident: ## Enforcement Guidelines -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: +The maintainers will follow these guidelines in determining consequences: ### 1. Correction @@ -231,13 +210,13 @@ For contributors with elevated access (Perimeter 2 or 1): If you believe an enforcement decision was made in error: 1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" +2. **Contact maintainers** via GitHub with subject line "Appeal: [Original Report ID]" 3. **Explain** why you believe the decision should be reconsidered 4. **Provide** any new information not previously available **Appeals Process** -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original +- Appeals are reviewed by a different maintainer than the original - You will receive a response within 14 days - The appeals decision is final - You may only appeal once per incident @@ -310,8 +289,7 @@ We thank these communities for their leadership in creating welcoming spaces. If you have questions about this Code of Conduct: -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) +- Open a [Discussion](https://github.com/hyperpolymath/eclexia/discussions) (for general questions) - Contact any maintainer directly --- @@ -324,4 +302,4 @@ We're all here because we care about this project. Let's make it a place where e --- -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 +Last updated: 2025 · Based on Contributor Covenant 2.1 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5457337..91a479e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,40 @@ +# Contributing to Eclexia + +Thank you for your interest in contributing to Eclexia! This document provides guidelines and information for contributors. + +## Table of Contents + +- [Getting Started](#getting-started) +- [How to Contribute](#how-to-contribute) +- [Development Workflow](#development-workflow) +- [Code Standards](#code-standards) +- [Pull Request Process](#pull-request-process) + +--- + +## Getting Started + +### Prerequisites + +Before contributing, ensure you have: + +- Git installed +- A GitHub account +- Familiarity with the project's purpose and structure + +### Setting Up Your Environment + +```bash # Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} +git clone https://github.com/hyperpolymath/eclexia.git +cd eclexia # Using Nix (recommended for reproducibility) nix develop # Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev +toolbox create eclexia-dev +toolbox enter eclexia-dev # Install dependencies manually # Verify setup @@ -16,8 +43,9 @@ just test # Run test suite ``` ### Repository Structure + ``` -{{REPO}}/ +eclexia/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) @@ -53,7 +81,7 @@ just test # Run test suite **Before reporting**: 1. Search existing issues -2. Check if it's already fixed in `{{MAIN_BRANCH}}` +2. Check if it's already fixed in `main` 3. Determine which perimeter the bug affects **When reporting**: @@ -86,16 +114,17 @@ Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) an Look for issues labelled: -- [`good first issue`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/perimeter-3) — Community sandbox scope +- [`good first issue`](https://github.com/hyperpolymath/eclexia/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/eclexia/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/eclexia/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/eclexia/labels/perimeter-3) — Community sandbox scope --- ## Development Workflow ### Branch Naming + ``` docs/short-description # Documentation (P3) test/what-added # Test additions (P3) @@ -108,9 +137,91 @@ security/what-fixed # Security fixes (P1-2) ### Commit Messages We follow [Conventional Commits](https://www.conventionalcommits.org/): + ``` (): [optional body] [optional footer] +``` + +**Types**: +- `feat`: New feature +- `fix`: Bug fix +- `docs`: Documentation only +- `style`: Formatting, no code change +- `refactor`: Code change that neither fixes a bug nor adds a feature +- `perf`: Performance improvement +- `test`: Adding or correcting tests +- `chore`: Maintenance tasks + +**Examples**: +``` +feat(auth): add OAuth2 support for GitHub +fix(parser): handle edge case with empty input +docs(readme): update installation instructions +``` + +--- + +## Code Standards + +### General Guidelines + +- Follow existing code style and patterns +- Write clear, self-documenting code +- Add tests for new functionality +- Update documentation as needed +- Keep commits atomic and focused + +### Security + +Please review our [Security Policy](SECURITY.md) and ensure your contributions: + +- Do not introduce security vulnerabilities +- Follow secure coding practices +- Do not commit secrets or credentials + +--- + +## Pull Request Process + +1. **Fork** the repository and create your branch from `main` +2. **Make** your changes following our guidelines +3. **Test** your changes thoroughly +4. **Commit** with clear, conventional commit messages +5. **Push** to your fork +6. **Open** a pull request with: + - Clear description of changes + - Reference to related issues + - Screenshots/examples if applicable +7. **Respond** to review feedback promptly + +### Review Criteria + +Pull requests are evaluated on: + +- Code quality and style consistency +- Test coverage +- Documentation updates +- Security considerations +- Alignment with project goals + +--- + +## Questions? + +- Open a [Discussion](https://github.com/hyperpolymath/eclexia/discussions) for general questions +- Check existing issues for similar questions +- Review the [README](README.adoc) for project overview + +--- + +## Code of Conduct + +By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). + +--- + +*Thank you for contributing to Eclexia!* diff --git a/ECOSYSTEM.scm b/ECOSYSTEM.scm index 5128535..7657d1e 100644 --- a/ECOSYSTEM.scm +++ b/ECOSYSTEM.scm @@ -1,10 +1,10 @@ ;; SPDX-License-Identifier: AGPL-3.0-or-later ;; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell -;; ECOSYSTEM.scm — template-repo +;; ECOSYSTEM.scm — eclexia (ecosystem (version "1.0.0") - (name "template-repo") + (name "eclexia") (type "project") (purpose "Project in the hyperpolymath ecosystem") diff --git a/META.scm b/META.scm index 136c02a..502a858 100644 --- a/META.scm +++ b/META.scm @@ -1,8 +1,8 @@ ;; SPDX-License-Identifier: AGPL-3.0-or-later ;; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell -;;; META.scm — template-repo +;;; META.scm — eclexia -(define-module (template-repo meta) +(define-module (eclexia meta) #:export (architecture-decisions development-practices design-rationale)) (define architecture-decisions diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..701c3cb --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,114 @@ +# Eclexia Roadmap + +This document outlines the development roadmap for Eclexia, tracking progress and planned milestones. + +## Current Status + +**Phase**: v0.1 - Initial Setup +**Overall Completion**: 50% +**Last Updated**: 2025-12-17 + +--- + +## Completed Milestones + +### v0.1.0 - Foundation (Complete) + +- [x] Initial repository setup +- [x] RSR compliance structure +- [x] SCM files (ECOSYSTEM.scm, META.scm, STATE.scm) +- [x] Security documentation (SECURITY.md) +- [x] Code of Conduct (CODE_OF_CONDUCT.md) +- [x] Contributing guidelines (CONTRIBUTING.md) +- [x] License setup (MIT OR AGPL-3.0-or-later dual license) +- [x] GitHub workflows (CodeQL, Dependabot) +- [x] Issue templates (bug report, feature request, documentation, question) + +--- + +## In Progress + +### v0.2.0 - Core Development + +- [ ] Define project scope and objectives +- [ ] Establish core architecture +- [ ] Set up development environment (flake.nix) +- [ ] Create justfile for task automation +- [ ] Add initial source code structure +- [ ] Implement basic functionality +- [ ] Add unit tests (target: 70% coverage) + +--- + +## Planned Milestones + +### v0.3.0 - Testing & Quality + +- [ ] Integration tests +- [ ] Property-based tests +- [ ] Performance benchmarks +- [ ] Code quality gates +- [ ] Documentation improvements + +### v0.4.0 - CI/CD Enhancement + +- [ ] Multi-platform CI workflows +- [ ] Automated releases +- [ ] Changelog automation +- [ ] Security scanning integration +- [ ] Container builds (Podman) + +### v1.0.0 - Stable Release + +- [ ] Feature complete for initial scope +- [ ] Comprehensive documentation +- [ ] Production-ready stability +- [ ] Community guidelines finalised +- [ ] First official release + +--- + +## Future Considerations + +### Post-v1.0 + +- Extended functionality based on community feedback +- Performance optimisations +- Additional integrations +- Plugin/extension system +- Expanded platform support + +--- + +## RSR Compliance Targets + +Following Rhodium Standard Repository guidelines: + +| Requirement | Status | Notes | +|-------------|--------|-------| +| SPDX headers | Complete | All files include licence identifiers | +| SHA-pinned actions | Complete | CodeQL workflow uses pinned SHAs | +| Security policy | Complete | SECURITY.md with reporting process | +| Code of Conduct | Complete | Contributor Covenant based | +| Dependabot config | Complete | Weekly updates configured | +| CodeQL analysis | Complete | JavaScript/TypeScript enabled | +| Multi-platform CI | Pending | Add Linux, macOS, Windows | +| Signed commits | Recommended | Encouraged in contributing guide | + +--- + +## Contributing to the Roadmap + +Have ideas for features or improvements? + +1. Check existing [issues](https://github.com/hyperpolymath/eclexia/issues) and [discussions](https://github.com/hyperpolymath/eclexia/discussions) +2. Open a [feature request](https://github.com/hyperpolymath/eclexia/issues/new?template=feature_request.md) +3. Participate in roadmap discussions + +--- + +## Updates + +This roadmap is updated as the project evolves. See [STATE.scm](STATE.scm) for machine-readable project state. + +*Last reviewed: 2025-12-17* diff --git a/SECURITY.md b/SECURITY.md index 7dd7b29..f2ca4e3 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,23 +1,5 @@ # Security Policy - - We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. ## Table of Contents @@ -40,7 +22,7 @@ We take security seriously. We appreciate your efforts to responsibly disclose v The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) +1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/eclexia/security/advisories/new) 2. Click **"Report a vulnerability"** 3. Complete the form with as much detail as possible 4. Submit — we'll receive a private notification @@ -52,28 +34,11 @@ This method ensures: - Coordinated disclosure tooling - Automatic credit when the advisory is published -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: +### Alternative: Email -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | +If you cannot use GitHub Security Advisories, you may open a private security advisory or contact the maintainers through GitHub. -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. +> **Warning:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. --- @@ -199,17 +164,17 @@ If we cannot reach agreement on disclosure timing, we default to 90 days from yo ## Scope -### In Scope ✅ +### In Scope The following are within scope for security research: -- This repository (`{{OWNER}}/{{REPO}}`) and all its code +- This repository (`hyperpolymath/eclexia`) and all its code - Official releases and packages published from this repository - Documentation that could lead to security issues - Build and deployment configurations in this repository - Dependencies (report here, we'll coordinate with upstream) -### Out of Scope ❌ +### Out of Scope The following are **not** in scope: @@ -262,11 +227,11 @@ We support security research conducted in good faith. If you conduct security research in accordance with this policy: -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls +- We will not initiate legal action against you +- We will not report your activity to law enforcement +- We will work with you in good faith to resolve issues +- We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +- We waive any potential claim against you for circumvention of security controls ### Good Faith Requirements @@ -279,7 +244,7 @@ To qualify for safe harbour, you must: - Not exploit vulnerabilities beyond proof-of-concept - Not use vulnerabilities for profit (beyond bug bounties where offered) -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. +> **Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. --- @@ -289,7 +254,7 @@ We believe in recognising security researchers who help us improve. ### Hall of Fame -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). +Researchers who report valid vulnerabilities will be acknowledged in our Security Acknowledgments (unless they prefer anonymity). Recognition includes: @@ -300,16 +265,16 @@ Recognition includes: ### What We Offer -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) +- Public credit in security advisories +- Acknowledgment in release notes +- Entry in our Hall of Fame +- Reference/recommendation letter upon request (for significant findings) ### What We Don't Currently Offer -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts +- Monetary bug bounties +- Hardware or swag +- Paid security research contracts > **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. @@ -322,8 +287,8 @@ Recognition includes: To stay informed about security updates: - **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) +- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/eclexia/security/advisories) +- **Release notes**: Security fixes noted in CHANGELOG ### Update Policy @@ -335,20 +300,18 @@ To stay informed about security updates: ### Supported Versions - - | Version | Supported | Notes | |---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | +| `main` branch | Yes | Latest development | +| Latest release | Yes | Current stable | +| Previous minor release | Yes | Security fixes backported | +| Older versions | No | Please upgrade | --- ## Security Best Practices -When using {{PROJECT_NAME}}, we recommend: +When using Eclexia, we recommend: ### General @@ -370,9 +333,7 @@ When using {{PROJECT_NAME}}, we recommend: ## Additional Resources -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) +- [Security Advisories](https://github.com/hyperpolymath/eclexia/security/advisories) - [Contributing Guidelines](CONTRIBUTING.md) - [CVE Database](https://cve.mitre.org/) - [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) @@ -383,9 +344,9 @@ When using {{PROJECT_NAME}}, we recommend: | Purpose | Contact | |---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | +| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/eclexia/security/advisories/new) | +| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/eclexia/discussions) | +| **Other enquiries** | See [README](README.adoc) for contact information | --- @@ -399,8 +360,8 @@ This security policy may be updated from time to time. Significant changes will --- -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ +*Thank you for helping keep Eclexia and its users safe.* --- -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 +Last updated: 2025 · Policy version: 1.0.0 diff --git a/STATE.scm b/STATE.scm index 326a48e..49cfa83 100644 --- a/STATE.scm +++ b/STATE.scm @@ -1,22 +1,26 @@ -;;; STATE.scm — template-repo +;;; STATE.scm — eclexia ;; SPDX-License-Identifier: AGPL-3.0-or-later ;; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell (define metadata - '((version . "0.1.0") (updated . "2025-12-15") (project . "template-repo"))) + '((version . "0.1.0") (updated . "2025-12-17") (project . "eclexia"))) (define current-position '((phase . "v0.1 - Initial Setup") - (overall-completion . 25) - (components ((rsr-compliance ((status . "complete") (completion . 100))))))) + (overall-completion . 50) + (components ((rsr-compliance ((status . "complete") (completion . 100))) + (security-docs ((status . "complete") (completion . 100))) + (scm-files ((status . "complete") (completion . 100))))))) (define blockers-and-issues '((critical ()) (high-priority ()))) (define critical-next-actions - '((immediate (("Verify CI/CD" . high))) (this-week (("Expand tests" . medium))))) + '((immediate (("Define project scope" . high))) + (this-week (("Add core functionality" . medium) ("Expand tests" . medium))))) (define session-history - '((snapshots ((date . "2025-12-15") (session . "initial") (notes . "SCM files added"))))) + '((snapshots ((date . "2025-12-15") (session . "initial") (notes . "SCM files added")) + ((date . "2025-12-17") (session . "security-review") (notes . "Fixed placeholders in SECURITY.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md; updated SCM files"))))) (define state-summary - '((project . "template-repo") (completion . 25) (blockers . 0) (updated . "2025-12-15"))) + '((project . "eclexia") (completion . 50) (blockers . 0) (updated . "2025-12-17")))