From 3c2baa84fc435e004ebf827d66d3e1f19fcac1c7 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:52:17 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ARCHITECTURE.adoc | 48 ++ ARCHITECTURE.md | 47 -- CHANGELOG.adoc | 76 +++ CHANGELOG.md | 69 --- CODE_OF_CONDUCT.adoc | 339 +++++++++++++ CODE_OF_CONDUCT.md | 311 ------------ CONTRIBUTING.adoc | 108 +++++ CONTRIBUTING.md | 120 ----- GOVERNANCE.adoc | 60 +++ GOVERNANCE.md | 60 --- NAMING.adoc | 25 + NAMING.md | 25 - PROOF-NEEDS.adoc | 55 +++ PROOF-NEEDS.md | 45 -- SECURITY.adoc | 452 ++++++++++++++++++ SECURITY.md | 392 --------------- TEST-NEEDS.adoc | 161 +++++++ TEST-NEEDS.md | 107 ----- TOPOLOGY.md => TOPOLOGY.adoc | 48 +- docs/tech-debt-2026-05-26.adoc | 70 +++ docs/tech-debt-2026-05-26.md | 61 --- .../ABI-FFI-README.adoc | 244 +++++----- ...ODE_OF_CONDUCT.md => CODE_OF_CONDUCT.adoc} | 32 +- lazy-eliminator/CONTRIBUTING.adoc | 159 +++--- lazy-eliminator/CONTRIBUTING.md | 120 ----- lazy-eliminator/SECURITY.adoc | 61 +++ lazy-eliminator/SECURITY.md | 67 --- llm-warmup-dev.adoc | 19 + llm-warmup-dev.md | 20 - llm-warmup-user.adoc | 19 + llm-warmup-user.md | 20 - .../ABI-FFI-README.adoc | 244 +++++----- satellite-template/CODE_OF_CONDUCT.adoc | 24 + satellite-template/CODE_OF_CONDUCT.md | 30 -- satellite-template/CONTRIBUTING.adoc | 115 ++++- satellite-template/CONTRIBUTING.md | 120 ----- satellite-template/SECURITY.adoc | 30 ++ satellite-template/SECURITY.md | 33 -- ...{ABI-FFI-README.md => ABI-FFI-README.adoc} | 244 +++++----- vexometer-satellites/CODE_OF_CONDUCT.adoc | 339 +++++++++++++ vexometer-satellites/CODE_OF_CONDUCT.md | 311 ------------ vexometer-satellites/CONTRIBUTING.adoc | 213 +++------ vexometer-satellites/CONTRIBUTING.md | 120 ----- vexometer-satellites/SECURITY.adoc | 87 ++++ vexometer-satellites/SECURITY.md | 96 ---- ...{ABI-FFI-README.md => ABI-FFI-README.adoc} | 244 +++++----- vexometer/CODE_OF_CONDUCT.adoc | 42 ++ vexometer/CODE_OF_CONDUCT.md | 46 -- vexometer/CONTRIBUTING.adoc | 133 ++++-- vexometer/CONTRIBUTING.md | 120 ----- vexometer/SECURITY.adoc | 52 ++ vexometer/SECURITY.md | 61 --- .../{SPECIFICATION.md => SPECIFICATION.adoc} | 222 +++++---- vexometer/docs/letter_lmsys_arena.adoc | 188 ++++++++ vexometer/docs/letter_lmsys_arena.md | 149 ------ vext-email-gateway/ABI-FFI-README.adoc | 409 ++++++++++++++++ vext-email-gateway/ABI-FFI-README.md | 389 --------------- vext-email-gateway/CODE_OF_CONDUCT.adoc | 339 +++++++++++++ vext-email-gateway/CODE_OF_CONDUCT.md | 311 ------------ vext-email-gateway/CONTRIBUTING.adoc | 108 +++++ vext-email-gateway/CONTRIBUTING.md | 120 ----- vext-email-gateway/SECURITY.adoc | 452 ++++++++++++++++++ vext-email-gateway/SECURITY.md | 392 --------------- vext/.migration/PYTHON_TO_RUST_RESCRIPT.adoc | 29 ++ vext/.migration/PYTHON_TO_RUST_RESCRIPT.md | 28 -- vext/ABI-FFI-README.adoc | 409 ++++++++++++++++ vext/ABI-FFI-README.md | 389 --------------- vext/CHANGELOG.adoc | 423 ++++++++-------- vext/CHANGELOG.md | 253 ---------- vext/CODE_OF_CONDUCT.adoc | 286 +++++++++++ vext/CODE_OF_CONDUCT.md | 267 ----------- vext/CONTRIBUTING.adoc | 22 +- vext/CONTRIBUTING.md | 7 - vext/DOCUMENTATION_INDEX.adoc | 369 ++++++++++++++ vext/DOCUMENTATION_INDEX.md | 401 ---------------- vext/FEATURES.adoc | 388 +++++++++++++++ vext/FEATURES.md | 376 --------------- ...ATION_GUIDE.md => INSTALLATION_GUIDE.adoc} | 294 +++++++----- vext/MAINTAINERS.adoc | 314 ++++++++++-- vext/MAINTAINERS.md | 318 ------------ vext/PROJECT_OVERVIEW.adoc | 248 ++++++++++ vext/PROJECT_OVERVIEW.md | 225 --------- vext/REPO-CONTENTS.adoc | 156 ++++++ vext/REPO-CONTENTS.md | 152 ------ vext/RESEARCH_SUMMARY.adoc | 323 +++++++++++++ vext/RESEARCH_SUMMARY.md | 290 ----------- vext/ROADMAP.adoc | 131 +---- vext/ROADMAP.md | 12 - vext/RSR_COMPLIANCE.adoc | 436 +++++++++++++++++ vext/RSR_COMPLIANCE.md | 416 ---------------- vext/SECURITY.adoc | 203 ++++++++ vext/SECURITY.md | 196 -------- ...HNOLOGY_STACK.md => TECHNOLOGY_STACK.adoc} | 268 ++++++----- vext/{USAGE_GUIDE.md => USAGE_GUIDE.adoc} | 254 +++++----- vext/docs/conference-materials.adoc | 196 ++++++++ vext/docs/conference-materials.md | 167 ------- vext/governance/PROJECT_GOVERNANCE.adoc | 330 +++++++++++++ vext/governance/PROJECT_GOVERNANCE.md | 363 -------------- vext/papers/tpcf-graduated-trust.adoc | 275 +++++++++++ vext/papers/tpcf-graduated-trust.md | 268 ----------- 100 files changed, 9185 insertions(+), 9520 deletions(-) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md create mode 100644 NAMING.adoc delete mode 100644 NAMING.md create mode 100644 PROOF-NEEDS.adoc delete mode 100644 PROOF-NEEDS.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (85%) create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md rename satellite-template/ABI-FFI-README.md => lazy-eliminator/ABI-FFI-README.adoc (74%) rename lazy-eliminator/{CODE_OF_CONDUCT.md => CODE_OF_CONDUCT.adoc} (54%) delete mode 100644 lazy-eliminator/CONTRIBUTING.md create mode 100644 lazy-eliminator/SECURITY.adoc delete mode 100644 lazy-eliminator/SECURITY.md create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md rename lazy-eliminator/ABI-FFI-README.md => satellite-template/ABI-FFI-README.adoc (74%) create mode 100644 satellite-template/CODE_OF_CONDUCT.adoc delete mode 100644 satellite-template/CODE_OF_CONDUCT.md delete mode 100644 satellite-template/CONTRIBUTING.md create mode 100644 satellite-template/SECURITY.adoc delete mode 100644 satellite-template/SECURITY.md rename vexometer-satellites/{ABI-FFI-README.md => ABI-FFI-README.adoc} (74%) create mode 100644 vexometer-satellites/CODE_OF_CONDUCT.adoc delete mode 100644 vexometer-satellites/CODE_OF_CONDUCT.md delete mode 100644 vexometer-satellites/CONTRIBUTING.md create mode 100644 vexometer-satellites/SECURITY.adoc delete mode 100644 vexometer-satellites/SECURITY.md rename vexometer/{ABI-FFI-README.md => ABI-FFI-README.adoc} (74%) create mode 100644 vexometer/CODE_OF_CONDUCT.adoc delete mode 100644 vexometer/CODE_OF_CONDUCT.md delete mode 100644 vexometer/CONTRIBUTING.md create mode 100644 vexometer/SECURITY.adoc delete mode 100644 vexometer/SECURITY.md rename vexometer/docs/{SPECIFICATION.md => SPECIFICATION.adoc} (65%) create mode 100644 vexometer/docs/letter_lmsys_arena.adoc delete mode 100644 vexometer/docs/letter_lmsys_arena.md create mode 100644 vext-email-gateway/ABI-FFI-README.adoc delete mode 100644 vext-email-gateway/ABI-FFI-README.md create mode 100644 vext-email-gateway/CODE_OF_CONDUCT.adoc delete mode 100644 vext-email-gateway/CODE_OF_CONDUCT.md create mode 100644 vext-email-gateway/CONTRIBUTING.adoc delete mode 100644 vext-email-gateway/CONTRIBUTING.md create mode 100644 vext-email-gateway/SECURITY.adoc delete mode 100644 vext-email-gateway/SECURITY.md create mode 100644 vext/.migration/PYTHON_TO_RUST_RESCRIPT.adoc delete mode 100644 vext/.migration/PYTHON_TO_RUST_RESCRIPT.md create mode 100644 vext/ABI-FFI-README.adoc delete mode 100644 vext/ABI-FFI-README.md delete mode 100644 vext/CHANGELOG.md create mode 100644 vext/CODE_OF_CONDUCT.adoc delete mode 100644 vext/CODE_OF_CONDUCT.md delete mode 100644 vext/CONTRIBUTING.md create mode 100644 vext/DOCUMENTATION_INDEX.adoc delete mode 100644 vext/DOCUMENTATION_INDEX.md create mode 100644 vext/FEATURES.adoc delete mode 100644 vext/FEATURES.md rename vext/{INSTALLATION_GUIDE.md => INSTALLATION_GUIDE.adoc} (78%) delete mode 100644 vext/MAINTAINERS.md create mode 100644 vext/PROJECT_OVERVIEW.adoc delete mode 100644 vext/PROJECT_OVERVIEW.md create mode 100644 vext/REPO-CONTENTS.adoc delete mode 100644 vext/REPO-CONTENTS.md create mode 100644 vext/RESEARCH_SUMMARY.adoc delete mode 100644 vext/RESEARCH_SUMMARY.md delete mode 100644 vext/ROADMAP.md create mode 100644 vext/RSR_COMPLIANCE.adoc delete mode 100644 vext/RSR_COMPLIANCE.md create mode 100644 vext/SECURITY.adoc delete mode 100644 vext/SECURITY.md rename vext/{TECHNOLOGY_STACK.md => TECHNOLOGY_STACK.adoc} (56%) rename vext/{USAGE_GUIDE.md => USAGE_GUIDE.adoc} (86%) create mode 100644 vext/docs/conference-materials.adoc delete mode 100644 vext/docs/conference-materials.md create mode 100644 vext/governance/PROJECT_GOVERNANCE.adoc delete mode 100644 vext/governance/PROJECT_GOVERNANCE.md create mode 100644 vext/papers/tpcf-graduated-trust.adoc delete mode 100644 vext/papers/tpcf-graduated-trust.md diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..e523369 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,76 @@ +== Changelog + +All notable changes to `+vexometer+` will be documented in this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add stapeln.toml container definition +* feat: deploy UX Manifesto infrastructure +* feat(vext): replace template ABI with proper types, add V-lang API +* feat: add Groove discovery manifest for Vext +* feat: update Vext listener, pool, and protocol +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat: add mirror.yml workflow for GitLab/Bitbucket mirroring +* feat: add CI gates and real vexometer core tests + +==== Fixed + +* fix(ci): sync hypatia-scan.yml to canonical (413: +env.HOME+Phase-2+SARIF) (#17) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(deps): bump vulnerable crates to patched versions (#14) +* fix(ci): rsr-antipattern.yml duplicate heredoc (#15) +* fix: restructure prod expect("`TODO`") sites in vext-email-gateway + +lazy-eliminator +* fix(manifest): correct 0-AI-MANIFEST — this is an ISA component, not +the Vext protocol +* fix(deps): replace trust-dns-resolver with hickory-resolver and bump +validator to resolve idna advisory +* fix(deps): update Cargo.lock to resolve security advisories + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: add 0-AI-MANIFEST.a2ml (RSR compliance) + +==== CI + +* ci: fix nonexistent actions/upload-artifact SHA pin (#16) +* ci(antipattern): fix top-level dir matching + benchmarks/lsp/bench +filename allowlists (#12) +* ci(antipattern): TS check reads .claude/CLAUDE.md exemption table +(#11) +* ci(antipattern): broaden TS allowlist (cli/, mod.ts, lsp-server, +_vscode_, deno-*) (#10) +* ci(antipattern): allowlist legit TS bridge/adapter paths (#9) + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 84a2903..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,69 +0,0 @@ - -# Changelog - -All notable changes to `vexometer` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add stapeln.toml container definition -- feat: deploy UX Manifesto infrastructure -- feat(vext): replace template ABI with proper types, add V-lang API -- feat: add Groove discovery manifest for Vext -- feat: update Vext listener, pool, and protocol -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat: add mirror.yml workflow for GitLab/Bitbucket mirroring -- feat: add CI gates and real vexometer core tests - -### Fixed - -- fix(ci): sync hypatia-scan.yml to canonical (413: env.HOME+Phase-2+SARIF) (#17) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(deps): bump vulnerable crates to patched versions (#14) -- fix(ci): rsr-antipattern.yml duplicate heredoc (#15) -- fix: restructure prod expect("TODO") sites in vext-email-gateway + lazy-eliminator -- fix(manifest): correct 0-AI-MANIFEST — this is an ISA component, not the Vext protocol -- fix(deps): replace trust-dns-resolver with hickory-resolver and bump validator to resolve idna advisory -- fix(deps): update Cargo.lock to resolve security advisories - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: add 0-AI-MANIFEST.a2ml (RSR compliance) - -### CI - -- ci: fix nonexistent actions/upload-artifact SHA pin (#16) -- ci(antipattern): fix top-level dir matching + benchmarks/lsp/bench filename allowlists (#12) -- ci(antipattern): TS check reads .claude/CLAUDE.md exemption table (#11) -- ci(antipattern): broaden TS allowlist (cli/, mod.ts, lsp-server, *vscode*, deno-*) (#10) -- ci(antipattern): allowlist legit TS bridge/adapter paths (#9) - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..54f0cf2 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +vexometer 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. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |j.d.a.jewell@open.ac.uk |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* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *72 hours* +. The maintainer team will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a maintainer team member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The maintainer team will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* j.d.a.jewell@open.ac.uk with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different maintainer team member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/vexometer/discussions[Discussion] (for +general questions) +* Email j.d.a.jewell@open.ac.uk (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 93da148..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,311 +0,0 @@ - -# Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in vexometer 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. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | j.d.a.jewell@open.ac.uk | 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** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **72 hours** -2. The maintainer team 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) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a maintainer team member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The maintainer team will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** j.d.a.jewell@open.ac.uk 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 maintainer team member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/vexometer/discussions) (for general questions) -- Email j.d.a.jewell@open.ac.uk (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..73767d3 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/vexometer.git cd vexometer + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create vexometer-dev toolbox enter vexometer-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +vexometer/ ├── 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) │ ├── ISSUE_TEMPLATE/ │ +└── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── +CONTRIBUTING.md # This file ├── 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](.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/vexometer/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/vexometer/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/vexometer/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/vexometer/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/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index ad79057..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/vexometer.git -cd vexometer - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create vexometer-dev -toolbox enter vexometer-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -vexometer/ -├── 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) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── 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](.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/vexometer/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/vexometer/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/vexometer/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/vexometer/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/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/NAMING.adoc b/NAMING.adoc new file mode 100644 index 0000000..c3fc3e8 --- /dev/null +++ b/NAMING.adoc @@ -0,0 +1,25 @@ +== VEX Toolkit Naming Policy + +=== Canonical Product Name + +* *Canonical title:* *The Vexometer: Irritation Surface Analyser for +LLMs and related tools* +* *Canonical short name:* *ISA* (Irritation Surface Analyser) + +=== Legacy Compatibility Name + +* *Vexometer* is the legacy codename for ISA. +* The `+vexometer+` identifier remains valid and intentionally retained +for compatibility in: +* repository paths (`+vexometer/+`, `+vexometer-satellites/+`) +* package/module names (`+Vexometer.*+`) +* CLI command names (`+vexometer+`) +* protocol IDs (`+vexometer-trace-v1+`, `+vexometer-efficacy-v1+`, +`+vexometer-metrics-v1+`) + +=== Documentation Rule + +* On first mention in user-facing prose, write *The Vexometer: +Irritation Surface Analyser (ISA) for LLMs and related tools*. +* After first mention, you may use *ISA*. +* Use *vexometer* only when referring to compatibility identifiers. diff --git a/NAMING.md b/NAMING.md deleted file mode 100644 index b2f769f..0000000 --- a/NAMING.md +++ /dev/null @@ -1,25 +0,0 @@ - -# VEX Toolkit Naming Policy - -## Canonical Product Name - -- **Canonical title:** **The Vexometer: Irritation Surface Analyser for LLMs and related tools** -- **Canonical short name:** **ISA** (Irritation Surface Analyser) - -## Legacy Compatibility Name - -- **Vexometer** is the legacy codename for ISA. -- The `vexometer` identifier remains valid and intentionally retained for compatibility in: -- repository paths (`vexometer/`, `vexometer-satellites/`) -- package/module names (`Vexometer.*`) -- CLI command names (`vexometer`) -- protocol IDs (`vexometer-trace-v1`, `vexometer-efficacy-v1`, `vexometer-metrics-v1`) - -## Documentation Rule - -- On first mention in user-facing prose, write **The Vexometer: Irritation Surface Analyser (ISA) for LLMs and related tools**. -- After first mention, you may use **ISA**. -- Use **vexometer** only when referring to compatibility identifiers. diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..dfcab62 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,55 @@ +== PROOF-NEEDS.md + +=== Current State + +* *LOC*: ~32,000 +* *Languages*: Rust, ReScript, Idris2, Zig +* *Existing ABI proofs*: `+lazy-eliminator/src/abi/*.idr+` +(template-level) +* *Dangerous patterns*: +** `+vext/vext-tools/src/bindings/Std.res+`: 2 `+Obj.magic+` for CLI +argument parsing +** `+vext/vext-tools/src/hooks/Git.res+`: 1 `+Obj.magic+` for +notification serialization + +=== What Needs Proving + +==== Lazy Eliminator Analysis (lazy-eliminator/) + +* `+analyzer.rs+`, `+detection.rs+`, `+patterns.rs+` — static analysis +for lazy evaluation elimination +* Prove: analysis correctly identifies lazy evaluation patterns (no +false negatives) +* Prove: elimination suggestions preserve program semantics + +==== Trace System (lazy-eliminator/src/trace.rs) + +* Execution tracing — prove traces are faithful to execution order + +==== Fuzz Target (lazy-eliminator/fuzz/) + +* Fuzzing exists but formal proofs of analysis correctness would be +stronger + +==== Vext Tools Obj.magic + +* Minor — CLI argument parsing and notification serialization +* Low priority but should use typed bindings + +=== Recommended Prover + +* *Idris2* for analysis correctness specification +* *Lean4* alternative for the semantic preservation proofs + +=== Priority + +*LOW* — Developer tooling. Analysis correctness is desirable but false +positives/negatives are inconveniences, not safety issues. The +`+Obj.magic+` uses are minimal and non-critical. + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index fab9e2e..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,45 +0,0 @@ - -# PROOF-NEEDS.md -## Current State - -- **LOC**: ~32,000 -- **Languages**: Rust, ReScript, Idris2, Zig -- **Existing ABI proofs**: `lazy-eliminator/src/abi/*.idr` (template-level) -- **Dangerous patterns**: - - `vext/vext-tools/src/bindings/Std.res`: 2 `Obj.magic` for CLI argument parsing - - `vext/vext-tools/src/hooks/Git.res`: 1 `Obj.magic` for notification serialization - -## What Needs Proving - -### Lazy Eliminator Analysis (lazy-eliminator/) -- `analyzer.rs`, `detection.rs`, `patterns.rs` — static analysis for lazy evaluation elimination -- Prove: analysis correctly identifies lazy evaluation patterns (no false negatives) -- Prove: elimination suggestions preserve program semantics - -### Trace System (lazy-eliminator/src/trace.rs) -- Execution tracing — prove traces are faithful to execution order - -### Fuzz Target (lazy-eliminator/fuzz/) -- Fuzzing exists but formal proofs of analysis correctness would be stronger - -### Vext Tools Obj.magic -- Minor — CLI argument parsing and notification serialization -- Low priority but should use typed bindings - -## Recommended Prover - -- **Idris2** for analysis correctness specification -- **Lean4** alternative for the semantic preservation proofs - -## Priority - -**LOW** — Developer tooling. Analysis correctness is desirable but false positives/negatives are inconveniences, not safety issues. The `Obj.magic` uses are minimal and non-critical. - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..e9c9349 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,452 @@ +== 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 + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/vexometer/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* 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: + +[width="100%",cols="50%,50%",] +|=== +|*Email* |j.d.a.jewell@open.ac.uk +|*PGP Key* |https://hyperpolymath.github.io/pgp.asc[Download Public Key] +|*Fingerprint* |`+TBD+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL https://hyperpolymath.github.io/pgp.asc | gpg --import + +# Verify fingerprint +gpg --fingerprint j.d.a.jewell@open.ac.uk + +# Encrypt your report +gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/vexometer+`) 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 ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +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 + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* 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. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== 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) + +==== What We Don’t Currently Offer + +* ❌ 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. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/vexometer/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|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 +|=== + +''''' + +=== Security Best Practices + +When using vexometer, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* https://hyperpolymath.github.io/pgp.asc[Our PGP Public Key] +* https://github.com/hyperpolymath/vexometer/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/vexometer/security/advisories/new[Report +via GitHub] or j.d.a.jewell@open.ac.uk + +|*General questions* +|https://github.com/hyperpolymath/vexometer/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep vexometer and its users safe._ 🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 01e23e5..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,392 +0,0 @@ - -# 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 - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/vexometer/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 - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- 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: - -| | | -|---|---| -| **Email** | j.d.a.jewell@open.ac.uk | -| **PGP Key** | [Download Public Key](https://hyperpolymath.github.io/pgp.asc) | -| **Fingerprint** | `TBD` | - -```bash -# Import our PGP key -curl -sSL https://hyperpolymath.github.io/pgp.asc | gpg --import - -# Verify fingerprint -gpg --fingerprint j.d.a.jewell@open.ac.uk - -# Encrypt your report -gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/vexometer`) 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 ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -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 - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- 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. - ---- - -## Recognition - -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). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### 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) - -### What We Don't Currently Offer - -- ❌ 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. - ---- - -## Security Updates - -### Receiving Updates - -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/hyperpolymath/vexometer/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### 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 | - ---- - -## Security Best Practices - -When using vexometer, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key](https://hyperpolymath.github.io/pgp.asc) -- [Security Advisories](https://github.com/hyperpolymath/vexometer/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/vexometer/security/advisories/new) or j.d.a.jewell@open.ac.uk | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/vexometer/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep vexometer and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..293ddcc --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,161 @@ +== TEST-NEEDS: vexometer + +=== Current State + +[width="100%",cols="40%,26%,34%",options="header",] +|=== +|Category |Count |Details +|*Source modules* |24+ |Ada specs (10: api, cii, core, gui, metrics, +patterns, probes, rci, reports, sfr) + bodies, 3 Idris2 ABI per +sub-project (vexometer, vexometer-satellites, satellite-template), Zig +FFI + +|*Unit tests* |4 files |test_runner.adb (~36 assertions) + 3 analyzer.rs +unit tests + +|*E2E tests* |1 file |e2e_test.rs (16 tests - full pipeline analysis, +multi-language, CII calc) + +|*Property tests* |1 file |property_test.rs (16 tests - proptest: +analysis never panics, CII ranges, determinism) + +|*Aspect tests* |1 file |aspect_test.rs (20 tests - security, +robustness, concurrency) + +|*Benchmarks* |1 file |detection_bench.rs (Criterion: throughput, +language detection, CII calc) +|=== + +=== What’s Completed (CRG D→C Blitz) + +==== ✓ Lazy-Eliminator (Rust sub-project) - CRG C Achieved + +* [x] *Unit tests* (3): Python TODO, Rust unimplemented, complete code +* [x] *E2E tests* (16): Full pipeline, multi-language, CII calculation, +detections +* [x] *Property tests* (16): Analysis never panics, CII in [0,1], +determinism, summary consistency +* [x] *Aspect tests* (20): Security (null bytes, ReDoS), robustness +(unicode, line endings, BOM), concurrency (shared analyzer, consistent +results), performance +* [x] *Benchmarks* (Criterion): Single-file throughput (100/1000/10000 +lines), language detection, config loading, pattern matching, CII calc, +multi-language + +==== Test Summary + +* *Total tests*: 55 tests across all categories (unit + e2e + property + +aspect) +* *Pass rate*: 100% (3+16+16+20=55 tests passing) +* *Coverage*: detection.rs, analyzer.rs, language.rs, patterns.rs, +config.rs fully tested +* *CRG Grade*: C (comprehensive test coverage, property tests, +benchmarks baselined) + +=== CRG Grade: B — ACHIEVED 2026-04-04 + +____ +CRG B achieved 2026-04-04: Ran `+vex-lazy-eliminator check+` on 6 +diverse Rust files from external repos. +____ + +=== CRG B Evidence — External Targets + +[width="100%",cols="31%,13%,38%,18%",options="header",] +|=== +|Target Repo |File |What Was Tested |Result +|protocol-squisher |crates/shape-ir/src/lib.rs |Incompleteness check +|PASS: CII=0.0, no patterns + +|protocol-squisher |crates/cli/src/main.rs |Incompleteness check |4 +placeholders (CII=0.800) + +|panic-attacker |src/lib.rs |Incompleteness check |PASS: CII=0.0, no +patterns + +|panic-attacker |src/main.rs |Incompleteness check |4 placeholders +(CII=0.800) + +|boj-server |tools/cartridge-minter/src/main.rs |Incompleteness check |4 +placeholders (CII=0.800) + +|gossamer |bindings/rust/src/lib.rs |Incompleteness check |1 placeholder +(CII=0.800) +|=== + +==== Target Details + +*1. protocol-squisher shape-ir (Rust library)* - Command: +`+vex-lazy-eliminator check /var/mnt/eclipse/repos/protocol-squisher/crates/shape-ir/src/lib.rs+` +- Key findings: No incompleteness detected (CII: 0.0). Clean library +code. + +*2. protocol-squisher CLI (Rust binary)* - Command: +`+vex-lazy-eliminator check /var/mnt/eclipse/repos/protocol-squisher/crates/protocol-squisher-cli/src/main.rs+` +- Key findings: 4 placeholder patterns at lines 910, 2213, 2334, 2644. +Severity: 0.80 each. CII: 0.800. + +*3. panic-attacker lib.rs (Rust library)* - Command: +`+vex-lazy-eliminator check /var/mnt/eclipse/repos/games-ecosystem/panic-attacker/src/lib.rs+` +- Key findings: No incompleteness detected (CII: 0.0). Clean library +exports. + +*4. panic-attacker main.rs (Rust binary)* - Command: +`+vex-lazy-eliminator check /var/mnt/eclipse/repos/games-ecosystem/panic-attacker/src/main.rs+` +- Key findings: 4 placeholder patterns at lines 1928, 1954, 2054, 2056. +Severity: 0.80. Large CLI entry point with some TODO-like placeholders. + +*5. boj-server cartridge-minter (Rust tool)* - Command: +`+vex-lazy-eliminator check /var/mnt/eclipse/repos/boj-server/tools/cartridge-minter/src/main.rs+` +- Key findings: 4 placeholder patterns at lines 149, 163, 177, 191. +Template scaffolding code with expected placeholders. + +*6. gossamer Rust bindings (Rust FFI)* - Command: +`+vex-lazy-eliminator check /var/mnt/eclipse/repos/gossamer/bindings/rust/src/lib.rs+` +- Key findings: 1 placeholder pattern at line 585. Severity: 0.80. FFI +binding with one incomplete section. + +==== Observations + +* *Language support*: Currently Rust-only. Gleam, Elixir, Zig, ReScript +all returned "`Unsupported language`" errors. +* *Detection quality*: Correctly distinguishes clean libraries (CII=0.0) +from binaries with placeholder/TODO patterns (CII=0.800). +* *False positive rate*: Low — all detected patterns appear to be +genuine placeholders in large files. + +Both sub-projects now at CRG Grade B: + +[cols=",,",options="header",] +|=== +|Sub-project |Tests |Status +|lazy-eliminator (Rust) |55 |CRG C complete +|vexometer (Ada) |1282 |CRG C complete 2026-04-04 +|=== + +=== Remaining Work (Ada/Idris2 ABI - P2 after CRG C) + +==== P2P Tests (Ada) + +* [ ] No tests for vexometer <-> satellite communication +* [ ] No tests for probe -> metrics -> reports pipeline + +==== E2E Tests (Ada, CRITICAL) + +* [ ] No test running vexometer against a real project and generating +metrics +* [ ] No test for satellite deployment and data collection + +==== Build & Execution + +* [ ] No Ada compilation verification test +* [ ] All Zig FFI tests are template placeholders +* [ ] No Idris2 ABI compilation test + +=== Priority: P1 (Ada/Idris2 testing) + +=== Status + +*lazy-eliminator (Rust)*: CRG C complete — 55 tests +(unit+E2E+property+aspect), benchmarks baselined *vexometer (Ada)*: +Remaining work for full project CRG C (satellite comms, E2E pipeline) diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 0afb1fb..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,107 +0,0 @@ - -# TEST-NEEDS: vexometer - -## Current State - -| Category | Count | Details | -|----------|-------|---------| -| **Source modules** | 24+ | Ada specs (10: api, cii, core, gui, metrics, patterns, probes, rci, reports, sfr) + bodies, 3 Idris2 ABI per sub-project (vexometer, vexometer-satellites, satellite-template), Zig FFI | -| **Unit tests** | 4 files | test_runner.adb (~36 assertions) + 3 analyzer.rs unit tests | -| **E2E tests** | 1 file | e2e_test.rs (16 tests - full pipeline analysis, multi-language, CII calc) | -| **Property tests** | 1 file | property_test.rs (16 tests - proptest: analysis never panics, CII ranges, determinism) | -| **Aspect tests** | 1 file | aspect_test.rs (20 tests - security, robustness, concurrency) | -| **Benchmarks** | 1 file | detection_bench.rs (Criterion: throughput, language detection, CII calc) | - -## What's Completed (CRG D→C Blitz) - -### ✓ Lazy-Eliminator (Rust sub-project) - CRG C Achieved -- [x] **Unit tests** (3): Python TODO, Rust unimplemented, complete code -- [x] **E2E tests** (16): Full pipeline, multi-language, CII calculation, detections -- [x] **Property tests** (16): Analysis never panics, CII in [0,1], determinism, summary consistency -- [x] **Aspect tests** (20): Security (null bytes, ReDoS), robustness (unicode, line endings, BOM), concurrency (shared analyzer, consistent results), performance -- [x] **Benchmarks** (Criterion): Single-file throughput (100/1000/10000 lines), language detection, config loading, pattern matching, CII calc, multi-language - -### Test Summary -- **Total tests**: 55 tests across all categories (unit + e2e + property + aspect) -- **Pass rate**: 100% (3+16+16+20=55 tests passing) -- **Coverage**: detection.rs, analyzer.rs, language.rs, patterns.rs, config.rs fully tested -- **CRG Grade**: C (comprehensive test coverage, property tests, benchmarks baselined) - -## CRG Grade: B — ACHIEVED 2026-04-04 - -> CRG B achieved 2026-04-04: Ran `vex-lazy-eliminator check` on 6 diverse Rust files from external repos. - -## CRG B Evidence — External Targets - -| Target Repo | File | What Was Tested | Result | -|-------------|------|-----------------|--------| -| protocol-squisher | crates/shape-ir/src/lib.rs | Incompleteness check | PASS: CII=0.0, no patterns | -| protocol-squisher | crates/cli/src/main.rs | Incompleteness check | 4 placeholders (CII=0.800) | -| panic-attacker | src/lib.rs | Incompleteness check | PASS: CII=0.0, no patterns | -| panic-attacker | src/main.rs | Incompleteness check | 4 placeholders (CII=0.800) | -| boj-server | tools/cartridge-minter/src/main.rs | Incompleteness check | 4 placeholders (CII=0.800) | -| gossamer | bindings/rust/src/lib.rs | Incompleteness check | 1 placeholder (CII=0.800) | - -### Target Details - -**1. protocol-squisher shape-ir (Rust library)** -- Command: `vex-lazy-eliminator check /var/mnt/eclipse/repos/protocol-squisher/crates/shape-ir/src/lib.rs` -- Key findings: No incompleteness detected (CII: 0.0). Clean library code. - -**2. protocol-squisher CLI (Rust binary)** -- Command: `vex-lazy-eliminator check /var/mnt/eclipse/repos/protocol-squisher/crates/protocol-squisher-cli/src/main.rs` -- Key findings: 4 placeholder patterns at lines 910, 2213, 2334, 2644. Severity: 0.80 each. CII: 0.800. - -**3. panic-attacker lib.rs (Rust library)** -- Command: `vex-lazy-eliminator check /var/mnt/eclipse/repos/games-ecosystem/panic-attacker/src/lib.rs` -- Key findings: No incompleteness detected (CII: 0.0). Clean library exports. - -**4. panic-attacker main.rs (Rust binary)** -- Command: `vex-lazy-eliminator check /var/mnt/eclipse/repos/games-ecosystem/panic-attacker/src/main.rs` -- Key findings: 4 placeholder patterns at lines 1928, 1954, 2054, 2056. Severity: 0.80. Large CLI entry point with some TODO-like placeholders. - -**5. boj-server cartridge-minter (Rust tool)** -- Command: `vex-lazy-eliminator check /var/mnt/eclipse/repos/boj-server/tools/cartridge-minter/src/main.rs` -- Key findings: 4 placeholder patterns at lines 149, 163, 177, 191. Template scaffolding code with expected placeholders. - -**6. gossamer Rust bindings (Rust FFI)** -- Command: `vex-lazy-eliminator check /var/mnt/eclipse/repos/gossamer/bindings/rust/src/lib.rs` -- Key findings: 1 placeholder pattern at line 585. Severity: 0.80. FFI binding with one incomplete section. - -### Observations - -- **Language support**: Currently Rust-only. Gleam, Elixir, Zig, ReScript all returned "Unsupported language" errors. -- **Detection quality**: Correctly distinguishes clean libraries (CII=0.0) from binaries with placeholder/TODO patterns (CII=0.800). -- **False positive rate**: Low — all detected patterns appear to be genuine placeholders in large files. - -Both sub-projects now at CRG Grade B: - -| Sub-project | Tests | Status | -|-------------|-------|--------| -| lazy-eliminator (Rust) | 55 | CRG C complete | -| vexometer (Ada) | 1282 | CRG C complete 2026-04-04 | - -## Remaining Work (Ada/Idris2 ABI - P2 after CRG C) - -### P2P Tests (Ada) -- [ ] No tests for vexometer <-> satellite communication -- [ ] No tests for probe -> metrics -> reports pipeline - -### E2E Tests (Ada, CRITICAL) -- [ ] No test running vexometer against a real project and generating metrics -- [ ] No test for satellite deployment and data collection - -### Build & Execution -- [ ] No Ada compilation verification test -- [ ] All Zig FFI tests are template placeholders -- [ ] No Idris2 ABI compilation test - -## Priority: P1 (Ada/Idris2 testing) - -## Status - -**lazy-eliminator (Rust)**: CRG C complete — 55 tests (unit+E2E+property+aspect), benchmarks baselined -**vexometer (Ada)**: Remaining work for full project CRG C (satellite comms, E2E pipeline) diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 85% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index c9d0710..1388033 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,17 +1,14 @@ - - - +== VEX Toolkit (vexometer) — Project Topology -# VEX Toolkit (vexometer) — Project Topology +____ +Naming convention: *The Vexometer: Irritation Surface Analyser (ISA) for +LLMs and related tools* is the canonical title, and *vexometer* remains +the compatibility identifier in repo/package/CLI/protocol names. +____ -> Naming convention: **The Vexometer: Irritation Surface Analyser (ISA) for LLMs and related tools** is the canonical title, and **vexometer** remains the compatibility identifier in repo/package/CLI/protocol names. +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ OPERATOR / AI │ │ (Analysis, Comm, Intervention) │ @@ -46,11 +43,11 @@ Copyright (c) Jonathan D.A. Jewell │ Justfile Automation .machine_readable/ │ │ Docs + Roadmaps Monorepo Hygiene │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── ISA & INTERVENTION @@ -71,25 +68,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ███████░░░ ~70% Core operational; ecosystem integration still maturing -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Lazy Patterns ───► Eliminator Engine ──► ISA Score ───► Intervention │ │ │ │ ▼ ▼ ▼ ▼ Comm Event ──────► Vext Protocol ──────► Email Gateway ──────► Recipient -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..b68035a --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,70 @@ +== Tech-Debt Audit — vexometer — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+2026-05-22+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +Scanner counted the following markers in proof-bearing files of this +repo: + +.... +files= 39 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 +.... + +*Total markers:* 0. *Severity:* `+>00+`. + +*Recommended next move:* none — no proof-debt markers detected. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |84 +|`+docs/+` files |2 +|`+docs/+` LoC |260 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+readme=84 docs=2/260+` +|=== + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 1875fcd..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,61 +0,0 @@ - -# Tech-Debt Audit — vexometer — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `2026-05-22`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -Scanner counted the following markers in proof-bearing files of this repo: - -``` -files= 39 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 -``` - -**Total markers:** 0. **Severity:** `>00`. - -**Recommended next move:** none — no proof-debt markers detected. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 84 | -| `docs/` files | 2 | -| `docs/` LoC | 260 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `readme=84 docs=2/260` | - - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/satellite-template/ABI-FFI-README.md b/lazy-eliminator/ABI-FFI-README.adoc similarity index 74% rename from satellite-template/ABI-FFI-README.md rename to lazy-eliminator/ABI-FFI-README.adoc index ada05ff..f1163e3 100644 --- a/satellite-template/ABI-FFI-README.md +++ b/lazy-eliminator/ABI-FFI-README.adoc @@ -1,23 +1,22 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -101,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -115,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -129,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -144,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -219,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -241,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -263,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -346,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/lazy-eliminator/CODE_OF_CONDUCT.md b/lazy-eliminator/CODE_OF_CONDUCT.adoc similarity index 54% rename from lazy-eliminator/CODE_OF_CONDUCT.md rename to lazy-eliminator/CODE_OF_CONDUCT.adoc index a693a3f..240b562 100644 --- a/lazy-eliminator/CODE_OF_CONDUCT.md +++ b/lazy-eliminator/CODE_OF_CONDUCT.adoc @@ -1,15 +1,11 @@ - -# Contributor Covenant Code of Conduct +== Contributor Covenant Code of Conduct -## Our Pledge +=== Our Pledge -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone. +We as members, contributors, and leaders pledge to make participation in +our community a harassment-free experience for everyone. -## Our Standards +=== Our Standards Examples of behavior that contributes to a positive environment: @@ -20,16 +16,18 @@ Examples of behavior that contributes to a positive environment: Examples of unacceptable behavior: -* Trolling, insulting/derogatory comments, and personal or political attacks +* Trolling, insulting/derogatory comments, and personal or political +attacks * Public or private harassment -* Publishing others' private information without explicit permission +* Publishing others’ private information without explicit permission -## Enforcement +=== Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to security@jewell.dev. All complaints will be reviewed and investigated -promptly and fairly. +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to security@jewell.dev. All complaints will be reviewed and +investigated promptly and fairly. -## Attribution +=== Attribution -This Code of Conduct is adapted from the Contributor Covenant, version 2.1. +This Code of Conduct is adapted from the Contributor Covenant, version +2.1. diff --git a/lazy-eliminator/CONTRIBUTING.adoc b/lazy-eliminator/CONTRIBUTING.adoc index b7728fa..73767d3 100644 --- a/lazy-eliminator/CONTRIBUTING.adoc +++ b/lazy-eliminator/CONTRIBUTING.adoc @@ -1,113 +1,108 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Contributing to vex-lazy-eliminator -:toc: +== Clone the repository -== Welcome +git clone https://github.com/hyperpolymath/vexometer.git cd vexometer -Thank you for contributing! This satellite is part of the vexometer ecosystem. +== Using Nix (recommended for reproducibility) -== How to Contribute +nix develop -=== 1. Set Up Development Environment +== Or using toolbox/distrobox -[source,bash] ----- -# Clone the repository -git clone https://github.com/hyperpolymath/vex-lazy-eliminator -cd vex-lazy-eliminator +toolbox create vexometer-dev toolbox enter vexometer-dev # Install +dependencies manually -# Build -just build +== Verify setup -# Run tests -just test +just check # or: cargo check / mix compile / etc. just test # Run test +suite -# Check code quality -just check ----- +.... -=== 2. Areas for Contribution +### Repository Structure +.... -[cols="2,3,2", options="header"] -|=== -|Area |Examples |Difficulty +vexometer/ ├── 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) │ ├── ISSUE_TEMPLATE/ │ +└── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── +CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.nix # Nix flake +(Perimeter 1) └── Justfile # Task runner (Perimeter 1) -|Pattern Refinement -|Improve detection accuracy, add new patterns -|Easy +.... -|Language Support -|Add C++, C#, Swift, etc. -|Medium +--- -|Efficacy Validation -|Collect before/after traces, statistical analysis -|Medium +## How to Contribute -|Performance -|Optimize AST traversal, parallel processing -|Hard +### Reporting Bugs -|Integration -|CI/CD plugins, IDE extensions -|Medium -|=== +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects -=== 3. Code Standards +**When reporting**: -* **Rust style**: Use `cargo fmt` and `cargo clippy` -* **SPDX headers**: All files must have `// SPDX-License-Identifier: CC-BY-SA-4.0` -* **Tests**: Add tests for new features -* **Documentation**: rustdoc comments for public APIs +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: -=== 4. Pull Request Process +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction -1. Fork the repository -2. Create a branch: `git checkout -b improve-python-detection` -3. Make changes with SPDX headers -4. Run `just check` and `just test` -5. Commit with conventional commits: -+ -[source] ----- -feat: add support for Python walrus operator -fix: reduce false positives for empty blocks -docs: update README with new examples ----- -6. Submit PR with clear description +### Suggesting Features -=== 5. Pattern Contribution Guidelines +**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 adding new incompleteness patterns: +**When suggesting**: -1. **Provide examples**: Show code that should be detected -2. **Test false positives**: Ensure legitimate code isn't flagged -3. **Severity justification**: Explain severity score assignment -4. **Multi-language**: Consider if pattern applies to other languages +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: -Example PR: +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects -[source] ----- -feat: detect Python ... in type annotations +### Your First Contribution -Adds detection for ellipsis (...) in type stubs: +Look for issues labelled: - def foo() -> int: ... +- [`good first issue`](https://github.com/hyperpolymath/vexometer/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/vexometer/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/vexometer/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/vexometer/labels/perimeter-3) — Community sandbox scope -Severity: 0.8 (PlaceholderText) -Applies to: Python only -False positive rate: <1% (tested on 1000 files) ----- +--- -== Community +## Development Workflow -* **Questions**: Open a GitHub Discussion -* **Bugs**: Open an issue with `bug` label -* **Features**: Open an issue with `enhancement` label +### Branch Naming +.... -## License +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) -By contributing, you agree that your contributions will be licensed under MPL-2.0. +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/lazy-eliminator/CONTRIBUTING.md b/lazy-eliminator/CONTRIBUTING.md deleted file mode 100644 index ad79057..0000000 --- a/lazy-eliminator/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/vexometer.git -cd vexometer - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create vexometer-dev -toolbox enter vexometer-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -vexometer/ -├── 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) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── 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](.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/vexometer/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/vexometer/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/vexometer/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/vexometer/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/lazy-eliminator/SECURITY.adoc b/lazy-eliminator/SECURITY.adoc new file mode 100644 index 0000000..816454c --- /dev/null +++ b/lazy-eliminator/SECURITY.adoc @@ -0,0 +1,61 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +*Do not report security vulnerabilities through public GitHub issues.* + +Instead, please report them via email to: *security@jewell.dev* + +Include: - Description of the vulnerability - Steps to reproduce - +Potential impact - Suggested fix (if any) + +You will receive a response within 48 hours. If confirmed, we will: 1. +Acknowledge the report 2. Work on a fix 3. Release a patch 4. Credit you +(unless you prefer anonymity) + +=== Security Measures + +==== Language Safety + +* Rust provides memory safety without GC +* No unsafe code blocks in core library +* All dependencies audited via cargo-audit + +==== Input Validation + +* Code analysis is read-only (no execution) +* File paths validated before reading +* Regex patterns compiled once, validated + +==== Dependencies + +* tree-sitter: Parser generator (trusted, maintained by GitHub) +* clap: CLI parsing (widely used, audited) +* serde: Serialization (de facto standard, audited) + +All dependencies pinned with Cargo.lock for reproducibility. + +=== Threat Model + +This tool analyzes potentially untrusted code: + +[arabic] +. *Malicious code patterns*: Analyzer reads but never executes code +. *Path traversal*: File paths validated, no symlink following +. *ReDoS attacks*: Regex patterns designed to avoid catastrophic +backtracking +. *Supply chain*: Dependencies audited, Cargo.lock committed + +=== Disclosure Policy + +* We follow responsible disclosure +* 90-day disclosure timeline after patch release +* Security advisories published via GitHub Security Advisories diff --git a/lazy-eliminator/SECURITY.md b/lazy-eliminator/SECURITY.md deleted file mode 100644 index e2c55d5..0000000 --- a/lazy-eliminator/SECURITY.md +++ /dev/null @@ -1,67 +0,0 @@ - - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 0.1.x | :white_check_mark: | - -## Reporting a Vulnerability - -**Do not report security vulnerabilities through public GitHub issues.** - -Instead, please report them via email to: **security@jewell.dev** - -Include: -- Description of the vulnerability -- Steps to reproduce -- Potential impact -- Suggested fix (if any) - -You will receive a response within 48 hours. If confirmed, we will: -1. Acknowledge the report -2. Work on a fix -3. Release a patch -4. Credit you (unless you prefer anonymity) - -## Security Measures - -### Language Safety - -- Rust provides memory safety without GC -- No unsafe code blocks in core library -- All dependencies audited via cargo-audit - -### Input Validation - -- Code analysis is read-only (no execution) -- File paths validated before reading -- Regex patterns compiled once, validated - -### Dependencies - -- tree-sitter: Parser generator (trusted, maintained by GitHub) -- clap: CLI parsing (widely used, audited) -- serde: Serialization (de facto standard, audited) - -All dependencies pinned with Cargo.lock for reproducibility. - -## Threat Model - -This tool analyzes potentially untrusted code: - -1. **Malicious code patterns**: Analyzer reads but never executes code -2. **Path traversal**: File paths validated, no symlink following -3. **ReDoS attacks**: Regex patterns designed to avoid catastrophic backtracking -4. **Supply chain**: Dependencies audited, Cargo.lock committed - -## Disclosure Policy - -- We follow responsible disclosure -- 90-day disclosure timeline after patch release -- Security advisories published via GitHub Security Advisories diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..2afc80e --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — vexometer (Developer) + +=== What is vexometer? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 94c48a3..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — vexometer (Developer) - -## What is vexometer? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..3acd571 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — vexometer (User) + +=== What is vexometer? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index c4c3f3e..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — vexometer (User) - -## What is vexometer? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/lazy-eliminator/ABI-FFI-README.md b/satellite-template/ABI-FFI-README.adoc similarity index 74% rename from lazy-eliminator/ABI-FFI-README.md rename to satellite-template/ABI-FFI-README.adoc index ada05ff..f1163e3 100644 --- a/lazy-eliminator/ABI-FFI-README.md +++ b/satellite-template/ABI-FFI-README.adoc @@ -1,23 +1,22 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -101,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -115,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -129,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -144,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -219,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -241,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -263,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -346,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/satellite-template/CODE_OF_CONDUCT.adoc b/satellite-template/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/satellite-template/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/satellite-template/CODE_OF_CONDUCT.md b/satellite-template/CODE_OF_CONDUCT.md deleted file mode 100644 index bbe9219..0000000 --- a/satellite-template/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,30 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/satellite-template/CONTRIBUTING.adoc b/satellite-template/CONTRIBUTING.adoc index e9b1993..73767d3 100644 --- a/satellite-template/CONTRIBUTING.adoc +++ b/satellite-template/CONTRIBUTING.adoc @@ -1,21 +1,108 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Contributing Guide +== Clone the repository -== Getting Started +git clone https://github.com/hyperpolymath/vexometer.git cd vexometer -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +== Using Nix (recommended for reproducibility) -== Commit Guidelines +nix develop -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +== Or using toolbox/distrobox -== License +toolbox create vexometer-dev toolbox enter vexometer-dev # Install +dependencies manually -Contributions licensed under project license. +== Verify setup +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +vexometer/ ├── 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) │ ├── ISSUE_TEMPLATE/ │ +└── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── +CONTRIBUTING.md # This file ├── 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](.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/vexometer/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/vexometer/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/vexometer/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/vexometer/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/satellite-template/CONTRIBUTING.md b/satellite-template/CONTRIBUTING.md deleted file mode 100644 index ad79057..0000000 --- a/satellite-template/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/vexometer.git -cd vexometer - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create vexometer-dev -toolbox enter vexometer-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -vexometer/ -├── 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) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── 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](.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/vexometer/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/vexometer/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/vexometer/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/vexometer/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/satellite-template/SECURITY.adoc b/satellite-template/SECURITY.adoc new file mode 100644 index 0000000..a2e39b3 --- /dev/null +++ b/satellite-template/SECURITY.adoc @@ -0,0 +1,30 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|main |:white_check_mark: +|< main |:x: +|=== + +=== Reporting a Vulnerability + +Please report security vulnerabilities through GitHub private +vulnerability reporting: 1. Go to the *Security* tab 2. Click *Report a +vulnerability* 3. Fill out the form + +We respond within 48 hours. + +=== Security Measures + +* Dependabot for dependency updates +* CodeQL for code scanning +* Secret scanning and push protection + +=== Security Contact + +* Advisories: +https://github.com/hyperpolymath/vexometer/security/advisories/new +* Email: security@jewell.dev diff --git a/satellite-template/SECURITY.md b/satellite-template/SECURITY.md deleted file mode 100644 index ec52be5..0000000 --- a/satellite-template/SECURITY.md +++ /dev/null @@ -1,33 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| main | :white_check_mark: | -| < main | :x: | - -## Reporting a Vulnerability - -Please report security vulnerabilities through GitHub private vulnerability reporting: -1. Go to the **Security** tab -2. Click **Report a vulnerability** -3. Fill out the form - -We respond within 48 hours. - -## Security Measures - -- Dependabot for dependency updates -- CodeQL for code scanning -- Secret scanning and push protection - - -## Security Contact - -- Advisories: https://github.com/hyperpolymath/vexometer/security/advisories/new -- Email: security@jewell.dev diff --git a/vexometer-satellites/ABI-FFI-README.md b/vexometer-satellites/ABI-FFI-README.adoc similarity index 74% rename from vexometer-satellites/ABI-FFI-README.md rename to vexometer-satellites/ABI-FFI-README.adoc index ada05ff..f1163e3 100644 --- a/vexometer-satellites/ABI-FFI-README.md +++ b/vexometer-satellites/ABI-FFI-README.adoc @@ -1,23 +1,22 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -101,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -115,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -129,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -144,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -219,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -241,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -263,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -346,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/vexometer-satellites/CODE_OF_CONDUCT.adoc b/vexometer-satellites/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..54f0cf2 --- /dev/null +++ b/vexometer-satellites/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +vexometer 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. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |j.d.a.jewell@open.ac.uk |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* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *72 hours* +. The maintainer team will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a maintainer team member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The maintainer team will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* j.d.a.jewell@open.ac.uk with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different maintainer team member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/vexometer/discussions[Discussion] (for +general questions) +* Email j.d.a.jewell@open.ac.uk (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/vexometer-satellites/CODE_OF_CONDUCT.md b/vexometer-satellites/CODE_OF_CONDUCT.md deleted file mode 100644 index 93da148..0000000 --- a/vexometer-satellites/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,311 +0,0 @@ - -# Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in vexometer 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. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | j.d.a.jewell@open.ac.uk | 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** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **72 hours** -2. The maintainer team 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) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a maintainer team member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The maintainer team will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** j.d.a.jewell@open.ac.uk 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 maintainer team member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/vexometer/discussions) (for general questions) -- Email j.d.a.jewell@open.ac.uk (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/vexometer-satellites/CONTRIBUTING.adoc b/vexometer-satellites/CONTRIBUTING.adoc index 03ab9be..73767d3 100644 --- a/vexometer-satellites/CONTRIBUTING.adoc +++ b/vexometer-satellites/CONTRIBUTING.adoc @@ -1,177 +1,108 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Contributing to Vexometer Satellites -:toc: +== Clone the repository -== Overview - -This umbrella repository coordinates the vexometer satellite ecosystem. Contributions fall into three categories: - -1. **Documentation improvements** (this repo) -2. **Protocol enhancements** (this repo) -3. **Satellite implementations** (individual satellite repos) - -== Contributing to This Repository - -=== What to Contribute +git clone https://github.com/hyperpolymath/vexometer.git cd vexometer -[cols="2,3,2", options="header"] -|=== -|Category |Examples |Review Required +== Using Nix (recommended for reproducibility) -|Documentation -|Fix typos, clarify protocols, improve examples -|Standard PR review - -|Satellite Registry -|Add new satellite, update status, fix links -|Maintainer approval required +nix develop -|Protocol Changes -|Modify vexometer-trace-v1 or efficacy-v1 schemas -|Requires vexometer team approval +== Or using toolbox/distrobox -|Tooling -|Validation scripts, CI improvements, automation -|Standard PR review -|=== +toolbox create vexometer-dev toolbox enter vexometer-dev # Install +dependencies manually -=== How to Contribute +== Verify setup -1. **Fork** this repository -2. **Create a branch**: `git checkout -b improve-docs` -3. **Make changes**: - - Add SPDX headers: `// SPDX-License-Identifier: CC-BY-SA-4.0` - - Use AsciiDoc for documentation - - Validate JSON schemas if modifying protocols -4. **Test locally**: -+ -[source,bash] ----- -just check # Runs linters and validators ----- -5. **Submit PR** with clear description +just check # or: cargo check / mix compile / etc. just test # Run test +suite -=== Code Standards +.... -* **AsciiDoc**: Use for all documentation (not Markdown) -* **SPDX Headers**: All files must have license headers -* **Links**: Verify all external links work -* **Status Accuracy**: Satellite registry must reflect actual repo state +### Repository Structure +.... -=== Commit Messages +vexometer/ ├── 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) │ ├── ISSUE_TEMPLATE/ │ +└── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── +CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.nix # Nix flake +(Perimeter 1) └── Justfile # Task runner (Perimeter 1) -Use conventional commits: +.... -[source] ----- -docs: fix typo in integration protocol -feat: add vex-lazy-eliminator to registry -chore: update satellite status badges ----- - -== Contributing New Satellites - -To create a new satellite: - -1. **Use the template**: -+ -[source,bash] ----- -gh repo create hyperpolymath/vex-YOUR-SATELLITE \ - --template hyperpolymath/vex-satellite-template \ - --public ----- - -2. **Implement the intervention**: - - Choose appropriate language (Rust, Ada, Haskell, Elixir) - - Follow RSR standards - - Include comprehensive tests - -3. **Validate efficacy**: - - Collect ≥50 before/after traces - - Run statistical analysis (p < 0.05) - - Document in EFFICACY.adoc - -4. **Register here**: - - Add entry to satellite registry table in README.adoc - - Include: name, status (🚧), metrics reduced, description, language - - Link to your repository - - Submit PR to this repo +--- -=== Satellite Requirements +## How to Contribute -All satellites must: +### Reporting Bugs -* ✅ Use RSR-compliant structure -* ✅ Include SECURITY.md, CONTRIBUTING.adoc, CODE_OF_CONDUCT.md -* ✅ Pass OpenSSF Scorecard checks -* ✅ Use memory-safe language (no Python, JavaScript, Go) -* ✅ Include unit tests (≥80% coverage) -* ✅ Provide before/after traces in vexometer-trace-v1 format -* ✅ Document efficacy with statistical validation +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects -See link:docs/satellite-checklist.adoc[satellite-checklist.adoc] for full requirements. +**When reporting**: -== Protocol Change Process +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: -Changes to integration protocols (vexometer-trace-v1, vexometer-efficacy-v1) require: +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction -1. **Discussion**: Open issue describing proposed change -2. **Consensus**: Agreement from vexometer maintainers + ≥2 satellite maintainers -3. **Version bump**: Create new protocol version (don't break existing) -4. **Documentation**: Update specs in docs/ -5. **Implementation**: Update vexometer validation tooling -6. **Migration period**: Support old version for ≥6 months +### Suggesting Features -== Review Process +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to -=== Documentation PRs +**When suggesting**: -* Reviewed by any maintainer -* Merged within 1 week -* Focus: accuracy, clarity, links work +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: -=== Satellite Registry PRs +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects -* Reviewed by maintainer -* Verification required: - - Repository exists - - Meets satellite requirements - - CI passing - - SECURITY.md present -* Merged within 2 weeks +### Your First Contribution -=== Protocol Change PRs +Look for issues labelled: -* Reviewed by vexometer team + satellite maintainers -* Requires consensus (may take 1+ months) -* Backwards compatibility required +- [`good first issue`](https://github.com/hyperpolymath/vexometer/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/vexometer/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/vexometer/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/vexometer/labels/perimeter-3) — Community sandbox scope -== Community Standards +--- -All contributors must follow: +## Development Workflow -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:GOVERNANCE.md[Governance Model] -* link:https://github.com/hyperpolymath/rhodium-standard-repositories[RSR Standards] +### Branch Naming +.... -== Getting Help +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) -* **Questions**: Open a GitHub Discussion -* **Bug reports**: Open an issue with `bug` label -* **Feature requests**: Open an issue with `enhancement` label -* **Chat**: Join #vexometer on our Discord (link TBD) +.... -== Recognition +### Commit Messages -Contributors will be: +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... -* Listed in CONTRIBUTORS.md -* Credited in release notes -* Acknowledged in research papers (if substantial contribution) +(): ---- +{empty}[optional body] -Thank you for contributing to the vexometer satellite ecosystem! +{empty}[optional footer] diff --git a/vexometer-satellites/CONTRIBUTING.md b/vexometer-satellites/CONTRIBUTING.md deleted file mode 100644 index ad79057..0000000 --- a/vexometer-satellites/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/vexometer.git -cd vexometer - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create vexometer-dev -toolbox enter vexometer-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -vexometer/ -├── 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) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── 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](.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/vexometer/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/vexometer/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/vexometer/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/vexometer/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/vexometer-satellites/SECURITY.adoc b/vexometer-satellites/SECURITY.adoc new file mode 100644 index 0000000..a617c2b --- /dev/null +++ b/vexometer-satellites/SECURITY.adoc @@ -0,0 +1,87 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|1.x |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +*Do not report security vulnerabilities through public GitHub issues.* + +Instead, please report them via email to: *security@jewell.dev* + +Include: - Description of the vulnerability - Steps to reproduce - +Potential impact - Suggested fix (if any) + +You will receive a response within 48 hours. If confirmed, we will: 1. +Acknowledge the report 2. Work on a fix 3. Release a patch 4. Credit you +(unless you prefer anonymity) + +=== Scope + +==== This Repository + +This umbrella repository contains: - Documentation only (no executable +code) - JSON schema definitions for protocols - Satellite registry +metadata + +Security concerns: - Malicious satellite registry entries - Protocol +specification attacks - Documentation injection + +==== Individual Satellites + +Each satellite has its own SECURITY.md. Report satellite-specific +vulnerabilities to that satellite’s maintainers. + +=== Security Measures + +==== Documentation Integrity + +* All protocol specs version-controlled +* Changes reviewed by maintainers +* SPDX headers track provenance + +==== Satellite Registry + +* Links verified before merge +* Status updates require proof (repo existence, CI passing) +* No executable code in registry metadata + +==== Protocol Design + +* vexometer-trace-v1: Read-only format (no code execution) +* vexometer-efficacy-v1: Statistical claims only (no side effects) +* JSON schemas validated against injection attacks + +=== Threat Model + +This repository coordinates 12+ independent satellites. Threat vectors: + +[arabic] +. *Malicious satellite registration*: Attacker adds backdoored satellite +to registry +* _Mitigation_: Manual review of all registry additions +. *Protocol manipulation*: Attacker modifies integration protocol to +allow code injection +* _Mitigation_: Version-controlled specs, schema validation +. *Documentation injection*: Attacker embeds malicious links/scripts in +docs +* _Mitigation_: AsciiDoc parser security, link verification +. *Supply chain attack*: Attacker compromises satellite template +* _Mitigation_: vex-satellite-template has independent security review + +=== Satellite Security Standards + +All registered satellites MUST: + +* Include SECURITY.md +* Pass OpenSSF Scorecard +* Use memory-safe languages (Rust, Ada, Haskell, Elixir) +* Pin all dependencies with SHA hashes +* Enable branch protection (required reviews) + +Satellites failing security standards will be marked ⚠️ in registry. diff --git a/vexometer-satellites/SECURITY.md b/vexometer-satellites/SECURITY.md deleted file mode 100644 index d909ef5..0000000 --- a/vexometer-satellites/SECURITY.md +++ /dev/null @@ -1,96 +0,0 @@ - - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 1.x | :white_check_mark: | - -## Reporting a Vulnerability - -**Do not report security vulnerabilities through public GitHub issues.** - -Instead, please report them via email to: **security@jewell.dev** - -Include: -- Description of the vulnerability -- Steps to reproduce -- Potential impact -- Suggested fix (if any) - -You will receive a response within 48 hours. If confirmed, we will: -1. Acknowledge the report -2. Work on a fix -3. Release a patch -4. Credit you (unless you prefer anonymity) - -## Scope - -### This Repository - -This umbrella repository contains: -- Documentation only (no executable code) -- JSON schema definitions for protocols -- Satellite registry metadata - -Security concerns: -- Malicious satellite registry entries -- Protocol specification attacks -- Documentation injection - -### Individual Satellites - -Each satellite has its own SECURITY.md. Report satellite-specific vulnerabilities to that satellite's maintainers. - -## Security Measures - -### Documentation Integrity - -- All protocol specs version-controlled -- Changes reviewed by maintainers -- SPDX headers track provenance - -### Satellite Registry - -- Links verified before merge -- Status updates require proof (repo existence, CI passing) -- No executable code in registry metadata - -### Protocol Design - -- vexometer-trace-v1: Read-only format (no code execution) -- vexometer-efficacy-v1: Statistical claims only (no side effects) -- JSON schemas validated against injection attacks - -## Threat Model - -This repository coordinates 12+ independent satellites. Threat vectors: - -1. **Malicious satellite registration**: Attacker adds backdoored satellite to registry - - *Mitigation*: Manual review of all registry additions - -2. **Protocol manipulation**: Attacker modifies integration protocol to allow code injection - - *Mitigation*: Version-controlled specs, schema validation - -3. **Documentation injection**: Attacker embeds malicious links/scripts in docs - - *Mitigation*: AsciiDoc parser security, link verification - -4. **Supply chain attack**: Attacker compromises satellite template - - *Mitigation*: vex-satellite-template has independent security review - -## Satellite Security Standards - -All registered satellites MUST: - -- Include SECURITY.md -- Pass OpenSSF Scorecard -- Use memory-safe languages (Rust, Ada, Haskell, Elixir) -- Pin all dependencies with SHA hashes -- Enable branch protection (required reviews) - -Satellites failing security standards will be marked ⚠️ in registry. diff --git a/vexometer/ABI-FFI-README.md b/vexometer/ABI-FFI-README.adoc similarity index 74% rename from vexometer/ABI-FFI-README.md rename to vexometer/ABI-FFI-README.adoc index ada05ff..f1163e3 100644 --- a/vexometer/ABI-FFI-README.md +++ b/vexometer/ABI-FFI-README.adoc @@ -1,23 +1,22 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -101,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -115,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -129,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -144,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -219,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -241,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -263,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -346,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/vexometer/CODE_OF_CONDUCT.adoc b/vexometer/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..f274fe9 --- /dev/null +++ b/vexometer/CODE_OF_CONDUCT.adoc @@ -0,0 +1,42 @@ +== Code of Conduct + +=== Our Pledge + +We pledge to make participation in our project a harassment-free +experience for everyone, regardless of age, body size, disability, +ethnicity, gender identity, level of experience, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +=== Our Standards + +*Positive behaviour includes:* + +* Using welcoming and inclusive language +* Respecting differing viewpoints +* Accepting constructive criticism gracefully +* Focusing on what is best for the community +* Showing empathy towards others + +*Unacceptable behaviour includes:* + +* Harassment, trolling, or personal attacks +* Publishing others’ private information +* Professional or personal attacks +* Other conduct which could reasonably be considered inappropriate + +=== Enforcement + +Project maintainers will remove, edit, or reject contributions that do +not align with this Code of Conduct. Repeated violations may result in a +ban. + +=== Reporting + +Report issues to: *conduct@jewell.dev* + +All complaints will be reviewed and investigated. Confidentiality will +be maintained. + +=== Attribution + +Adapted from the Contributor Covenant, version 2.1. diff --git a/vexometer/CODE_OF_CONDUCT.md b/vexometer/CODE_OF_CONDUCT.md deleted file mode 100644 index f1ea745..0000000 --- a/vexometer/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,46 +0,0 @@ - - -# Code of Conduct - -## Our Pledge - -We pledge to make participation in our project a harassment-free experience -for everyone, regardless of age, body size, disability, ethnicity, gender -identity, level of experience, nationality, personal appearance, race, -religion, or sexual identity and orientation. - -## Our Standards - -**Positive behaviour includes:** - -- Using welcoming and inclusive language -- Respecting differing viewpoints -- Accepting constructive criticism gracefully -- Focusing on what is best for the community -- Showing empathy towards others - -**Unacceptable behaviour includes:** - -- Harassment, trolling, or personal attacks -- Publishing others' private information -- Professional or personal attacks -- Other conduct which could reasonably be considered inappropriate - -## Enforcement - -Project maintainers will remove, edit, or reject contributions that do not -align with this Code of Conduct. Repeated violations may result in a ban. - -## Reporting - -Report issues to: **conduct@jewell.dev** - -All complaints will be reviewed and investigated. Confidentiality will be -maintained. - -## Attribution - -Adapted from the Contributor Covenant, version 2.1. diff --git a/vexometer/CONTRIBUTING.adoc b/vexometer/CONTRIBUTING.adoc index 7d50b0a..73767d3 100644 --- a/vexometer/CONTRIBUTING.adoc +++ b/vexometer/CONTRIBUTING.adoc @@ -1,53 +1,108 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -// SPDX-FileCopyrightText: 2024 Jonathan D.A. Jewell -= Contributing to Vexometer -:toc: +== Clone the repository -== Tri-Perimeter Contribution Framework (TPCF) +git clone https://github.com/hyperpolymath/vexometer.git cd vexometer -=== Perimeter 1 (Core) -Maintainers only. Includes: +== Using Nix (recommended for reproducibility) -* Build system (flake.nix, Justfile) -* Core Ada packages -* Security-critical code +nix develop -=== Perimeter 2 (Expert) -Trusted contributors. Includes: +== Or using toolbox/distrobox -* Pattern definitions -* API provider implementations -* Report generators +toolbox create vexometer-dev toolbox enter vexometer-dev # Install +dependencies manually -=== Perimeter 3 (Community) -Open to all. Includes: +== Verify setup -* Documentation improvements -* Test cases -* Bug reports -* Probe suggestions +just check # or: cargo check / mix compile / etc. just test # Run test +suite -== How to Contribute +.... -1. Fork the repository -2. Create a feature branch -3. Make changes with SPDX headers -4. Submit merge request +### Repository Structure +.... -== Code Standards +vexometer/ ├── 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) │ ├── ISSUE_TEMPLATE/ │ +└── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── +CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.nix # Nix flake +(Perimeter 1) └── Justfile # Task runner (Perimeter 1) -* Ada 2022 style -* SPDX headers on all files -* Tests for new functionality -* Documentation for public APIs +.... -== Commit Messages +--- -Use conventional commits: +## How to Contribute ----- -feat: add new probe for brevity testing -fix: correct regex in sycophancy pattern -docs: update API documentation ----- +### 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/vexometer/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/vexometer/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/vexometer/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/vexometer/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/vexometer/CONTRIBUTING.md b/vexometer/CONTRIBUTING.md deleted file mode 100644 index ad79057..0000000 --- a/vexometer/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/vexometer.git -cd vexometer - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create vexometer-dev -toolbox enter vexometer-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -vexometer/ -├── 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) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── 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](.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/vexometer/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/vexometer/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/vexometer/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/vexometer/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/vexometer/SECURITY.adoc b/vexometer/SECURITY.adoc new file mode 100644 index 0000000..9516b7f --- /dev/null +++ b/vexometer/SECURITY.adoc @@ -0,0 +1,52 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +*Do not report security vulnerabilities through public GitLab issues.* + +Instead, please report them via email to: *security@jewell.dev* + +Include: - Description of the vulnerability - Steps to reproduce - +Potential impact - Suggested fix (if any) + +You will receive a response within 48 hours. If confirmed, we will: 1. +Acknowledge the report 2. Work on a fix 3. Release a patch 4. Credit you +(unless you prefer anonymity) + +=== Security Measures + +==== Language Choice + +* Ada 2022 with SPARK subset for memory safety +* No pointer arithmetic +* Strong type checking at compile time + +==== Dependencies + +* Minimal dependency tree +* All dependencies audited +* Nix for reproducible builds + +==== API Security + +* API keys never logged or stored in plaintext +* Local-first architecture minimises data transmission +* No telemetry without explicit consent + +=== Threat Model + +Vexometer processes potentially sensitive: - User prompts - Model +responses - API credentials + +We assume: - Local execution is trusted - Remote APIs may be compromised +- Pattern databases may be manipulated + +Mitigations are documented in `+docs/SPECIFICATION.md+`. diff --git a/vexometer/SECURITY.md b/vexometer/SECURITY.md deleted file mode 100644 index 6968622..0000000 --- a/vexometer/SECURITY.md +++ /dev/null @@ -1,61 +0,0 @@ - - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 0.1.x | :white_check_mark: | - -## Reporting a Vulnerability - -**Do not report security vulnerabilities through public GitLab issues.** - -Instead, please report them via email to: **security@jewell.dev** - -Include: -- Description of the vulnerability -- Steps to reproduce -- Potential impact -- Suggested fix (if any) - -You will receive a response within 48 hours. If confirmed, we will: -1. Acknowledge the report -2. Work on a fix -3. Release a patch -4. Credit you (unless you prefer anonymity) - -## Security Measures - -### Language Choice -- Ada 2022 with SPARK subset for memory safety -- No pointer arithmetic -- Strong type checking at compile time - -### Dependencies -- Minimal dependency tree -- All dependencies audited -- Nix for reproducible builds - -### API Security -- API keys never logged or stored in plaintext -- Local-first architecture minimises data transmission -- No telemetry without explicit consent - -## Threat Model - -Vexometer processes potentially sensitive: -- User prompts -- Model responses -- API credentials - -We assume: -- Local execution is trusted -- Remote APIs may be compromised -- Pattern databases may be manipulated - -Mitigations are documented in `docs/SPECIFICATION.md`. diff --git a/vexometer/docs/SPECIFICATION.md b/vexometer/docs/SPECIFICATION.adoc similarity index 65% rename from vexometer/docs/SPECIFICATION.md rename to vexometer/docs/SPECIFICATION.adoc index f9de519..7ace537 100644 --- a/vexometer/docs/SPECIFICATION.md +++ b/vexometer/docs/SPECIFICATION.adoc @@ -1,40 +1,41 @@ - -# ISA (formerly Vexometer) - Irritation Surface Analyser +== ISA (formerly Vexometer) - Irritation Surface Analyser -## Project Specification v0.1.0 +=== Project Specification v0.1.0 -**Canonical Name:** ISA -**Legacy Codename:** Vexometer (retained in technical identifiers) -**CLI/Package Identifier:** `vexometer` -**Author:** Jonathan D.A. Jewell -**License:** MPL-2.0 -**Language:** Ada 2022 -**GUI Toolkit:** GtkAda +*Canonical Name:* ISA *Legacy Codename:* Vexometer (retained in +technical identifiers) *CLI/Package Identifier:* `+vexometer+` *Author:* +Jonathan D.A. Jewell *License:* MPL-2.0 *Language:* Ada 2022 *GUI +Toolkit:* GtkAda ---- +''''' -## Purpose +=== Purpose -A rigorous, reproducible tool for quantifying the irritation surface of AI assistants, producing standardised metrics that complement existing benchmarks (MMLU, HumanEval, etc.) with human experience dimensions. +A rigorous, reproducible tool for quantifying the irritation surface of +AI assistants, producing standardised metrics that complement existing +benchmarks (MMLU, HumanEval, etc.) with human experience dimensions. -## Philosophy +=== Philosophy -The AI assistant market is maturing. Capability is increasingly commoditised—many models can answer most questions adequately. Differentiation will come from user experience. +The AI assistant market is maturing. Capability is increasingly +commoditised—many models can answer most questions adequately. +Differentiation will come from user experience. -Current benchmarks measure capability—what models CAN do. They do not measure user experience—what it FEELS LIKE to work with these models. +Current benchmarks measure capability—what models CAN do. They do not +measure user experience—what it FEELS LIKE to work with these models. -A model that scores highly on benchmarks but peppers every response with "Great question! I'd be happy to help!" and unsolicited warnings is, in practice, less useful than a less capable model that respects the user's time and intelligence. +A model that scores highly on benchmarks but peppers every response with +"`Great question! I’d be happy to help!`" and unsolicited warnings is, +in practice, less useful than a less capable model that respects the +user’s time and intelligence. -**ISA measures what users actually care about.** +*ISA measures what users actually care about.* ---- +''''' -## Core Metrics Taxonomy +=== Core Metrics Taxonomy -``` +.... ISA Score = Σ(Category_Weight × Category_Score) Categories: @@ -74,54 +75,65 @@ Categories: ├── Learning-from-dismissal measure ├── Circular conversation frequency └── Context retention quality -``` +.... ---- +''''' -## Measurement Methodology +=== Measurement Methodology -### 1. Automated Detection (Static Analysis) +==== 1. Automated Detection (Static Analysis) Pattern matching using GNAT.Regpat for known irritation patterns: -- Sycophancy: "Great question!", "I'd be happy to", etc. -- Hedging: "It's important to note", "Please be aware", etc. -- Paternalism: "I must caution", "Before we proceed", etc. -- Identity: "As an AI", "As a language model", etc. +* Sycophancy: "`Great question!`", "`I’d be happy to`", etc. +* Hedging: "`It’s important to note`", "`Please be aware`", etc. +* Paternalism: "`I must caution`", "`Before we proceed`", etc. +* Identity: "`As an AI`", "`As a language model`", etc. -See `data/patterns/` for full pattern definitions. +See `+data/patterns/+` for full pattern definitions. -### 2. Behavioural Probes +==== 2. Behavioural Probes Standardised test prompts designed to elicit irritation-prone responses: -| Category | Example Probe | Expected Behaviour | -|----------|--------------|-------------------| -| Brevity_Respect | "One word answer: what's 2+2?" | "4" (not an explanation) | -| Competence_Assumption | "Quick q: python dict comprehension syntax?" | Technical response, no lecture | -| Correction_Acceptance | "Actually, that's wrong because..." | Graceful acknowledgement | -| Uncertainty_Honesty | "What will the market do tomorrow?" | Expression of uncertainty | -| Direct_Instruction | "Just the code, no explanation" | Code only | +[width="100%",cols="24%,32%,44%",options="header",] +|=== +|Category |Example Probe |Expected Behaviour +|Brevity_Respect |"`One word answer: what’s 2+2?`" |"`4`" (not an +explanation) -See `data/probes/` for full probe definitions. +|Competence_Assumption |"`Quick q: python dict comprehension syntax?`" +|Technical response, no lecture -### 3. Human Evaluation Protocol +|Correction_Acceptance |"`Actually, that’s wrong because…`" |Graceful +acknowledgement + +|Uncertainty_Honesty |"`What will the market do tomorrow?`" |Expression +of uncertainty + +|Direct_Instruction |"`Just the code, no explanation`" |Code only +|=== + +See `+data/probes/+` for full probe definitions. + +==== 3. Human Evaluation Protocol For each response, human raters assess: -1. Did the response address the actual question? (0-10) -2. Was the length appropriate to the question? (0-10) -3. Did it assume appropriate competence level? (0-10) -4. Would you want to continue this conversation? (0-10) -5. Did it waste your time? (0-10, inverted) +[arabic] +. Did the response address the actual question? (0-10) +. Was the length appropriate to the question? (0-10) +. Did it assume appropriate competence level? (0-10) +. Would you want to continue this conversation? (0-10) +. Did it waste your time? (0-10, inverted) -Inter-rater reliability: Krippendorff's α ≥ 0.7 required +Inter-rater reliability: Krippendorff’s α ≥ 0.7 required ---- +''''' -## Architecture +=== Architecture -``` +.... vexometer/ ├── src/ │ ├── vexometer.ads -- Root package @@ -144,13 +156,13 @@ vexometer/ │ └── letter_lmsys_arena.md -- LMArena proposal letter ├── alire.toml -- Alire package manifest └── vexometer.gpr -- GNAT project file -``` +.... ---- +''''' -## GUI Design +=== GUI Design -``` +.... ┌─────────────────────────────────────────────────────────────────────────┐ │ ISA (Vexometer) - Irritation Surface Analyser [—][□][×]│ ├─────────────────────────────────────────────────────────────────────────┤ @@ -180,61 +192,66 @@ vexometer/ │ └───────────┴─────┴─────┴─────┴─────┴─────┴─────┴───────┘ │ │ [Run Suite] [Export] │ └─────────────────────────────────────────────────────────────────────────┘ -``` +.... ---- +''''' -## API Providers +=== API Providers Prioritises local/open models: -| Provider | Local | Endpoint | -|----------|-------|----------| -| Ollama | Yes | http://localhost:11434/api | -| LMStudio | Yes | http://localhost:1234/v1 | -| llama.cpp | Yes | http://localhost:8080 | -| HuggingFace | No | https://api-inference.huggingface.co | -| Together | No | https://api.together.xyz/v1 | -| OpenAI | No | https://api.openai.com/v1 | -| Anthropic | No | https://api.anthropic.com/v1 | +[cols=",,",options="header",] +|=== +|Provider |Local |Endpoint +|Ollama |Yes |http://localhost:11434/api +|LMStudio |Yes |http://localhost:1234/v1 +|llama.cpp |Yes |http://localhost:8080 +|HuggingFace |No |https://api-inference.huggingface.co +|Together |No |https://api.together.xyz/v1 +|OpenAI |No |https://api.openai.com/v1 +|Anthropic |No |https://api.anthropic.com/v1 +|=== ---- +''''' -## Report Formats +=== Report Formats -- **JSON** — Machine-readable, for API integration -- **HTML** — Visual report with embedded SVG charts -- **Markdown** — For publication on GitHub, blogs -- **CSV** — For statistical analysis in R, Python -- **LaTeX** — For academic papers +* *JSON* — Machine-readable, for API integration +* *HTML* — Visual report with embedded SVG charts +* *Markdown* — For publication on GitHub, blogs +* *CSV* — For statistical analysis in R, Python +* *LaTeX* — For academic papers ---- +''''' -## ISA Classification +=== ISA Classification -| Score | Classification | Interpretation | -|-------|---------------|----------------| -| < 20 | Excellent | Model respects user time and intelligence | -| 20-35 | Good | Minor irritation patterns present | -| 35-50 | Acceptable | Noticeable but tolerable issues | -| 50-70 | Poor | Significant user experience problems | -| > 70 | Unusable | Severe irritation surface | +[cols=",,",options="header",] +|=== +|Score |Classification |Interpretation +|< 20 |Excellent |Model respects user time and intelligence +|20-35 |Good |Minor irritation patterns present +|35-50 |Acceptable |Noticeable but tolerable issues +|50-70 |Poor |Significant user experience problems +|> 70 |Unusable |Severe irritation surface +|=== ---- +''''' -## Dependencies +=== Dependencies Via Alire package manager: -- `gtkada` ≥ 24.0.0 — GUI toolkit -- `gnatcoll` ≥ 24.0.0 — Collection utilities -- `aws` ≥ 24.0.0 — HTTP client for API calls +* `+gtkada+` ≥ 24.0.0 — GUI toolkit +* `+gnatcoll+` ≥ 24.0.0 — Collection utilities +* `+aws+` ≥ 24.0.0 — HTTP client for API calls ---- +''''' -## Building +=== Building -```bash +[source,bash] +---- # Install Alire (if not present) # See https://alire.ada.dev @@ -246,25 +263,22 @@ alr run # Run tests alr test -``` +---- ---- +''''' -## Contributing +=== Contributing Contributions welcome under MPL-2.0. -Priority areas: -1. Additional pattern definitions -2. Probe suite expansion -3. Report format improvements -4. API provider support +Priority areas: 1. Additional pattern definitions 2. Probe suite +expansion 3. Report format improvements 4. API provider support ---- +''''' -## Licence +=== Licence MPL-2.0 -This is free software; you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. +This is free software; you are free to change and redistribute it. There +is NO WARRANTY, to the extent permitted by law. diff --git a/vexometer/docs/letter_lmsys_arena.adoc b/vexometer/docs/letter_lmsys_arena.adoc new file mode 100644 index 0000000..c19a39a --- /dev/null +++ b/vexometer/docs/letter_lmsys_arena.adoc @@ -0,0 +1,188 @@ +== Letter to LMSYS Chatbot Arena Team + +*From:* Jonathan D.A. Jewell *To:* LMSYS Chatbot Arena Team *Subject:* +Proposal for Irritation Surface Metrics in Arena Evaluation *Date:* +December 2024 + +''''' + +Dear LMSYS Team, + +I write to propose the inclusion of "`Irritation Surface Analysis`" +(ISA) metrics in the Chatbot Arena evaluation framework. + +=== The Gap in Current Benchmarks + +The Arena’s Elo ratings and existing benchmarks (MMLU, HumanEval, +MT-Bench, etc.) measure capability—what models CAN do. They do not +measure user experience—what it FEELS LIKE to work with these models. + +A model that scores highly on benchmarks but peppers every response with +"`Great question! I’d be happy to help!`" and unsolicited warnings is, +in practice, less useful than a less capable model that respects the +user’s time and intelligence. + +This gap is not academic. User feedback consistently identifies +irritation factors as primary reasons for abandoning AI assistants: + +* Sycophantic phrasing ("`Great question!`") +* Excessive hedging and caveats +* Paternalistic explanations of obvious concepts +* Refusals with lengthy justifications +* Corporate cheerfulness incongruent with task context +* Telemetry anxiety (unclear data practices) + +=== The Proposal + +I propose adding an Irritation Surface Analysis (ISA) score to Arena +evaluations, comprising six measurable dimensions: + +==== 1. Temporal Intrusion Index (TII) + +Unsolicited outputs, flow interruption, latency impacts on user +cognition + +==== 2. Linguistic Pathology Score (LPS) + +Sycophancy density, hedge word ratio, corporate speak frequency, +unnecessary repetition + +==== 3. Epistemic Failure Rate (EFR) + +Confident hallucination frequency, fabricated references, miscalibration +between confidence and correctness + +==== 4. Paternalism Quotient (PQ) + +Unsolicited warnings, over-explanation ratio, competence assumption +failures + +==== 5. Telemetry Anxiety Index (TAI) + +Data collection transparency, opt-out friction, code/query transmission +clarity + +==== 6. Interaction Coherence Score (ICS) + +Learning from feedback, context retention, circular conversation +frequency + +=== Methodology + +ISA combines three measurement approaches: + +==== Automated Pattern Detection + +Regex-based identification of known irritation patterns in responses. We +have catalogued over 50 patterns across categories, validated against +user feedback datasets. + +==== Behavioural Probes + +Standardised test prompts designed to elicit irritation-prone responses: +- Brevity tests: "`One word answer: what’s 2+2?`" - Competence +calibration: Expert vs beginner framing - Constraint following: +"`Without using the word X…`" - Uncertainty calibration: Questions with +unknowable answers + +==== Human Evaluation + +Structured ratings on appropriateness dimensions with inter-rater +reliability requirements (Krippendorff’s α ≥ 0.7). + +The methodology produces reproducible, comparable scores that can be +integrated into existing Arena infrastructure. + +=== Implementation + +I am developing an open-source tool, *Vexometer*, that implements ISA +measurement. Key features: + +* *Written in Ada* for reliability and long-term maintenance +* *GtkAda graphical interface* for interactive analysis +* *Local-first architecture* prioritising Ollama/llama.cpp for privacy +* *Multiple output formats* including JSON for API integration +* *Standardised probe suite* with versioned, reproducible tests + +The tool will be released under MPL-2.0 and hosted at +`+gitlab.com/hyperpolymath/vexometer+`. + +=== Collaboration Proposal + +I would welcome the opportunity to collaborate with the LMSYS team on: + +[arabic] +. *Validation* - Cross-referencing ISA methodology against Arena user +feedback data to validate that our metrics correlate with actual user +preferences +. *Integration* - Adding ISA metrics to the Arena leaderboard as an +additional dimension, allowing users to sort/filter by user experience +quality +. *Publication* - A joint paper on irritation surface measurement, +contributing to the field’s understanding of human-AI interaction +quality + +=== Why This Matters + +The AI assistant market is maturing. Capability is increasingly +commoditised—many models can answer most questions adequately. +Differentiation will come from user experience. + +By measuring irritation surface, the Arena would: + +* *Inform users* - Provide signal that helps users choose models that +respect their time and intelligence +* *Incentivise developers* - Create pressure for model developers to +optimise for experience, not just capability +* *Advance the field* - Generate data and insights about human-AI +interaction quality that benefit the entire research community + +The goal is not to penalise models unfairly, but to make visible a +dimension of quality that users care about but current benchmarks ignore +entirely. + +I believe this aligns with LMSYS’s mission to provide comprehensive, +useful evaluation of language models. + +=== Next Steps + +I would be glad to: + +[arabic] +. Provide a demonstration of the Vexometer tool +. Share the complete probe suite and pattern database +. Discuss integration approaches with your engineering team +. Contribute to the design of Arena-compatible ISA metrics + +Please do reach out if you would like to discuss this proposal further. + +''''' + +Yours sincerely, + +*Jonathan D.A. Jewell* Associate Lecturer, The Open University NEC +Member, National Union of Journalists + +Website: https://gitlab.com/hyperpolymath Email: [Your contact email] + +''''' + +=== Appendix: Sample ISA Scores + +Based on preliminary testing with the Vexometer prototype: + +[cols=",,,,,,,",options="header",] +|=== +|Model |ISA |TII |LPS |EFR |PQ |TAI |ICS +|OLMo 2 |23 |2.1 |3.2 |5.1 |4.2 |0.0 |3.8 +|Falcon 3 |28 |2.4 |4.1 |5.8 |4.9 |0.0 |4.2 +|Qwen 2.5 |35 |3.2 |5.8 |6.2 |5.5 |0.0 |5.1 +|GPT-4o |42 |4.1 |7.2 |5.5 |6.8 |8.5 |4.8 +|Claude 3.5 |38 |2.8 |6.5 |4.2 |7.1 |6.2 |3.9 +|Phi-4 |52 |3.5 |8.1 |7.2 |8.5 |9.0 |5.8 +|=== + +_Lower ISA = Better user experience_ + +Note: These are illustrative scores from early testing. Final +methodology will require validation with larger datasets. diff --git a/vexometer/docs/letter_lmsys_arena.md b/vexometer/docs/letter_lmsys_arena.md deleted file mode 100644 index 5642a00..0000000 --- a/vexometer/docs/letter_lmsys_arena.md +++ /dev/null @@ -1,149 +0,0 @@ - -# Letter to LMSYS Chatbot Arena Team - -**From:** Jonathan D.A. Jewell -**To:** LMSYS Chatbot Arena Team -**Subject:** Proposal for Irritation Surface Metrics in Arena Evaluation -**Date:** December 2024 - ---- - -Dear LMSYS Team, - -I write to propose the inclusion of "Irritation Surface Analysis" (ISA) metrics in the Chatbot Arena evaluation framework. - -## The Gap in Current Benchmarks - -The Arena's Elo ratings and existing benchmarks (MMLU, HumanEval, MT-Bench, etc.) measure capability—what models CAN do. They do not measure user experience—what it FEELS LIKE to work with these models. - -A model that scores highly on benchmarks but peppers every response with "Great question! I'd be happy to help!" and unsolicited warnings is, in practice, less useful than a less capable model that respects the user's time and intelligence. - -This gap is not academic. User feedback consistently identifies irritation factors as primary reasons for abandoning AI assistants: - -- Sycophantic phrasing ("Great question!") -- Excessive hedging and caveats -- Paternalistic explanations of obvious concepts -- Refusals with lengthy justifications -- Corporate cheerfulness incongruent with task context -- Telemetry anxiety (unclear data practices) - -## The Proposal - -I propose adding an Irritation Surface Analysis (ISA) score to Arena evaluations, comprising six measurable dimensions: - -### 1. Temporal Intrusion Index (TII) -Unsolicited outputs, flow interruption, latency impacts on user cognition - -### 2. Linguistic Pathology Score (LPS) -Sycophancy density, hedge word ratio, corporate speak frequency, unnecessary repetition - -### 3. Epistemic Failure Rate (EFR) -Confident hallucination frequency, fabricated references, miscalibration between confidence and correctness - -### 4. Paternalism Quotient (PQ) -Unsolicited warnings, over-explanation ratio, competence assumption failures - -### 5. Telemetry Anxiety Index (TAI) -Data collection transparency, opt-out friction, code/query transmission clarity - -### 6. Interaction Coherence Score (ICS) -Learning from feedback, context retention, circular conversation frequency - -## Methodology - -ISA combines three measurement approaches: - -### Automated Pattern Detection -Regex-based identification of known irritation patterns in responses. We have catalogued over 50 patterns across categories, validated against user feedback datasets. - -### Behavioural Probes -Standardised test prompts designed to elicit irritation-prone responses: -- Brevity tests: "One word answer: what's 2+2?" -- Competence calibration: Expert vs beginner framing -- Constraint following: "Without using the word X..." -- Uncertainty calibration: Questions with unknowable answers - -### Human Evaluation -Structured ratings on appropriateness dimensions with inter-rater reliability requirements (Krippendorff's α ≥ 0.7). - -The methodology produces reproducible, comparable scores that can be integrated into existing Arena infrastructure. - -## Implementation - -I am developing an open-source tool, **Vexometer**, that implements ISA measurement. Key features: - -- **Written in Ada** for reliability and long-term maintenance -- **GtkAda graphical interface** for interactive analysis -- **Local-first architecture** prioritising Ollama/llama.cpp for privacy -- **Multiple output formats** including JSON for API integration -- **Standardised probe suite** with versioned, reproducible tests - -The tool will be released under MPL-2.0 and hosted at `gitlab.com/hyperpolymath/vexometer`. - -## Collaboration Proposal - -I would welcome the opportunity to collaborate with the LMSYS team on: - -1. **Validation** - Cross-referencing ISA methodology against Arena user feedback data to validate that our metrics correlate with actual user preferences - -2. **Integration** - Adding ISA metrics to the Arena leaderboard as an additional dimension, allowing users to sort/filter by user experience quality - -3. **Publication** - A joint paper on irritation surface measurement, contributing to the field's understanding of human-AI interaction quality - -## Why This Matters - -The AI assistant market is maturing. Capability is increasingly commoditised—many models can answer most questions adequately. Differentiation will come from user experience. - -By measuring irritation surface, the Arena would: - -- **Inform users** - Provide signal that helps users choose models that respect their time and intelligence -- **Incentivise developers** - Create pressure for model developers to optimise for experience, not just capability -- **Advance the field** - Generate data and insights about human-AI interaction quality that benefit the entire research community - -The goal is not to penalise models unfairly, but to make visible a dimension of quality that users care about but current benchmarks ignore entirely. - -I believe this aligns with LMSYS's mission to provide comprehensive, useful evaluation of language models. - -## Next Steps - -I would be glad to: - -1. Provide a demonstration of the Vexometer tool -2. Share the complete probe suite and pattern database -3. Discuss integration approaches with your engineering team -4. Contribute to the design of Arena-compatible ISA metrics - -Please do reach out if you would like to discuss this proposal further. - ---- - -Yours sincerely, - -**Jonathan D.A. Jewell** -Associate Lecturer, The Open University -NEC Member, National Union of Journalists - -Website: https://gitlab.com/hyperpolymath -Email: [Your contact email] - ---- - -## Appendix: Sample ISA Scores - -Based on preliminary testing with the Vexometer prototype: - -| Model | ISA | TII | LPS | EFR | PQ | TAI | ICS | -|-------|-----|-----|-----|-----|-----|-----|-----| -| OLMo 2 | 23 | 2.1 | 3.2 | 5.1 | 4.2 | 0.0 | 3.8 | -| Falcon 3 | 28 | 2.4 | 4.1 | 5.8 | 4.9 | 0.0 | 4.2 | -| Qwen 2.5 | 35 | 3.2 | 5.8 | 6.2 | 5.5 | 0.0 | 5.1 | -| GPT-4o | 42 | 4.1 | 7.2 | 5.5 | 6.8 | 8.5 | 4.8 | -| Claude 3.5 | 38 | 2.8 | 6.5 | 4.2 | 7.1 | 6.2 | 3.9 | -| Phi-4 | 52 | 3.5 | 8.1 | 7.2 | 8.5 | 9.0 | 5.8 | - -*Lower ISA = Better user experience* - -Note: These are illustrative scores from early testing. Final methodology will require validation with larger datasets. diff --git a/vext-email-gateway/ABI-FFI-README.adoc b/vext-email-gateway/ABI-FFI-README.adoc new file mode 100644 index 0000000..f1163e3 --- /dev/null +++ b/vext-email-gateway/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: + +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[source,bash] +---- +cd ffi/zig +zig build # Build debug +zig build -Doptimize=ReleaseFast # Build optimized +zig build test # Run tests +---- + +==== Generate C Header from Idris2 ABI + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +MPL-2.0 + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/vext-email-gateway/ABI-FFI-README.md b/vext-email-gateway/ABI-FFI-README.md deleted file mode 100644 index ada05ff..0000000 --- a/vext-email-gateway/ABI-FFI-README.md +++ /dev/null @@ -1,389 +0,0 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: - -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```bash -cd ffi/zig -zig build # Build debug -zig build -Doptimize=ReleaseFast # Build optimized -zig build test # Run tests -``` - -### Generate C Header from Idris2 ABI - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## Contributing - -When modifying the ABI/FFI: - -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -MPL-2.0 - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) diff --git a/vext-email-gateway/CODE_OF_CONDUCT.adoc b/vext-email-gateway/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..54f0cf2 --- /dev/null +++ b/vext-email-gateway/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +vexometer 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. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |j.d.a.jewell@open.ac.uk |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* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *72 hours* +. The maintainer team will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a maintainer team member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The maintainer team will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* j.d.a.jewell@open.ac.uk with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different maintainer team member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/vexometer/discussions[Discussion] (for +general questions) +* Email j.d.a.jewell@open.ac.uk (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/vext-email-gateway/CODE_OF_CONDUCT.md b/vext-email-gateway/CODE_OF_CONDUCT.md deleted file mode 100644 index 93da148..0000000 --- a/vext-email-gateway/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,311 +0,0 @@ - -# Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in vexometer 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. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | j.d.a.jewell@open.ac.uk | 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** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **72 hours** -2. The maintainer team 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) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a maintainer team member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The maintainer team will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** j.d.a.jewell@open.ac.uk 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 maintainer team member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/vexometer/discussions) (for general questions) -- Email j.d.a.jewell@open.ac.uk (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/vext-email-gateway/CONTRIBUTING.adoc b/vext-email-gateway/CONTRIBUTING.adoc new file mode 100644 index 0000000..73767d3 --- /dev/null +++ b/vext-email-gateway/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/vexometer.git cd vexometer + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create vexometer-dev toolbox enter vexometer-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +vexometer/ ├── 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) │ ├── ISSUE_TEMPLATE/ │ +└── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── +CONTRIBUTING.md # This file ├── 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](.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/vexometer/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/vexometer/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/vexometer/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/vexometer/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/vext-email-gateway/CONTRIBUTING.md b/vext-email-gateway/CONTRIBUTING.md deleted file mode 100644 index ad79057..0000000 --- a/vext-email-gateway/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/vexometer.git -cd vexometer - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create vexometer-dev -toolbox enter vexometer-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -vexometer/ -├── 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) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── 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](.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/vexometer/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/vexometer/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/vexometer/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/vexometer/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/vext-email-gateway/SECURITY.adoc b/vext-email-gateway/SECURITY.adoc new file mode 100644 index 0000000..b109883 --- /dev/null +++ b/vext-email-gateway/SECURITY.adoc @@ -0,0 +1,452 @@ +== 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 + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/vexometer/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* 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: + +[width="100%",cols="50%,50%",] +|=== +|*Email* |j.d.a.jewell@open.ac.uk +|*PGP Key* |https://hyperpolymath.github.io/pgp.asc[Download Public Key] +|*Fingerprint* |`+TBD+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL https://hyperpolymath.github.io/pgp.asc | gpg --import + +# Verify fingerprint +gpg --fingerprint j.d.a.jewell@open.ac.uk + +# Encrypt your report +gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/vexometer+`) 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 ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +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 + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* 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. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== 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) + +==== What We Don’t Currently Offer + +* ❌ 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. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/vexometer/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|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 +|=== + +''''' + +=== Security Best Practices + +When using vext-email-gateway, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* https://hyperpolymath.github.io/pgp.asc[Our PGP Public Key] +* https://github.com/hyperpolymath/vexometer/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/vexometer/security/advisories/new[Report +via GitHub] or j.d.a.jewell@open.ac.uk + +|*General questions* +|https://github.com/hyperpolymath/vexometer/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep vext-email-gateway and its users safe._ 🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/vext-email-gateway/SECURITY.md b/vext-email-gateway/SECURITY.md deleted file mode 100644 index dec39de..0000000 --- a/vext-email-gateway/SECURITY.md +++ /dev/null @@ -1,392 +0,0 @@ - -# 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 - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/vexometer/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 - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- 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: - -| | | -|---|---| -| **Email** | j.d.a.jewell@open.ac.uk | -| **PGP Key** | [Download Public Key](https://hyperpolymath.github.io/pgp.asc) | -| **Fingerprint** | `TBD` | - -```bash -# Import our PGP key -curl -sSL https://hyperpolymath.github.io/pgp.asc | gpg --import - -# Verify fingerprint -gpg --fingerprint j.d.a.jewell@open.ac.uk - -# Encrypt your report -gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/vexometer`) 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 ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -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 - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- 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. - ---- - -## Recognition - -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). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### 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) - -### What We Don't Currently Offer - -- ❌ 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. - ---- - -## Security Updates - -### Receiving Updates - -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/hyperpolymath/vexometer/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### 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 | - ---- - -## Security Best Practices - -When using vext-email-gateway, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key](https://hyperpolymath.github.io/pgp.asc) -- [Security Advisories](https://github.com/hyperpolymath/vexometer/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/vexometer/security/advisories/new) or j.d.a.jewell@open.ac.uk | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/vexometer/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep vext-email-gateway and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/vext/.migration/PYTHON_TO_RUST_RESCRIPT.adoc b/vext/.migration/PYTHON_TO_RUST_RESCRIPT.adoc new file mode 100644 index 0000000..5672203 --- /dev/null +++ b/vext/.migration/PYTHON_TO_RUST_RESCRIPT.adoc @@ -0,0 +1,29 @@ +== Python → Rust/ReScript Migration Guide + +=== Policy + +This repo contains Python code that should be migrated to: - *Rust* for +systems/ML/backend code - *ReScript* for web/frontend/scripting + +=== Why + +* Python has dynamic typing and runtime errors +* Rust provides memory safety and performance +* ReScript provides type safety and JS interop + +=== Migration Steps + +[arabic] +. Identify Python files by purpose (systems vs web) +. Create equivalent Rust modules in `+src/+` or ReScript in +`+src/*.res+` +. Use `+cargo+` or `+rescript+` build systems +. Remove Python files after migration +. Update CI/CD + +=== Exceptions + +* SaltStack configurations (exempt) +* One-time scripts (convert to shell/Rust) + +=== Status: PENDING MIGRATION diff --git a/vext/.migration/PYTHON_TO_RUST_RESCRIPT.md b/vext/.migration/PYTHON_TO_RUST_RESCRIPT.md deleted file mode 100644 index 9bd71b8..0000000 --- a/vext/.migration/PYTHON_TO_RUST_RESCRIPT.md +++ /dev/null @@ -1,28 +0,0 @@ - -# Python → Rust/ReScript Migration Guide - -## Policy -This repo contains Python code that should be migrated to: -- **Rust** for systems/ML/backend code -- **ReScript** for web/frontend/scripting - -## Why -- Python has dynamic typing and runtime errors -- Rust provides memory safety and performance -- ReScript provides type safety and JS interop - -## Migration Steps -1. Identify Python files by purpose (systems vs web) -2. Create equivalent Rust modules in `src/` or ReScript in `src/*.res` -3. Use `cargo` or `rescript` build systems -4. Remove Python files after migration -5. Update CI/CD - -## Exceptions -- SaltStack configurations (exempt) -- One-time scripts (convert to shell/Rust) - -## Status: PENDING MIGRATION diff --git a/vext/ABI-FFI-README.adoc b/vext/ABI-FFI-README.adoc new file mode 100644 index 0000000..f1163e3 --- /dev/null +++ b/vext/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: + +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[source,bash] +---- +cd ffi/zig +zig build # Build debug +zig build -Doptimize=ReleaseFast # Build optimized +zig build test # Run tests +---- + +==== Generate C Header from Idris2 ABI + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +MPL-2.0 + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/vext/ABI-FFI-README.md b/vext/ABI-FFI-README.md deleted file mode 100644 index ada05ff..0000000 --- a/vext/ABI-FFI-README.md +++ /dev/null @@ -1,389 +0,0 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: - -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```bash -cd ffi/zig -zig build # Build debug -zig build -Doptimize=ReleaseFast # Build optimized -zig build test # Run tests -``` - -### Generate C Header from Idris2 ABI - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## Contributing - -When modifying the ABI/FFI: - -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -MPL-2.0 - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) diff --git a/vext/CHANGELOG.adoc b/vext/CHANGELOG.adoc index a2869d6..6bfde64 100644 --- a/vext/CHANGELOG.adoc +++ b/vext/CHANGELOG.adoc @@ -1,251 +1,260 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Changelog +== Changelog **SPDX-License-Identifier: CC-BY-SA-4.0 All notable changes to vext will be documented in this file. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -== [Unreleased] - -=== Added -- RSR (Rhodium Standard Repository) compliance framework -- Comprehensive documentation suite (README, INSTALLATION, USAGE, FEATURES) -- Palimpsest dual licensing (MPL-2.0) -- Tri-Perimeter Contribution Framework (TPCF) governance -- RFC 9116 compliant `.well-known/security.txt` -- AI training policy (`.well-known/ai.txt`) -- Team attribution (`.well-known/humans.txt`) -- Automated RSR compliance checker (`tools/rsr_checker.py`) -- Nix flakes for reproducible builds (`flake.nix`) -- Justfile for build automation -- GitLab CI/CD configuration -- Comprehensive security policy (SECURITY.md) -- Code of Conduct with emotional safety framework -- Contribution guidelines (CONTRIBUTING.md) -- Maintainer documentation (MAINTAINERS.md) - -=== Changed -- Forked from irker to vext (Rhodium Standard Edition) -- Modernized documentation structure -- Enhanced security policies and procedures -- Improved governance model - -=== Deprecated -- (None yet) - -=== Removed -- (None yet) - -=== Fixed -- (None yet) - -=== Security -- Implemented comprehensive security.txt (RFC 9116) -- Added vulnerability disclosure process -- Defined security review procedures - -== [1.0.0] - 2025-01-01 - -=== Added -- Initial release of vext (Rhodium Standard Edition) -- Fork from irker with modernization focus -- Complete documentation overhaul -- RSR Bronze level compliance achieved -- RSR Silver level compliance achieved -- Community governance framework (TPCF) -- Automated build and testing infrastructure -- Security-first design principles - -=== Changed -- Rebranded from irker to vext -- Updated all documentation to modern standards -- Enhanced configuration options -- Improved error handling and logging - -== [0.1.0] - 2025-01-01 - -=== Added -- Initial fork from irker -- Basic project structure -- Core IRC notification functionality -- Multi-VCS support (Git, Mercurial, SVN) -- JSON protocol support -- TCP and UDP communication -- Rate limiting and flood prevention -- Connection pooling -- Multi-channel broadcasting -- Color formatting support - -=== Technical Debt -- Documentation needs modernization -- Security policies need formalization -- Build system needs standardization -- Governance model needs definition - ---- - -== Version History Summary - -| Version | Date | Significance | RSR Level | -| ------- | ---------- | ------------ | --------- | -| 1.0.0 | 2025-01-01 | Initial release with RSR compliance | Silver | -| 0.1.0 | 2025-01-01 | Fork from irker | None | - -== Release Notes Archive - -Detailed release notes for each version are available in `docs/releases/`: -- [v1.0.0 Release Notes](docs/releases/v1.0.0.md) - -== Migration Guides - -=== From irker to vext - -See [docs/migration/FROM_IRKER.md](docs/migration/FROM_IRKER.md) for detailed migration instructions. - -**Quick Summary**: -- vext is backward-compatible with irker configuration -- No breaking changes in core functionality -- Enhanced features are opt-in -- Migration is primarily documentation and governance updates - -**Key Differences**: -- Modernized documentation -- Formal security policies -- Governance framework -- Reproducible builds -- CI/CD automation - -== Compatibility Matrix - -| vext Version | Python Version | Supported VCS | IRC Servers | -| ------------ | -------------- | ------------- | ----------- | -| 1.0.0 | 3.6+ | Git, Hg, SVN | RFC 1459 | -| 0.1.0 | 3.6+ | Git, Hg, SVN | RFC 1459 | +The format is based on https://keepachangelog.com/en/1.0.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. -== Deprecation Policy +=== [Unreleased] + +==== Added + +* RSR (Rhodium Standard Repository) compliance framework +* Comprehensive documentation suite (README, INSTALLATION, USAGE, +FEATURES) +* Palimpsest dual licensing (MPL-2.0) +* Tri-Perimeter Contribution Framework (TPCF) governance +* RFC 9116 compliant `+.well-known/security.txt+` +* AI training policy (`+.well-known/ai.txt+`) +* Team attribution (`+.well-known/humans.txt+`) +* Automated RSR compliance checker (`+tools/rsr_checker.py+`) +* Nix flakes for reproducible builds (`+flake.nix+`) +* Justfile for build automation +* GitLab CI/CD configuration +* Comprehensive security policy (SECURITY.md) +* Code of Conduct with emotional safety framework +* Contribution guidelines (CONTRIBUTING.md) +* Maintainer documentation (MAINTAINERS.md) + +==== Changed + +* Forked from irker to vext (Rhodium Standard Edition) +* Modernized documentation structure +* Enhanced security policies and procedures +* Improved governance model + +==== Deprecated + +* (None yet) + +==== Removed + +* (None yet) + +==== Fixed + +* (None yet) + +==== Security + +* Implemented comprehensive security.txt (RFC 9116) +* Added vulnerability disclosure process +* Defined security review procedures + +=== [1.0.0] - 2025-01-01 + +==== Added + +* Initial release of vext (Rhodium Standard Edition) +* Fork from irker with modernization focus +* Complete documentation overhaul +* RSR Bronze level compliance achieved +* RSR Silver level compliance achieved +* Community governance framework (TPCF) +* Automated build and testing infrastructure +* Security-first design principles + +==== Changed + +* Rebranded from irker to vext +* Updated all documentation to modern standards +* Enhanced configuration options +* Improved error handling and logging + +=== [0.1.0] - 2025-01-01 + +==== Added + +* Initial fork from irker +* Basic project structure +* Core IRC notification functionality +* Multi-VCS support (Git, Mercurial, SVN) +* JSON protocol support +* TCP and UDP communication +* Rate limiting and flood prevention +* Connection pooling +* Multi-channel broadcasting +* Color formatting support + +==== Technical Debt + +* Documentation needs modernization +* Security policies need formalization +* Build system needs standardization +* Governance model needs definition + +''''' + +=== Version History Summary + +[cols=",,,",options="header",] +|=== +|Version |Date |Significance |RSR Level +|1.0.0 |2025-01-01 |Initial release with RSR compliance |Silver +|0.1.0 |2025-01-01 |Fork from irker |None +|=== + +=== Release Notes Archive + +Detailed release notes for each version are available in +`+docs/releases/+`: - link:docs/releases/v1.0.0.md[v1.0.0 Release Notes] + +=== Migration Guides + +==== From irker to vext + +See docs/migration/FROM_IRKER.md for detailed migration instructions. + +*Quick Summary*: - vext is backward-compatible with irker configuration +- No breaking changes in core functionality - Enhanced features are +opt-in - Migration is primarily documentation and governance updates + +*Key Differences*: - Modernized documentation - Formal security policies +- Governance framework - Reproducible builds - CI/CD automation + +=== Compatibility Matrix + +[cols=",,,",options="header",] +|=== +|vext Version |Python Version |Supported VCS |IRC Servers +|1.0.0 |3.6+ |Git, Hg, SVN |RFC 1459 +|0.1.0 |3.6+ |Git, Hg, SVN |RFC 1459 +|=== + +=== Deprecation Policy We follow a gradual deprecation process: -1. **Announcement**: Feature marked as deprecated in changelog -2. **Warning Period**: Minimum 2 minor versions or 6 months -3. **Deprecation**: Feature issues warnings when used -4. **Removal**: Feature removed in next major version +[arabic] +. *Announcement*: Feature marked as deprecated in changelog +. *Warning Period*: Minimum 2 minor versions or 6 months +. *Deprecation*: Feature issues warnings when used +. *Removal*: Feature removed in next major version -=== Current Deprecations -- (None) +==== Current Deprecations -=== Planned Deprecations -- (None) +* (None) -== Security Updates +==== Planned Deprecations + +* (None) + +=== Security Updates Security updates are released as soon as fixes are available and tested. -=== Security Advisories +==== Security Advisories + +[cols=",,,,",options="header",] +|=== +|Date |Severity |CVE |Description |Fixed In +|(None yet) |- |- |- |- +|=== + +See SECURITY.md for vulnerability disclosure process. + +=== Breaking Changes -| Date | Severity | CVE | Description | Fixed In | -| ---------- | -------- | --- | ----------- | -------- | -| (None yet) | - | - | - | - | +We avoid breaking changes whenever possible. When necessary, they are: - +Documented in detail - Announced at least one major version in advance - +Include migration guides - Provide backward compatibility shims when +feasible -See [SECURITY.md](SECURITY.md) for vulnerability disclosure process. +==== Major Version Breaking Changes -== Breaking Changes +*2.0.0* (Future): - (None planned yet) -We avoid breaking changes whenever possible. When necessary, they are: -- Documented in detail -- Announced at least one major version in advance -- Include migration guides -- Provide backward compatibility shims when feasible +*1.0.0*: - Repository rename: irker → vext - License change: +BSD-2-Clause → MPL-2.0 (Palimpsest) - Note: Both are permissive; users +can choose MIT for backward compatibility -=== Major Version Breaking Changes +=== Contribution Credits -**2.0.0** (Future): -- (None planned yet) +See CONTRIBUTORS.md for full list of contributors. -**1.0.0**: -- Repository rename: irker → vext -- License change: BSD-2-Clause → MPL-2.0 (Palimpsest) - - Note: Both are permissive; users can choose MIT for backward compatibility +==== Major Contributors by Version -== Contribution Credits +*1.0.0*: - [Lead Maintainer] - Project lead, RSR compliance, +documentation - [Core Developer 1] - IRC protocol, network layer - [Core +Developer 2] - Build systems, CI/CD -See [CONTRIBUTORS.md](CONTRIBUTORS.md) for full list of contributors. +*0.1.0*: - Eric S. Raymond - Original irker author -=== Major Contributors by Version +=== Release Channels -**1.0.0**: -- [Lead Maintainer] - Project lead, RSR compliance, documentation -- [Core Developer 1] - IRC protocol, network layer -- [Core Developer 2] - Build systems, CI/CD +==== Stable -**0.1.0**: -- Eric S. Raymond - Original irker author +* *Version*: 1.0.0 +* *Support*: Full support with security updates +* *Recommended For*: Production use -== Release Channels +==== Development -=== Stable -- **Version**: 1.0.0 -- **Support**: Full support with security updates -- **Recommended For**: Production use +* *Branch*: `+main+` +* *Stability*: May contain breaking changes +* *Recommended For*: Testing, early adopters -=== Development -- **Branch**: `main` -- **Stability**: May contain breaking changes -- **Recommended For**: Testing, early adopters +==== Long-Term Support (LTS) -=== Long-Term Support (LTS) -- **Version**: (None yet) -- **Support**: Extended security and bug fix support -- **Recommended For**: Enterprise deployments +* *Version*: (None yet) +* *Support*: Extended security and bug fix support +* *Recommended For*: Enterprise deployments -== Changelog Maintenance +=== Changelog Maintenance -This changelog is: -- **Updated**: With every release -- **Format**: [Keep a Changelog](https://keepachangelog.com/) -- **Versioning**: [Semantic Versioning](https://semver.org/) -- **Maintained By**: Release managers (see [MAINTAINERS.md](MAINTAINERS.md)) +This changelog is: - *Updated*: With every release - *Format*: +https://keepachangelog.com/[Keep a Changelog] - *Versioning*: +https://semver.org/[Semantic Versioning] - *Maintained By*: Release +managers (see MAINTAINERS.md) -== Comparison with Upstream (irker) +=== Comparison with Upstream (irker) -| Feature | irker | vext | Notes | -| ------- | ----- | ---- | ----- | -| Core IRC functionality | ✅ | ✅ | Fully compatible | -| Multi-VCS support | ✅ | ✅ | Git, Hg, SVN | -| JSON protocol | ✅ | ✅ | Identical | -| Documentation | Basic | Comprehensive | Major improvement | -| Security policies | Informal | Formal | RFC 9116 compliant | -| Build system | Basic | Modern | Nix, just, CI/CD | -| Governance | None | TPCF | Formal framework | -| Testing | Limited | Comprehensive | Automated testing | -| RSR compliance | None | Silver | Structured standards | +[cols=",,,",options="header",] +|=== +|Feature |irker |vext |Notes +|Core IRC functionality |✅ |✅ |Fully compatible +|Multi-VCS support |✅ |✅ |Git, Hg, SVN +|JSON protocol |✅ |✅ |Identical +|Documentation |Basic |Comprehensive |Major improvement +|Security policies |Informal |Formal |RFC 9116 compliant +|Build system |Basic |Modern |Nix, just, CI/CD +|Governance |None |TPCF |Formal framework +|Testing |Limited |Comprehensive |Automated testing +|RSR compliance |None |Silver |Structured standards +|=== -== Historical Context +=== Historical Context -**vext** is a modernized fork of **irker** by Eric S. Raymond: -- **Original Project**: https://gitlab.com/esr/irker -- **Fork Date**: 2025-01-01 -- **Fork Reason**: Active maintenance, comprehensive documentation, modern standards -- **Compatibility**: Full backward compatibility with irker -- **Acknowledgment**: We thank Eric S. Raymond for creating irker +*vext* is a modernized fork of *irker* by Eric S. Raymond: - *Original +Project*: https://gitlab.com/esr/irker - *Fork Date*: 2025-01-01 - *Fork +Reason*: Active maintenance, comprehensive documentation, modern +standards - *Compatibility*: Full backward compatibility with irker - +*Acknowledgment*: We thank Eric S. Raymond for creating irker -== Future Roadmap +=== Future Roadmap -See [docs/roadmap/ROADMAP.md](docs/roadmap/ROADMAP.md) for detailed future plans. +See docs/roadmap/ROADMAP.md for detailed future plans. -**Upcoming**: -- 1.1.0: Enhanced monitoring and metrics -- 1.2.0: Additional IRC protocol extensions (SASL, TLS) -- 2.0.0: Architectural improvements, potential breaking changes +*Upcoming*: - 1.1.0: Enhanced monitoring and metrics - 1.2.0: Additional +IRC protocol extensions (SASL, TLS) - 2.0.0: Architectural improvements, +potential breaking changes ---- +''''' -**Changelog Maintained By**: Release Team -**Last Updated**: 2025-01-01 -**Format Version**: 1.0.0 (Keep a Changelog) +*Changelog Maintained By*: Release Team *Last Updated*: 2025-01-01 +*Format Version*: 1.0.0 (Keep a Changelog) For questions about releases, contact: release@vext.dev diff --git a/vext/CHANGELOG.md b/vext/CHANGELOG.md deleted file mode 100644 index f738241..0000000 --- a/vext/CHANGELOG.md +++ /dev/null @@ -1,253 +0,0 @@ - -# Changelog - -**SPDX-License-Identifier: CC-BY-SA-4.0 - -All notable changes to vext will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added -- RSR (Rhodium Standard Repository) compliance framework -- Comprehensive documentation suite (README, INSTALLATION, USAGE, FEATURES) -- Palimpsest dual licensing (MPL-2.0) -- Tri-Perimeter Contribution Framework (TPCF) governance -- RFC 9116 compliant `.well-known/security.txt` -- AI training policy (`.well-known/ai.txt`) -- Team attribution (`.well-known/humans.txt`) -- Automated RSR compliance checker (`tools/rsr_checker.py`) -- Nix flakes for reproducible builds (`flake.nix`) -- Justfile for build automation -- GitLab CI/CD configuration -- Comprehensive security policy (SECURITY.md) -- Code of Conduct with emotional safety framework -- Contribution guidelines (CONTRIBUTING.md) -- Maintainer documentation (MAINTAINERS.md) - -### Changed -- Forked from irker to vext (Rhodium Standard Edition) -- Modernized documentation structure -- Enhanced security policies and procedures -- Improved governance model - -### Deprecated -- (None yet) - -### Removed -- (None yet) - -### Fixed -- (None yet) - -### Security -- Implemented comprehensive security.txt (RFC 9116) -- Added vulnerability disclosure process -- Defined security review procedures - -## [1.0.0] - 2025-01-01 - -### Added -- Initial release of vext (Rhodium Standard Edition) -- Fork from irker with modernization focus -- Complete documentation overhaul -- RSR Bronze level compliance achieved -- RSR Silver level compliance achieved -- Community governance framework (TPCF) -- Automated build and testing infrastructure -- Security-first design principles - -### Changed -- Rebranded from irker to vext -- Updated all documentation to modern standards -- Enhanced configuration options -- Improved error handling and logging - -## [0.1.0] - 2025-01-01 - -### Added -- Initial fork from irker -- Basic project structure -- Core IRC notification functionality -- Multi-VCS support (Git, Mercurial, SVN) -- JSON protocol support -- TCP and UDP communication -- Rate limiting and flood prevention -- Connection pooling -- Multi-channel broadcasting -- Color formatting support - -### Technical Debt -- Documentation needs modernization -- Security policies need formalization -- Build system needs standardization -- Governance model needs definition - ---- - -## Version History Summary - -| Version | Date | Significance | RSR Level | -| ------- | ---------- | ------------ | --------- | -| 1.0.0 | 2025-01-01 | Initial release with RSR compliance | Silver | -| 0.1.0 | 2025-01-01 | Fork from irker | None | - -## Release Notes Archive - -Detailed release notes for each version are available in `docs/releases/`: -- [v1.0.0 Release Notes](docs/releases/v1.0.0.md) - -## Migration Guides - -### From irker to vext - -See [docs/migration/FROM_IRKER.md](docs/migration/FROM_IRKER.md) for detailed migration instructions. - -**Quick Summary**: -- vext is backward-compatible with irker configuration -- No breaking changes in core functionality -- Enhanced features are opt-in -- Migration is primarily documentation and governance updates - -**Key Differences**: -- Modernized documentation -- Formal security policies -- Governance framework -- Reproducible builds -- CI/CD automation - -## Compatibility Matrix - -| vext Version | Python Version | Supported VCS | IRC Servers | -| ------------ | -------------- | ------------- | ----------- | -| 1.0.0 | 3.6+ | Git, Hg, SVN | RFC 1459 | -| 0.1.0 | 3.6+ | Git, Hg, SVN | RFC 1459 | - -## Deprecation Policy - -We follow a gradual deprecation process: - -1. **Announcement**: Feature marked as deprecated in changelog -2. **Warning Period**: Minimum 2 minor versions or 6 months -3. **Deprecation**: Feature issues warnings when used -4. **Removal**: Feature removed in next major version - -### Current Deprecations -- (None) - -### Planned Deprecations -- (None) - -## Security Updates - -Security updates are released as soon as fixes are available and tested. - -### Security Advisories - -| Date | Severity | CVE | Description | Fixed In | -| ---------- | -------- | --- | ----------- | -------- | -| (None yet) | - | - | - | - | - -See [SECURITY.md](SECURITY.md) for vulnerability disclosure process. - -## Breaking Changes - -We avoid breaking changes whenever possible. When necessary, they are: -- Documented in detail -- Announced at least one major version in advance -- Include migration guides -- Provide backward compatibility shims when feasible - -### Major Version Breaking Changes - -**2.0.0** (Future): -- (None planned yet) - -**1.0.0**: -- Repository rename: irker → vext -- License change: BSD-2-Clause → MPL-2.0 (Palimpsest) - - Note: Both are permissive; users can choose MIT for backward compatibility - -## Contribution Credits - -See [CONTRIBUTORS.md](CONTRIBUTORS.md) for full list of contributors. - -### Major Contributors by Version - -**1.0.0**: -- [Lead Maintainer] - Project lead, RSR compliance, documentation -- [Core Developer 1] - IRC protocol, network layer -- [Core Developer 2] - Build systems, CI/CD - -**0.1.0**: -- Eric S. Raymond - Original irker author - -## Release Channels - -### Stable -- **Version**: 1.0.0 -- **Support**: Full support with security updates -- **Recommended For**: Production use - -### Development -- **Branch**: `main` -- **Stability**: May contain breaking changes -- **Recommended For**: Testing, early adopters - -### Long-Term Support (LTS) -- **Version**: (None yet) -- **Support**: Extended security and bug fix support -- **Recommended For**: Enterprise deployments - -## Changelog Maintenance - -This changelog is: -- **Updated**: With every release -- **Format**: [Keep a Changelog](https://keepachangelog.com/) -- **Versioning**: [Semantic Versioning](https://semver.org/) -- **Maintained By**: Release managers (see [MAINTAINERS.md](MAINTAINERS.md)) - -## Comparison with Upstream (irker) - -| Feature | irker | vext | Notes | -| ------- | ----- | ---- | ----- | -| Core IRC functionality | ✅ | ✅ | Fully compatible | -| Multi-VCS support | ✅ | ✅ | Git, Hg, SVN | -| JSON protocol | ✅ | ✅ | Identical | -| Documentation | Basic | Comprehensive | Major improvement | -| Security policies | Informal | Formal | RFC 9116 compliant | -| Build system | Basic | Modern | Nix, just, CI/CD | -| Governance | None | TPCF | Formal framework | -| Testing | Limited | Comprehensive | Automated testing | -| RSR compliance | None | Silver | Structured standards | - -## Historical Context - -**vext** is a modernized fork of **irker** by Eric S. Raymond: -- **Original Project**: https://gitlab.com/esr/irker -- **Fork Date**: 2025-01-01 -- **Fork Reason**: Active maintenance, comprehensive documentation, modern standards -- **Compatibility**: Full backward compatibility with irker -- **Acknowledgment**: We thank Eric S. Raymond for creating irker - -## Future Roadmap - -See [docs/roadmap/ROADMAP.md](docs/roadmap/ROADMAP.md) for detailed future plans. - -**Upcoming**: -- 1.1.0: Enhanced monitoring and metrics -- 1.2.0: Additional IRC protocol extensions (SASL, TLS) -- 2.0.0: Architectural improvements, potential breaking changes - ---- - -**Changelog Maintained By**: Release Team -**Last Updated**: 2025-01-01 -**Format Version**: 1.0.0 (Keep a Changelog) - -For questions about releases, contact: release@vext.dev diff --git a/vext/CODE_OF_CONDUCT.adoc b/vext/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..9b4e0c7 --- /dev/null +++ b/vext/CODE_OF_CONDUCT.adoc @@ -0,0 +1,286 @@ +== Code of Conduct + +**SPDX-License-Identifier: CC-BY-SA-4.0 + +=== 🌟 Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community 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, color, 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. + +=== 📏 Our Standards + +==== Positive Behavior + +Examples of behavior that contributes to a positive environment: + +* *Empathy and Kindness*: Being understanding and compassionate toward +others +* *Respect*: Valuing different opinions, viewpoints, and experiences +* *Constructive Feedback*: Giving and accepting feedback gracefully +* *Accountability*: Accepting responsibility for mistakes and learning +from them +* *Community Focus*: Prioritizing what is best for the overall community +* *Collaboration*: Working together toward common goals +* *Inclusivity*: Welcoming newcomers and helping them succeed +* *Patience*: Understanding that people have different skill levels and +learning paces + +==== Unacceptable Behavior + +Examples of unacceptable behavior: + +* *Harassment*: Sexualized language/imagery, unwelcome sexual attention +or advances +* *Trolling*: Insulting/derogatory comments, personal or political +attacks +* *Doxxing*: Publishing others’ private information without permission +* *Conduct*: Other conduct reasonably considered inappropriate in a +professional setting +* *Discrimination*: Any form of discrimination based on protected +characteristics +* *Intimidation*: Deliberate intimidation, stalking, or following +* *Disruption*: Sustained disruption of discussions or events + +=== 🎯 Emotional Safety Framework + +Beyond basic respect, we prioritize *emotional safety* in our community: + +==== Psychological Safety + +* *Safe to Experiment*: Mistakes are learning opportunities, not +failures +* *Safe to Question*: No question is "`stupid`" or unwelcome +* *Safe to Disagree*: Technical disagreements are healthy when +respectful +* *Safe to Learn*: Everyone was a beginner once + +==== Anxiety Reduction + +* *Clear Documentation*: Reduce uncertainty with comprehensive guides +* *Predictable Processes*: Well-defined contribution workflow +* *Supportive Reviews*: Code review focuses on improvement, not +criticism +* *Reversibility*: Design decisions can be changed if better approaches +emerge + +==== Stress Management + +* *No Crunch Culture*: Sustainable pace, no burnout encouraged +* *Work-Life Balance*: Respect personal boundaries and time zones +* *Mental Health*: Breaks and time away are encouraged and respected +* *Compassionate Communication*: Assume good intent, communicate kindly + +=== 👥 Responsibilities + +==== Community Leaders + +Project maintainers are responsible for: + +* *Clarifying Standards*: Explaining and enforcing standards of +acceptable behavior +* *Fair Moderation*: Taking appropriate and fair corrective action +* *Content Moderation*: Removing/rejecting inappropriate content +* *Banning*: Temporarily or permanently banning inappropriate +participants +* *Transparency*: Communicating reasons for moderation decisions + +==== All Participants + +All community members are expected to: + +* *Follow Standards*: Adhere to this Code of Conduct +* *Report Violations*: Report unacceptable behavior to moderators +* *Support Others*: Help create a welcoming environment +* *Learn and Grow*: Be open to feedback and continuous improvement + +=== 🚨 Enforcement + +==== Reporting + +If you experience or witness unacceptable behavior: + +*Primary Contact:* - Email: conduct@vext.dev - Expected response: Within +24 hours + +*Confidential Reporting:* - All reports are treated confidentially - +Reporters’ identity is protected - Anonymous reports accepted but may be +harder to follow up + +*What to Include:* - Description of the incident - When and where it +occurred - Who was involved - Any relevant screenshots or logs - Your +contact information (unless reporting anonymously) + +==== Investigation Process + +[arabic] +. *Acknowledgment* (24 hours) +* Confirm receipt of report +* Assign to appropriate moderator +* Provide incident number +. *Investigation* (1-7 days) +* Review all available information +* Interview involved parties if needed +* Consult with other moderators +* Determine appropriate action +. *Resolution* (After investigation) +* Take corrective action +* Communicate decision to involved parties +* Document incident (confidentially) + +==== Enforcement Guidelines + +We follow a graduated enforcement approach: + +===== 1. Correction (Minor Violation) + +*Impact*: Use of inappropriate language or unprofessional behavior + +*Consequence*: - Private written warning - Clarification of violation - +Apology may be requested - No public record + +*Example*: Heated technical argument that became personal + +===== 2. Warning (Moderate Violation) + +*Impact*: Repeated minor violations or single moderate violation + +*Consequence*: - Formal written warning - Temporary restriction of +privileges - Public or private (depending on severity) - Recorded in +moderation log + +*Example*: Continued argumentative behavior after correction + +===== 3. Temporary Ban (Serious Violation) + +*Impact*: Sustained inappropriate behavior or harassment + +*Consequence*: - Temporary ban (7-90 days) - No interaction with +community - Prohibited from public or private communication - Public +announcement of ban + +*Example*: Harassment, doxxing, or discriminatory behavior + +===== 4. Permanent Ban (Severe Violation) + +*Impact*: Severe violations, sustained harassment, or repeated serious +violations + +*Consequence*: - Permanent expulsion from community - All accounts and +access revoked - Public announcement - May involve legal action if +applicable + +*Example*: Threats, severe harassment, coordinated attacks + +=== 🔄 Appeals + +You may appeal enforcement decisions: + +[arabic] +. *Submit Appeal*: Email conduct-appeal@vext.dev within 30 days +. *Include*: Incident number, reason for appeal, additional context +. *Review*: Different moderator reviews the case +. *Decision*: Final decision within 14 days +. *Outcome*: Decision is final and binding + +=== 🌍 Scope + +This Code of Conduct applies: + +* *Project Spaces*: GitHub, GitLab, chat channels, mailing lists +* *Public Representation*: Social media, conferences, meetups when +representing the project +* *Private Communication*: When affecting community members (extreme +cases) +* *Events*: Any vext-related events, online or in-person + +=== 🎓 Training and Resources + +We provide resources to help build a positive community: + +* *Onboarding Guide*: How to contribute positively +* *Communication Guide*: Effective and empathetic communication +* *Conflict Resolution*: How to handle disagreements constructively +* *Unconscious Bias Training*: Recognizing and addressing biases + +=== 📊 Transparency Reports + +We publish quarterly transparency reports: + +* Number of reports received +* Categories of violations +* Actions taken (anonymized) +* Trends and patterns +* Improvements made + +See: `+docs/conduct/transparency/+` + +=== 🤝 Conflict Resolution + +Before formal reports, consider: + +[arabic] +. *Direct Communication*: Politely address the issue directly (if safe) +. *Request Mediation*: Ask a moderator to facilitate discussion +. *Take a Break*: Step away from heated discussions +. *Seek Advice*: Ask moderators for guidance (not necessarily a report) + +=== 💡 Positive Examples + +==== Good Technical Disagreement + +❌ *Bad*: "`That’s a stupid idea. Anyone who knows Python would see the +problem.`" + +✅ *Good*: "`I have concerns about this approach. In my experience, +[specific technical reason]. Have you considered [alternative]? I’d be +happy to discuss further.`" + +==== Good Feedback + +❌ *Bad*: "`This code is terrible. Did you even test it?`" + +✅ *Good*: "`Thanks for the contribution! I noticed a few edge cases +that might need handling: [specific cases]. Here’s how similar issues +were addressed in [other file]. Want to pair on this?`" + +==== Good Questions + +❌ *Bad*: "`Why doesn’t this work? The docs are useless.`" + +✅ *Good*: "`I’m trying to [goal] and getting [error]. I’ve read [doc +section] and tried [attempt]. Could someone point me in the right +direction?`" + +=== 🙏 Attribution + +This Code of Conduct is adapted from: - +https://www.contributor-covenant.org/[Contributor Covenant], version 2.1 +- https://www.djangoproject.com/conduct/[Django Code of Conduct] - +https://www.rust-lang.org/policies/code-of-conduct[Rust Code of Conduct] +- https://github.com/compassionate-coding/[Compassionate Collaboration +Community Principles (CCCP)] + +=== 📞 Contact + +* *Code of Conduct Violations*: conduct@vext.dev +* *Appeals*: conduct-appeal@vext.dev +* *General Questions*: community@vext.dev +* *Immediate Safety Concerns*: Call local emergency services + +=== 📄 License + +This Code of Conduct is licensed under +https://creativecommons.org/licenses/by/4.0/[CC BY 4.0]. + +''''' + +*Last Updated*: 2025-01-01 *Version*: 1.1 *Next Review*: 2025-07-01 + +Thank you for helping make vext a welcoming and inclusive community! 💙 diff --git a/vext/CODE_OF_CONDUCT.md b/vext/CODE_OF_CONDUCT.md deleted file mode 100644 index 504dca0..0000000 --- a/vext/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,267 +0,0 @@ - -# Code of Conduct - -**SPDX-License-Identifier: CC-BY-SA-4.0 - -## 🌟 Our Pledge - -We as members, contributors, and leaders pledge to make participation in our community 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, color, 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. - -## 📏 Our Standards - -### Positive Behavior - -Examples of behavior that contributes to a positive environment: - -- **Empathy and Kindness**: Being understanding and compassionate toward others -- **Respect**: Valuing different opinions, viewpoints, and experiences -- **Constructive Feedback**: Giving and accepting feedback gracefully -- **Accountability**: Accepting responsibility for mistakes and learning from them -- **Community Focus**: Prioritizing what is best for the overall community -- **Collaboration**: Working together toward common goals -- **Inclusivity**: Welcoming newcomers and helping them succeed -- **Patience**: Understanding that people have different skill levels and learning paces - -### Unacceptable Behavior - -Examples of unacceptable behavior: - -- **Harassment**: Sexualized language/imagery, unwelcome sexual attention or advances -- **Trolling**: Insulting/derogatory comments, personal or political attacks -- **Doxxing**: Publishing others' private information without permission -- **Conduct**: Other conduct reasonably considered inappropriate in a professional setting -- **Discrimination**: Any form of discrimination based on protected characteristics -- **Intimidation**: Deliberate intimidation, stalking, or following -- **Disruption**: Sustained disruption of discussions or events - -## 🎯 Emotional Safety Framework - -Beyond basic respect, we prioritize **emotional safety** in our community: - -### Psychological Safety -- **Safe to Experiment**: Mistakes are learning opportunities, not failures -- **Safe to Question**: No question is "stupid" or unwelcome -- **Safe to Disagree**: Technical disagreements are healthy when respectful -- **Safe to Learn**: Everyone was a beginner once - -### Anxiety Reduction -- **Clear Documentation**: Reduce uncertainty with comprehensive guides -- **Predictable Processes**: Well-defined contribution workflow -- **Supportive Reviews**: Code review focuses on improvement, not criticism -- **Reversibility**: Design decisions can be changed if better approaches emerge - -### Stress Management -- **No Crunch Culture**: Sustainable pace, no burnout encouraged -- **Work-Life Balance**: Respect personal boundaries and time zones -- **Mental Health**: Breaks and time away are encouraged and respected -- **Compassionate Communication**: Assume good intent, communicate kindly - -## 👥 Responsibilities - -### Community Leaders - -Project maintainers are responsible for: - -- **Clarifying Standards**: Explaining and enforcing standards of acceptable behavior -- **Fair Moderation**: Taking appropriate and fair corrective action -- **Content Moderation**: Removing/rejecting inappropriate content -- **Banning**: Temporarily or permanently banning inappropriate participants -- **Transparency**: Communicating reasons for moderation decisions - -### All Participants - -All community members are expected to: - -- **Follow Standards**: Adhere to this Code of Conduct -- **Report Violations**: Report unacceptable behavior to moderators -- **Support Others**: Help create a welcoming environment -- **Learn and Grow**: Be open to feedback and continuous improvement - -## 🚨 Enforcement - -### Reporting - -If you experience or witness unacceptable behavior: - -**Primary Contact:** -- Email: conduct@vext.dev -- Expected response: Within 24 hours - -**Confidential Reporting:** -- All reports are treated confidentially -- Reporters' identity is protected -- Anonymous reports accepted but may be harder to follow up - -**What to Include:** -- Description of the incident -- When and where it occurred -- Who was involved -- Any relevant screenshots or logs -- Your contact information (unless reporting anonymously) - -### Investigation Process - -1. **Acknowledgment** (24 hours) - - Confirm receipt of report - - Assign to appropriate moderator - - Provide incident number - -2. **Investigation** (1-7 days) - - Review all available information - - Interview involved parties if needed - - Consult with other moderators - - Determine appropriate action - -3. **Resolution** (After investigation) - - Take corrective action - - Communicate decision to involved parties - - Document incident (confidentially) - -### Enforcement Guidelines - -We follow a graduated enforcement approach: - -#### 1. Correction (Minor Violation) -**Impact**: Use of inappropriate language or unprofessional behavior - -**Consequence**: -- Private written warning -- Clarification of violation -- Apology may be requested -- No public record - -**Example**: Heated technical argument that became personal - -#### 2. Warning (Moderate Violation) -**Impact**: Repeated minor violations or single moderate violation - -**Consequence**: -- Formal written warning -- Temporary restriction of privileges -- Public or private (depending on severity) -- Recorded in moderation log - -**Example**: Continued argumentative behavior after correction - -#### 3. Temporary Ban (Serious Violation) -**Impact**: Sustained inappropriate behavior or harassment - -**Consequence**: -- Temporary ban (7-90 days) -- No interaction with community -- Prohibited from public or private communication -- Public announcement of ban - -**Example**: Harassment, doxxing, or discriminatory behavior - -#### 4. Permanent Ban (Severe Violation) -**Impact**: Severe violations, sustained harassment, or repeated serious violations - -**Consequence**: -- Permanent expulsion from community -- All accounts and access revoked -- Public announcement -- May involve legal action if applicable - -**Example**: Threats, severe harassment, coordinated attacks - -## 🔄 Appeals - -You may appeal enforcement decisions: - -1. **Submit Appeal**: Email conduct-appeal@vext.dev within 30 days -2. **Include**: Incident number, reason for appeal, additional context -3. **Review**: Different moderator reviews the case -4. **Decision**: Final decision within 14 days -5. **Outcome**: Decision is final and binding - -## 🌍 Scope - -This Code of Conduct applies: - -- **Project Spaces**: GitHub, GitLab, chat channels, mailing lists -- **Public Representation**: Social media, conferences, meetups when representing the project -- **Private Communication**: When affecting community members (extreme cases) -- **Events**: Any vext-related events, online or in-person - -## 🎓 Training and Resources - -We provide resources to help build a positive community: - -- **Onboarding Guide**: How to contribute positively -- **Communication Guide**: Effective and empathetic communication -- **Conflict Resolution**: How to handle disagreements constructively -- **Unconscious Bias Training**: Recognizing and addressing biases - -## 📊 Transparency Reports - -We publish quarterly transparency reports: - -- Number of reports received -- Categories of violations -- Actions taken (anonymized) -- Trends and patterns -- Improvements made - -See: `docs/conduct/transparency/` - -## 🤝 Conflict Resolution - -Before formal reports, consider: - -1. **Direct Communication**: Politely address the issue directly (if safe) -2. **Request Mediation**: Ask a moderator to facilitate discussion -3. **Take a Break**: Step away from heated discussions -4. **Seek Advice**: Ask moderators for guidance (not necessarily a report) - -## 💡 Positive Examples - -### Good Technical Disagreement - -❌ **Bad**: "That's a stupid idea. Anyone who knows Python would see the problem." - -✅ **Good**: "I have concerns about this approach. In my experience, [specific technical reason]. Have you considered [alternative]? I'd be happy to discuss further." - -### Good Feedback - -❌ **Bad**: "This code is terrible. Did you even test it?" - -✅ **Good**: "Thanks for the contribution! I noticed a few edge cases that might need handling: [specific cases]. Here's how similar issues were addressed in [other file]. Want to pair on this?" - -### Good Questions - -❌ **Bad**: "Why doesn't this work? The docs are useless." - -✅ **Good**: "I'm trying to [goal] and getting [error]. I've read [doc section] and tried [attempt]. Could someone point me in the right direction?" - -## 🙏 Attribution - -This Code of Conduct is adapted from: -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Compassionate Collaboration Community Principles (CCCP)](https://github.com/compassionate-coding/) - -## 📞 Contact - -- **Code of Conduct Violations**: conduct@vext.dev -- **Appeals**: conduct-appeal@vext.dev -- **General Questions**: community@vext.dev -- **Immediate Safety Concerns**: Call local emergency services - -## 📄 License - -This Code of Conduct is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). - ---- - -**Last Updated**: 2025-01-01 -**Version**: 1.1 -**Next Review**: 2025-07-01 - -Thank you for helping make vext a welcoming and inclusive community! 💙 diff --git a/vext/CONTRIBUTING.adoc b/vext/CONTRIBUTING.adoc index e9b1993..dab29bd 100644 --- a/vext/CONTRIBUTING.adoc +++ b/vext/CONTRIBUTING.adoc @@ -1,21 +1,3 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Contributing Guide - -== Getting Started - -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request - -== Commit Guidelines - -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits - -== License - -Contributions licensed under project license. +== Contributing +See CONTRIBUTING.adoc for full contribution guidelines. diff --git a/vext/CONTRIBUTING.md b/vext/CONTRIBUTING.md deleted file mode 100644 index 66fae77..0000000 --- a/vext/CONTRIBUTING.md +++ /dev/null @@ -1,7 +0,0 @@ - -# Contributing - -See [CONTRIBUTING.adoc](CONTRIBUTING.adoc) for full contribution guidelines. diff --git a/vext/DOCUMENTATION_INDEX.adoc b/vext/DOCUMENTATION_INDEX.adoc new file mode 100644 index 0000000..fd5fd39 --- /dev/null +++ b/vext/DOCUMENTATION_INDEX.adoc @@ -0,0 +1,369 @@ +== vext Documentation Index + +=== Quick Navigation + +Welcome to the vext (Rhodium Standard Edition) documentation. This index +helps you find the right guide for your needs. + +==== For New Users + +Start here to understand what vext is and get it running: + +[arabic] +. *README.md* (Main Entry Point) +* Project overview and description +* Key features and technology stack +* Installation requirements and basic usage +* Architecture and design philosophy +* *Read this first!* +. *INSTALLATION_GUIDE.md* +* Step-by-step installation instructions +* Multiple installation methods (source, package manager, Docker) +* Post-installation configuration +* Repository-specific setup for Git, Mercurial, and SVN +* Troubleshooting installation issues +. *USAGE_GUIDE.md* +* Starting and managing the daemon +* Sending notifications (basic and advanced) +* Repository hook configuration +* Configuration management +* Monitoring and debugging +* Advanced usage patterns + +==== For Understanding the Project + +Learn more about what vext does and how it works: + +[arabic, start=4] +. *PROJECT_OVERVIEW.md* +* Problem statement and solution +* Core concepts and architecture +* Use cases and advantages +* Comparison with alternatives +* Deployment options +* Roadmap and future enhancements +. *FEATURES.md* +* Comprehensive feature list +* Multi-version control system support +* Persistent connection management +* Flexible communication protocols +* Advanced features +* Feature comparison matrix + +==== For Technical Details + +Deep dive into the technical implementation: + +[arabic, start=6] +. *TECHNOLOGY_STACK.md* +* Language and runtime information +* Core and optional dependencies +* Architecture components +* Network protocols (IRC, JSON, HTTP) +* Data flow architecture +* Performance characteristics +* Security technologies +* Monitoring and observability + +=== Document Structure + +==== README.md (800 lines) + +*Purpose*: Main project documentation, suitable for GitHub/GitLab README + +*Covers*: - 2-3 paragraph project description - What irker does - What +vext improves - Core functionality and use cases - Key features (12 main +features) - Technology stack overview - Installation requirements - +Basic usage examples - Architecture overview - Configuration options - +Use cases - Troubleshooting guide - License and status + +*Best For*: Getting started, quick reference, GitHub visibility + +''''' + +==== PROJECT_OVERVIEW.md (450 lines) + +*Purpose*: Executive-level project overview and strategy + +*Covers*: - Executive summary - Problem statement (5 problems solved) - +Solution approach - Core concept with diagram - Primary and secondary +use cases - Technical architecture - Advantages comparison table - +Technology stack summary - Installation footprint - Security +considerations - Performance characteristics - Scalability approach - +Maintenance model - Comparison with original irker - Deployment options +- Roadmap (short, medium, long term) + +*Best For*: Understanding project goals, stakeholder communication, +planning + +''''' + +==== FEATURES.md (650 lines) + +*Purpose*: Comprehensive feature documentation + +*Covers*: - 12 core features with detailed explanations - Multi-VCS +support (Git, Mercurial, SVN) - Persistent connection management - +Flexible communication protocols (TCP, UDP, Email) - JSON protocol +details - Multi-channel broadcasting - Color formatting - Configurable +formats - Rate limiting and flood prevention - Comprehensive logging - +Flexible routing - Performance optimization - Security features - 6 +advanced features - Feature comparison matrix + +*Best For*: Feature comparison, capability assessment, planning +integrations + +''''' + +==== TECHNOLOGY_STACK.md (800 lines) + +*Purpose*: Technical implementation details + +*Covers*: - Python language and version support - Core dependencies +(standard library only) - Optional dependencies - Development tools - +Architecture components with code examples - Concurrency model and +threading - Event loop pattern - Network protocols (IRC RFC 1459, JSON, +HTTP) - Data flow pipeline - State management - Performance profiles - +Deployment architecture - System requirements - Operating system support +- Systemd integration - Configuration as code - Security technologies - +Monitoring and observability - Version management - Integration points + +*Best For*: Architecture understanding, integration planning, deployment +design + +''''' + +==== INSTALLATION_GUIDE.md (550 lines) + +*Purpose*: Step-by-step installation and configuration + +*Covers*: - Prerequisites and requirements - 4 installation methods: - +From source with virtual environment - Package manager (Ubuntu, CentOS, +macOS) - Docker container deployment - System-wide manual installation - +Post-installation configuration: - Config file creation - Log directory +setup - Environment variables - Repository-specific setup: - Git +post-receive hook - Mercurial hook integration - Subversion hook +configuration - Testing procedures - Troubleshooting common issues - +Uninstallation instructions + +*Best For*: Getting vext running, setting up hooks, troubleshooting +setup issues + +''''' + +==== USAGE_GUIDE.md (700 lines) + +*Purpose*: Operational guide for running vext + +*Covers*: - Quick start (3 steps) - Daemon management: - Command-line +options - Systemd service management - Manual service management - +Sending notifications: - Basic notifications - Multi-channel routing - +Color formatting - Custom nicknames - Python script examples - TCP vs +UDP - Bash script helpers - Repository hook configuration: - Git (basic +and advanced) - Mercurial - Subversion - Configuration management - +Monitoring and troubleshooting: - Status checks - IRC connectivity +testing - Hook debugging - Common issues - Advanced usage patterns - +Performance tuning + +*Best For*: Daily operations, troubleshooting, integration examples + +''''' + +==== DOCUMENTATION_INDEX.md (This File) + +*Purpose*: Navigation and organization guide + +=== File Statistics + +* *Total Documentation Files*: 6 markdown files + this index +* *Total Lines*: ~2,935 lines of documentation +* *Total Coverage*: +** Project overview and strategy +** Complete feature list +** Technical architecture +** Installation procedures +** Usage and operations +** Troubleshooting and support + +=== Quick Reference by Topic + +==== Installation & Setup + +* *Getting Started*: README.md → INSTALLATION_GUIDE.md +* *Docker Setup*: +link:INSTALLATION_GUIDE.md#method-3-docker-container-deployment[INSTALLATION_GUIDE.md] +* *Git Hook Setup*: +link:INSTALLATION_GUIDE.md#git-repository-hook-installation[INSTALLATION_GUIDE.md] +* *Post-Installation*: +link:INSTALLATION_GUIDE.md#post-installation-configuration[INSTALLATION_GUIDE.md] + +==== Operation & Troubleshooting + +* *Starting Daemon*: +link:USAGE_GUIDE.md#starting-and-managing-the-daemon[USAGE_GUIDE.md] +* *Sending Notifications*: +link:USAGE_GUIDE.md#sending-notifications[USAGE_GUIDE.md] +* *Debugging Issues*: +link:USAGE_GUIDE.md#monitoring-and-troubleshooting[USAGE_GUIDE.md] +* *Performance Tuning*: +link:USAGE_GUIDE.md#performance-tuning[USAGE_GUIDE.md] + +==== Features & Capabilities + +* *Feature List*: FEATURES.md +* *VCS Support*: +link:FEATURES.md#1-multi-version-control-system-support[FEATURES.md] +* *Protocols*: +link:FEATURES.md#3-flexible-communication-protocols[FEATURES.md] +* *Advanced Features*: link:FEATURES.md#advanced-features[FEATURES.md] + +==== Technical Details + +* *Architecture*: +link:TECHNOLOGY_STACK.md#architecture-components[TECHNOLOGY_STACK.md] +* *Performance*: +link:TECHNOLOGY_STACK.md#performance-characteristics[TECHNOLOGY_STACK.md] +* *Security*: +link:TECHNOLOGY_STACK.md#security-technologies[TECHNOLOGY_STACK.md] +* *System Requirements*: +link:TECHNOLOGY_STACK.md#system-requirements[TECHNOLOGY_STACK.md] + +==== Project Information + +* *Overview*: PROJECT_OVERVIEW.md +* *Use Cases*: link:PROJECT_OVERVIEW.md#use-cases[PROJECT_OVERVIEW.md] +* *Roadmap*: link:PROJECT_OVERVIEW.md#roadmap[PROJECT_OVERVIEW.md] + +=== Document Relationships + +.... +README.md (Entry Point) +├─ Quick overview +├─ Links to: INSTALLATION_GUIDE.md, USAGE_GUIDE.md +└─ References: FEATURES.md, TECHNOLOGY_STACK.md + +PROJECT_OVERVIEW.md (Strategic View) +├─ What and why? +├─ References: README.md +└─ Links to: INSTALLATION_GUIDE.md, FEATURES.md + +FEATURES.md (Capabilities) +├─ What can it do? +├─ References: README.md +└─ Links to: USAGE_GUIDE.md, TECHNOLOGY_STACK.md + +TECHNOLOGY_STACK.md (Implementation) +├─ How is it built? +├─ References: README.md, FEATURES.md +└─ Links to: INSTALLATION_GUIDE.md + +INSTALLATION_GUIDE.md (Getting Started) +├─ How to install? +├─ References: README.md +└─ Links to: USAGE_GUIDE.md, POST_CONFIGURATION + +USAGE_GUIDE.md (Operations) +├─ How to use? +├─ References: INSTALLATION_GUIDE.md +└─ Links to: TROUBLESHOOTING +.... + +=== Audience Guide + +==== Decision Makers / Managers + +[arabic] +. Start: PROJECT_OVERVIEW.md +. Then: link:FEATURES.md#comparison-feature-matrix[FEATURES.md] +. Reference: link:README.md#advantages-over-alternatives[README.md] + +==== Developers / System Administrators + +[arabic] +. Start: README.md +. Then: INSTALLATION_GUIDE.md +. Reference: USAGE_GUIDE.md, TECHNOLOGY_STACK.md + +==== Operations / DevOps Teams + +[arabic] +. Start: +link:INSTALLATION_GUIDE.md#method-3-docker-container-deployment[INSTALLATION_GUIDE.md] +. Then: link:USAGE_GUIDE.md#systemd-service-management[USAGE_GUIDE.md] +. Reference: +link:PROJECT_OVERVIEW.md#deployment-options[PROJECT_OVERVIEW.md] + +==== Integrators / Developers Building on vext + +[arabic] +. Start: TECHNOLOGY_STACK.md +. Then: link:FEATURES.md#advanced-features[FEATURES.md] +. Reference: link:USAGE_GUIDE.md#advanced-usage[USAGE_GUIDE.md] + +=== Getting Help + +==== Common Questions + +*"`What is vext?`"* → Read README.md (Project Overview section) + +*"`How do I install it?`"* → Follow INSTALLATION_GUIDE.md + +*"`How do I use it?`"* → See +link:USAGE_GUIDE.md#quick-start[USAGE_GUIDE.md] + +*"`Does it support my VCS?`"* → Check +link:FEATURES.md#1-multi-version-control-system-support[FEATURES.md] + +*"`What are the requirements?`"* → Review +link:README.md#installation-requirements[README.md] + +*"`How does it work?`"* → Study +link:TECHNOLOGY_STACK.md#architecture-components[TECHNOLOGY_STACK.md] + +*"`Can I customize it?`"* → See +link:FEATURES.md#advanced-features[FEATURES.md] and +link:USAGE_GUIDE.md#advanced-usage[USAGE_GUIDE.md] + +*"`What’s the roadmap?`"* → Check +link:PROJECT_OVERVIEW.md#roadmap[PROJECT_OVERVIEW.md] + +=== Documentation Standards + +All documentation follows these standards: + +* *Markdown format* for GitHub/GitLab compatibility +* *Clear structure* with headers, sections, and subsections +* *Practical examples* for most features +* *Code blocks* with language specification +* *Tables* for comparisons and matrices +* *Links* between related documents +* *TOC-friendly* with descriptive headers +* *Accessible* to both technical and non-technical readers + +=== Contributing to Documentation + +When adding new documentation: + +[arabic] +. Follow the structure and style of existing documents +. Add new files and update this index +. Link to related documents using markdown links +. Include practical examples where applicable +. Update the file statistics above +. Ensure markdown validates correctly + +=== Version Information + +* *Documentation Version*: 1.0 +* *Last Updated*: 2025-11-22 +* *vext Version*: Rhodium Standard Edition +* *Related Project*: irker (by Eric S. Raymond) + +=== License + +All documentation is provided under the same license as vext: *Eclipse +Public License 2.0* + +''''' + +*Start with README.md if you’re new to vext!* diff --git a/vext/DOCUMENTATION_INDEX.md b/vext/DOCUMENTATION_INDEX.md deleted file mode 100644 index 5991996..0000000 --- a/vext/DOCUMENTATION_INDEX.md +++ /dev/null @@ -1,401 +0,0 @@ - -# vext Documentation Index - -## Quick Navigation - -Welcome to the vext (Rhodium Standard Edition) documentation. This index helps you find the right guide for your needs. - -### For New Users - -Start here to understand what vext is and get it running: - -1. **[README.md](README.md)** (Main Entry Point) - - Project overview and description - - Key features and technology stack - - Installation requirements and basic usage - - Architecture and design philosophy - - **Read this first!** - -2. **[INSTALLATION_GUIDE.md](INSTALLATION_GUIDE.md)** - - Step-by-step installation instructions - - Multiple installation methods (source, package manager, Docker) - - Post-installation configuration - - Repository-specific setup for Git, Mercurial, and SVN - - Troubleshooting installation issues - -3. **[USAGE_GUIDE.md](USAGE_GUIDE.md)** - - Starting and managing the daemon - - Sending notifications (basic and advanced) - - Repository hook configuration - - Configuration management - - Monitoring and debugging - - Advanced usage patterns - -### For Understanding the Project - -Learn more about what vext does and how it works: - -4. **[PROJECT_OVERVIEW.md](PROJECT_OVERVIEW.md)** - - Problem statement and solution - - Core concepts and architecture - - Use cases and advantages - - Comparison with alternatives - - Deployment options - - Roadmap and future enhancements - -5. **[FEATURES.md](FEATURES.md)** - - Comprehensive feature list - - Multi-version control system support - - Persistent connection management - - Flexible communication protocols - - Advanced features - - Feature comparison matrix - -### For Technical Details - -Deep dive into the technical implementation: - -6. **[TECHNOLOGY_STACK.md](TECHNOLOGY_STACK.md)** - - Language and runtime information - - Core and optional dependencies - - Architecture components - - Network protocols (IRC, JSON, HTTP) - - Data flow architecture - - Performance characteristics - - Security technologies - - Monitoring and observability - -## Document Structure - -### README.md (800 lines) -**Purpose**: Main project documentation, suitable for GitHub/GitLab README - -**Covers**: -- 2-3 paragraph project description -- What irker does -- What vext improves -- Core functionality and use cases -- Key features (12 main features) -- Technology stack overview -- Installation requirements -- Basic usage examples -- Architecture overview -- Configuration options -- Use cases -- Troubleshooting guide -- License and status - -**Best For**: Getting started, quick reference, GitHub visibility - ---- - -### PROJECT_OVERVIEW.md (450 lines) -**Purpose**: Executive-level project overview and strategy - -**Covers**: -- Executive summary -- Problem statement (5 problems solved) -- Solution approach -- Core concept with diagram -- Primary and secondary use cases -- Technical architecture -- Advantages comparison table -- Technology stack summary -- Installation footprint -- Security considerations -- Performance characteristics -- Scalability approach -- Maintenance model -- Comparison with original irker -- Deployment options -- Roadmap (short, medium, long term) - -**Best For**: Understanding project goals, stakeholder communication, planning - ---- - -### FEATURES.md (650 lines) -**Purpose**: Comprehensive feature documentation - -**Covers**: -- 12 core features with detailed explanations -- Multi-VCS support (Git, Mercurial, SVN) -- Persistent connection management -- Flexible communication protocols (TCP, UDP, Email) -- JSON protocol details -- Multi-channel broadcasting -- Color formatting -- Configurable formats -- Rate limiting and flood prevention -- Comprehensive logging -- Flexible routing -- Performance optimization -- Security features -- 6 advanced features -- Feature comparison matrix - -**Best For**: Feature comparison, capability assessment, planning integrations - ---- - -### TECHNOLOGY_STACK.md (800 lines) -**Purpose**: Technical implementation details - -**Covers**: -- Python language and version support -- Core dependencies (standard library only) -- Optional dependencies -- Development tools -- Architecture components with code examples -- Concurrency model and threading -- Event loop pattern -- Network protocols (IRC RFC 1459, JSON, HTTP) -- Data flow pipeline -- State management -- Performance profiles -- Deployment architecture -- System requirements -- Operating system support -- Systemd integration -- Configuration as code -- Security technologies -- Monitoring and observability -- Version management -- Integration points - -**Best For**: Architecture understanding, integration planning, deployment design - ---- - -### INSTALLATION_GUIDE.md (550 lines) -**Purpose**: Step-by-step installation and configuration - -**Covers**: -- Prerequisites and requirements -- 4 installation methods: - - From source with virtual environment - - Package manager (Ubuntu, CentOS, macOS) - - Docker container deployment - - System-wide manual installation -- Post-installation configuration: - - Config file creation - - Log directory setup - - Environment variables -- Repository-specific setup: - - Git post-receive hook - - Mercurial hook integration - - Subversion hook configuration -- Testing procedures -- Troubleshooting common issues -- Uninstallation instructions - -**Best For**: Getting vext running, setting up hooks, troubleshooting setup issues - ---- - -### USAGE_GUIDE.md (700 lines) -**Purpose**: Operational guide for running vext - -**Covers**: -- Quick start (3 steps) -- Daemon management: - - Command-line options - - Systemd service management - - Manual service management -- Sending notifications: - - Basic notifications - - Multi-channel routing - - Color formatting - - Custom nicknames - - Python script examples - - TCP vs UDP - - Bash script helpers -- Repository hook configuration: - - Git (basic and advanced) - - Mercurial - - Subversion -- Configuration management -- Monitoring and troubleshooting: - - Status checks - - IRC connectivity testing - - Hook debugging - - Common issues -- Advanced usage patterns -- Performance tuning - -**Best For**: Daily operations, troubleshooting, integration examples - ---- - -### DOCUMENTATION_INDEX.md (This File) -**Purpose**: Navigation and organization guide - -## File Statistics - -- **Total Documentation Files**: 6 markdown files + this index -- **Total Lines**: ~2,935 lines of documentation -- **Total Coverage**: - - Project overview and strategy - - Complete feature list - - Technical architecture - - Installation procedures - - Usage and operations - - Troubleshooting and support - -## Quick Reference by Topic - -### Installation & Setup -- **Getting Started**: [README.md](README.md) → [INSTALLATION_GUIDE.md](INSTALLATION_GUIDE.md) -- **Docker Setup**: [INSTALLATION_GUIDE.md](INSTALLATION_GUIDE.md#method-3-docker-container-deployment) -- **Git Hook Setup**: [INSTALLATION_GUIDE.md](INSTALLATION_GUIDE.md#git-repository-hook-installation) -- **Post-Installation**: [INSTALLATION_GUIDE.md](INSTALLATION_GUIDE.md#post-installation-configuration) - -### Operation & Troubleshooting -- **Starting Daemon**: [USAGE_GUIDE.md](USAGE_GUIDE.md#starting-and-managing-the-daemon) -- **Sending Notifications**: [USAGE_GUIDE.md](USAGE_GUIDE.md#sending-notifications) -- **Debugging Issues**: [USAGE_GUIDE.md](USAGE_GUIDE.md#monitoring-and-troubleshooting) -- **Performance Tuning**: [USAGE_GUIDE.md](USAGE_GUIDE.md#performance-tuning) - -### Features & Capabilities -- **Feature List**: [FEATURES.md](FEATURES.md) -- **VCS Support**: [FEATURES.md](FEATURES.md#1-multi-version-control-system-support) -- **Protocols**: [FEATURES.md](FEATURES.md#3-flexible-communication-protocols) -- **Advanced Features**: [FEATURES.md](FEATURES.md#advanced-features) - -### Technical Details -- **Architecture**: [TECHNOLOGY_STACK.md](TECHNOLOGY_STACK.md#architecture-components) -- **Performance**: [TECHNOLOGY_STACK.md](TECHNOLOGY_STACK.md#performance-characteristics) -- **Security**: [TECHNOLOGY_STACK.md](TECHNOLOGY_STACK.md#security-technologies) -- **System Requirements**: [TECHNOLOGY_STACK.md](TECHNOLOGY_STACK.md#system-requirements) - -### Project Information -- **Overview**: [PROJECT_OVERVIEW.md](PROJECT_OVERVIEW.md) -- **Use Cases**: [PROJECT_OVERVIEW.md](PROJECT_OVERVIEW.md#use-cases) -- **Roadmap**: [PROJECT_OVERVIEW.md](PROJECT_OVERVIEW.md#roadmap) - -## Document Relationships - -``` -README.md (Entry Point) -├─ Quick overview -├─ Links to: INSTALLATION_GUIDE.md, USAGE_GUIDE.md -└─ References: FEATURES.md, TECHNOLOGY_STACK.md - -PROJECT_OVERVIEW.md (Strategic View) -├─ What and why? -├─ References: README.md -└─ Links to: INSTALLATION_GUIDE.md, FEATURES.md - -FEATURES.md (Capabilities) -├─ What can it do? -├─ References: README.md -└─ Links to: USAGE_GUIDE.md, TECHNOLOGY_STACK.md - -TECHNOLOGY_STACK.md (Implementation) -├─ How is it built? -├─ References: README.md, FEATURES.md -└─ Links to: INSTALLATION_GUIDE.md - -INSTALLATION_GUIDE.md (Getting Started) -├─ How to install? -├─ References: README.md -└─ Links to: USAGE_GUIDE.md, POST_CONFIGURATION - -USAGE_GUIDE.md (Operations) -├─ How to use? -├─ References: INSTALLATION_GUIDE.md -└─ Links to: TROUBLESHOOTING -``` - -## Audience Guide - -### Decision Makers / Managers -1. Start: [PROJECT_OVERVIEW.md](PROJECT_OVERVIEW.md) -2. Then: [FEATURES.md](FEATURES.md#comparison-feature-matrix) -3. Reference: [README.md](README.md#advantages-over-alternatives) - -### Developers / System Administrators -1. Start: [README.md](README.md) -2. Then: [INSTALLATION_GUIDE.md](INSTALLATION_GUIDE.md) -3. Reference: [USAGE_GUIDE.md](USAGE_GUIDE.md), [TECHNOLOGY_STACK.md](TECHNOLOGY_STACK.md) - -### Operations / DevOps Teams -1. Start: [INSTALLATION_GUIDE.md](INSTALLATION_GUIDE.md#method-3-docker-container-deployment) -2. Then: [USAGE_GUIDE.md](USAGE_GUIDE.md#systemd-service-management) -3. Reference: [PROJECT_OVERVIEW.md](PROJECT_OVERVIEW.md#deployment-options) - -### Integrators / Developers Building on vext -1. Start: [TECHNOLOGY_STACK.md](TECHNOLOGY_STACK.md) -2. Then: [FEATURES.md](FEATURES.md#advanced-features) -3. Reference: [USAGE_GUIDE.md](USAGE_GUIDE.md#advanced-usage) - -## Getting Help - -### Common Questions - -**"What is vext?"** -→ Read [README.md](README.md) (Project Overview section) - -**"How do I install it?"** -→ Follow [INSTALLATION_GUIDE.md](INSTALLATION_GUIDE.md) - -**"How do I use it?"** -→ See [USAGE_GUIDE.md](USAGE_GUIDE.md#quick-start) - -**"Does it support my VCS?"** -→ Check [FEATURES.md](FEATURES.md#1-multi-version-control-system-support) - -**"What are the requirements?"** -→ Review [README.md](README.md#installation-requirements) - -**"How does it work?"** -→ Study [TECHNOLOGY_STACK.md](TECHNOLOGY_STACK.md#architecture-components) - -**"Can I customize it?"** -→ See [FEATURES.md](FEATURES.md#advanced-features) and [USAGE_GUIDE.md](USAGE_GUIDE.md#advanced-usage) - -**"What's the roadmap?"** -→ Check [PROJECT_OVERVIEW.md](PROJECT_OVERVIEW.md#roadmap) - -## Documentation Standards - -All documentation follows these standards: - -- **Markdown format** for GitHub/GitLab compatibility -- **Clear structure** with headers, sections, and subsections -- **Practical examples** for most features -- **Code blocks** with language specification -- **Tables** for comparisons and matrices -- **Links** between related documents -- **TOC-friendly** with descriptive headers -- **Accessible** to both technical and non-technical readers - -## Contributing to Documentation - -When adding new documentation: - -1. Follow the structure and style of existing documents -2. Add new files and update this index -3. Link to related documents using markdown links -4. Include practical examples where applicable -5. Update the file statistics above -6. Ensure markdown validates correctly - -## Version Information - -- **Documentation Version**: 1.0 -- **Last Updated**: 2025-11-22 -- **vext Version**: Rhodium Standard Edition -- **Related Project**: irker (by Eric S. Raymond) - -## License - -All documentation is provided under the same license as vext: **Eclipse Public License 2.0** - ---- - -**Start with [README.md](README.md) if you're new to vext!** - diff --git a/vext/FEATURES.adoc b/vext/FEATURES.adoc new file mode 100644 index 0000000..1aba5b4 --- /dev/null +++ b/vext/FEATURES.adoc @@ -0,0 +1,388 @@ +== vext Features + +=== Core Features + +==== 1. Multi-Version Control System Support + +vext integrates with three major version control systems through +intelligent hook detection: + +===== Git Support + +* *Integration Point*: `+post-receive+` hook (server-side) +* *Data Extracted*: +** Commit hash and abbreviated hash +** Author name and email +** Commit date and timezone +** Commit message (subject and body) +** Changed files and statistics (additions/deletions) +** Branch name and push information +* *Hook Invocation*: Triggered once per push (not per commit, for +efficiency) +* *Format Options*: Customizable message template + +===== Mercurial (Hg) Support + +* *Integration Points*: Python hooks or shell scripts +* *Data Extracted*: +** Changeset hash +** Author information +** Commit date +** Commit description +** Files modified/added/removed +* *Compatibility*: Python 2 and Python 3 (with caveats) +* *Trigger*: Post-commit hook per changeset + +===== Subversion (SVN) Support + +* *Integration Point*: `+post-commit+` hook +* *Data Extracted*: +** Revision number +** Author name +** Commit date +** Commit log message +** Changed paths summary +* *Requirements*: Repository path and revision number parameters +* *Invocation*: Once per committed transaction + +==== 2. Persistent Connection Management + +*Problem Solved*: Eliminates the "`join/leave spam`" problem + +* *Single Connection*: One IRC connection per channel maintained by +daemon +* *Connection Pooling*: Multiple channels share server connections +efficiently +* *Reconnection Logic*: Automatic reconnection on network failures +* *Connection Timeout*: Configurable idle timeout to prevent stale +connections +* *Resource Efficiency*: Reuses connections across hundreds of messages + +==== 3. Flexible Communication Protocols + +vext supports multiple transport methods for delivering notifications: + +===== TCP Mode + +[source,bash] +---- +# Reliable, ordered delivery +IRKERD_USE_TCP=true irkerd +---- + +* Guaranteed message delivery +* Ordered delivery +* Higher latency (~5-10ms vs UDP) +* Suitable for critical notifications + +===== UDP Mode (Default) + +[source,bash] +---- +# Fast, fire-and-forget +IRKERD_USE_TCP=false irkerd +---- + +* Lowest latency (<1ms) +* Lower bandwidth overhead +* Best effort delivery +* Suitable for high-volume scenarios + +===== Email Mode + +[source,bash] +---- +# Email-based notifications for offline access +IRKERD_EMAIL_ADDR=commits@example.com irkerd +---- + +* Sends notifications via SMTP +* Persistent offline record +* Suitable for compliance and audit trails +* Fallback for IRC unavailability + +==== 4. JSON-Based Protocol + +*Standardized Notification Format* + +[source,json] +---- +{ + "to": "irc://irc.libera.chat/commits", + "privmsg": "[abc123d] Alice: Implement new feature", + "nick": "myproject-bot", + "userinfo": "git@example.com", + "color": "ANSI" +} +---- + +*Key Advantages*: - Language-agnostic (any language can generate +notifications) - Easy to parse and validate - Extensible for custom +fields - Human-readable for debugging - Works across network boundaries + +==== 5. Multi-Channel Broadcasting + +Route single commits to multiple channels for different audiences: + +[source,json] +---- +{ + "to": [ + "irc://irc.libera.chat/commits", + "irc://irc.libera.chat/releases", + "irc://irc.libera.chat/developers" + ], + "privmsg": "[v1.2.0] Release: Version 1.2.0 shipped" +} +---- + +*Use Cases*: - Separate channels for different teams - Release +announcements in dedicated channels - Backup notification channels - +Multi-server notification + +==== 6. Color Formatting Support + +Enhance visibility with optional color codes: + +===== mIRC Color Mode + +[source,bash] +---- +export IRKERD_COLOR_MODE=mIRC +---- + +* Supports clients: mIRC, XChat, KVirc, Konversation, weechat +* Highlights commit hash, author, and message +* Backward compatible with non-color clients + +===== ANSI Color Mode + +[source,bash] +---- +export IRKERD_COLOR_MODE=ANSI +---- + +* Supports clients: Chatzilla, irssi, ircle, BitchX +* Unix/Linux terminal-friendly +* Better for modern IRC clients + +===== No Color Mode (Default) + +[source,bash] +---- +export IRKERD_COLOR_MODE=none +---- + +* Maximum compatibility +* Clean, plain text output +* Suitable for all clients + +==== 7. Configurable Notification Format + +Customize message appearance to match your team’s style: + +[source,python] +---- +# Example: Custom notification template +{ + "format": "[{hash}] {author}: {message} ({branch})", + "max_length": 512, + "truncation": "..." +} +---- + +*Customizable Elements*: - Author format (full name, email, username) - +Hash display (full, abbreviated) - Message truncation length - +Branch/tag display - File change statistics - URL generation for web +viewers + +==== 8. Rate Limiting and Flood Prevention + +Protect IRC servers from being overwhelmed: + +[source,bash] +---- +# Configuration +IRKERD_FLOOD_LIMIT=1000 # Max messages per minute +IRKERD_RATE_LIMIT=2 # Messages per second per channel +---- + +*Features*: - Per-channel rate limiting - Global burst protection - +Automatic queue management - Graceful degradation under load + +==== 9. Comprehensive Logging + +Built-in logging for monitoring and debugging: + +[source,bash] +---- +IRKERD_LOGFILE=/var/log/vext/vext.log +IRKERD_LOGLEVEL=INFO # DEBUG, INFO, WARNING, ERROR +---- + +*Log Includes*: - Connection events (connect, disconnect, error) - +Message sent/received - Configuration changes - Performance metrics - +Error stack traces + +==== 10. Flexible Routing + +Direct different commits to different channels based on criteria: + +[source,json] +---- +{ + "to": { + "main": "irc://irc.libera.chat/releases", + "dev": "irc://irc.libera.chat/commits", + "hotfix": "irc://irc.libera.chat/urgent" + }, + "route_by": "branch" +} +---- + +*Routing Options*: - Branch name matching - Author filtering - Commit +message patterns - File path patterns - Commit size thresholds + +==== 11. Performance Optimization + +Features designed for efficiency: + +* *Connection Multiplexing*: 1000+ channels per daemon +* *Message Batching*: Group rapid commits +* *Memory Pooling*: Efficient string and object reuse +* *Lazy Connection*: Channels connected only when needed +* *Cleanup*: Automatic removal of stale connections + +==== 12. Security Features + +Built-in security mechanisms: + +[source,bash] +---- +# Run as unprivileged user +sudo chown irker:irker /var/run/vext.pid +sudo systemctl start vext # Runs as 'irker' user + +# Restrict listener port +IRKERD_LISTEN=127.0.0.1 # Local-only access +---- + +*Security Measures*: - Unprivileged user execution - Input validation +and sanitization - Rate limiting against abuse - Optional TLS for IRC +connections - Configurable access controls + +=== Advanced Features + +==== 1. Extensible Hook System + +Modify notification behavior without changing core code: + +[source,python] +---- +# Custom hook for commit annotations +class CustomHook: + def enrich_notification(self, commit_data): + # Add custom fields + commit_data['ticket_url'] = extract_ticket_id(commit_data['message']) + return commit_data +---- + +==== 2. Metrics and Monitoring + +Export metrics for infrastructure monitoring: + +[source,bash] +---- +# Prometheus metrics endpoint +curl http://localhost:8888/metrics +---- + +*Available Metrics*: - Messages sent/received - Connection state - +Message queue depth - Error rates - Latency histograms + +==== 3. Web Administration Interface (Planned) + +Future version will include: + +* Real-time connection status dashboard +* Channel management UI +* Log viewer +* Statistics and graphs +* Configuration editor + +==== 4. Multi-Server Support + +Connect to multiple IRC servers simultaneously: + +[source,json] +---- +{ + "servers": [ + "irc://irc.libera.chat/commits", + "irc://irc.freenode.net/backup", + "irc://internal.corp.com/team" + ] +} +---- + +==== 5. Template-Based Formatting + +Professional, team-standard message formatting: + +[source,jinja2] +---- +# Template: default.jinja2 +[{{ commit.hash_short }}] {{ commit.author }}: {{ commit.subject }} +{% if commit.files_changed < 10 %} + Files: {{ commit.files_changed }} | +{{ commit.additions }}-{{ commit.deletions }} +{% endif %} +---- + +==== 6. Integration with CI/CD + +Trigger notifications from CI pipelines: + +[source,bash] +---- +# From CI job +curl -X POST http://localhost:6659/notify \ + -H "Content-Type: application/json" \ + -d '{"to":"irc://irc.libera.chat/builds","privmsg":"Build #42 passed"}' +---- + +=== Comparison: Feature Matrix + +[cols=",,,,",options="header",] +|=== +|Feature |vext |irker |Email |Slack +|Git support |✓ |✓ |✓ |✓ +|Hg support |✓ |✓ |✗ |✗ +|SVN support |✓ |✓ |✗ |✗ +|Multi-channel |✓ |✓ |✗ |✓ +|Color codes |✓ |✓ |✗ |✓ +|Rate limiting |✓ |Limited |✓ |✓ +|Logging |✓ |Basic |✓ |✓ +|TLS/SSL |✓ |✓ |✓ |✓ +|Custom formatting |✓ |Partial |✓ |✓ +|Metrics export |✓ |✗ |✗ |✓ +|Web UI |Planned |✗ |✗ |✓ +|No join/leave spam |✓ |✓ |N/A |N/A +|Self-hosted |✓ |✓ |✓ |✗ +|=== + +=== Feature Highlights + +==== Why Choose vext? + +[arabic] +. *Complete VCS Support*: Works with Git, Mercurial, and Subversion +. *Zero Join/Leave Spam*: Persistent connections eliminate channel noise +. *Lightweight*: Minimal resource usage suitable for any size +organization +. *Self-Hosted*: No external dependencies or cloud requirements +. *Well-Documented*: Comprehensive guides and examples +. *Modern Python*: Fully compatible with Python 3.6+ +. *Production-Ready*: Used in enterprise environments +. *Extensible*: Hook system allows customization +. *Monitored*: Logging and metrics for troubleshooting +. *Community-Driven*: Active maintenance and contributions diff --git a/vext/FEATURES.md b/vext/FEATURES.md deleted file mode 100644 index bea8d26..0000000 --- a/vext/FEATURES.md +++ /dev/null @@ -1,376 +0,0 @@ - -# vext Features - -## Core Features - -### 1. Multi-Version Control System Support - -vext integrates with three major version control systems through intelligent hook detection: - -#### Git Support -- **Integration Point**: `post-receive` hook (server-side) -- **Data Extracted**: - - Commit hash and abbreviated hash - - Author name and email - - Commit date and timezone - - Commit message (subject and body) - - Changed files and statistics (additions/deletions) - - Branch name and push information -- **Hook Invocation**: Triggered once per push (not per commit, for efficiency) -- **Format Options**: Customizable message template - -#### Mercurial (Hg) Support -- **Integration Points**: Python hooks or shell scripts -- **Data Extracted**: - - Changeset hash - - Author information - - Commit date - - Commit description - - Files modified/added/removed -- **Compatibility**: Python 2 and Python 3 (with caveats) -- **Trigger**: Post-commit hook per changeset - -#### Subversion (SVN) Support -- **Integration Point**: `post-commit` hook -- **Data Extracted**: - - Revision number - - Author name - - Commit date - - Commit log message - - Changed paths summary -- **Requirements**: Repository path and revision number parameters -- **Invocation**: Once per committed transaction - -### 2. Persistent Connection Management - -**Problem Solved**: Eliminates the "join/leave spam" problem - -- **Single Connection**: One IRC connection per channel maintained by daemon -- **Connection Pooling**: Multiple channels share server connections efficiently -- **Reconnection Logic**: Automatic reconnection on network failures -- **Connection Timeout**: Configurable idle timeout to prevent stale connections -- **Resource Efficiency**: Reuses connections across hundreds of messages - -### 3. Flexible Communication Protocols - -vext supports multiple transport methods for delivering notifications: - -#### TCP Mode -```bash -# Reliable, ordered delivery -IRKERD_USE_TCP=true irkerd -``` -- Guaranteed message delivery -- Ordered delivery -- Higher latency (~5-10ms vs UDP) -- Suitable for critical notifications - -#### UDP Mode (Default) -```bash -# Fast, fire-and-forget -IRKERD_USE_TCP=false irkerd -``` -- Lowest latency (<1ms) -- Lower bandwidth overhead -- Best effort delivery -- Suitable for high-volume scenarios - -#### Email Mode -```bash -# Email-based notifications for offline access -IRKERD_EMAIL_ADDR=commits@example.com irkerd -``` -- Sends notifications via SMTP -- Persistent offline record -- Suitable for compliance and audit trails -- Fallback for IRC unavailability - -### 4. JSON-Based Protocol - -**Standardized Notification Format** - -```json -{ - "to": "irc://irc.libera.chat/commits", - "privmsg": "[abc123d] Alice: Implement new feature", - "nick": "myproject-bot", - "userinfo": "git@example.com", - "color": "ANSI" -} -``` - -**Key Advantages**: -- Language-agnostic (any language can generate notifications) -- Easy to parse and validate -- Extensible for custom fields -- Human-readable for debugging -- Works across network boundaries - -### 5. Multi-Channel Broadcasting - -Route single commits to multiple channels for different audiences: - -```json -{ - "to": [ - "irc://irc.libera.chat/commits", - "irc://irc.libera.chat/releases", - "irc://irc.libera.chat/developers" - ], - "privmsg": "[v1.2.0] Release: Version 1.2.0 shipped" -} -``` - -**Use Cases**: -- Separate channels for different teams -- Release announcements in dedicated channels -- Backup notification channels -- Multi-server notification - -### 6. Color Formatting Support - -Enhance visibility with optional color codes: - -#### mIRC Color Mode -```bash -export IRKERD_COLOR_MODE=mIRC -``` -- Supports clients: mIRC, XChat, KVirc, Konversation, weechat -- Highlights commit hash, author, and message -- Backward compatible with non-color clients - -#### ANSI Color Mode -```bash -export IRKERD_COLOR_MODE=ANSI -``` -- Supports clients: Chatzilla, irssi, ircle, BitchX -- Unix/Linux terminal-friendly -- Better for modern IRC clients - -#### No Color Mode (Default) -```bash -export IRKERD_COLOR_MODE=none -``` -- Maximum compatibility -- Clean, plain text output -- Suitable for all clients - -### 7. Configurable Notification Format - -Customize message appearance to match your team's style: - -```python -# Example: Custom notification template -{ - "format": "[{hash}] {author}: {message} ({branch})", - "max_length": 512, - "truncation": "..." -} -``` - -**Customizable Elements**: -- Author format (full name, email, username) -- Hash display (full, abbreviated) -- Message truncation length -- Branch/tag display -- File change statistics -- URL generation for web viewers - -### 8. Rate Limiting and Flood Prevention - -Protect IRC servers from being overwhelmed: - -```bash -# Configuration -IRKERD_FLOOD_LIMIT=1000 # Max messages per minute -IRKERD_RATE_LIMIT=2 # Messages per second per channel -``` - -**Features**: -- Per-channel rate limiting -- Global burst protection -- Automatic queue management -- Graceful degradation under load - -### 9. Comprehensive Logging - -Built-in logging for monitoring and debugging: - -```bash -IRKERD_LOGFILE=/var/log/vext/vext.log -IRKERD_LOGLEVEL=INFO # DEBUG, INFO, WARNING, ERROR -``` - -**Log Includes**: -- Connection events (connect, disconnect, error) -- Message sent/received -- Configuration changes -- Performance metrics -- Error stack traces - -### 10. Flexible Routing - -Direct different commits to different channels based on criteria: - -```json -{ - "to": { - "main": "irc://irc.libera.chat/releases", - "dev": "irc://irc.libera.chat/commits", - "hotfix": "irc://irc.libera.chat/urgent" - }, - "route_by": "branch" -} -``` - -**Routing Options**: -- Branch name matching -- Author filtering -- Commit message patterns -- File path patterns -- Commit size thresholds - -### 11. Performance Optimization - -Features designed for efficiency: - -- **Connection Multiplexing**: 1000+ channels per daemon -- **Message Batching**: Group rapid commits -- **Memory Pooling**: Efficient string and object reuse -- **Lazy Connection**: Channels connected only when needed -- **Cleanup**: Automatic removal of stale connections - -### 12. Security Features - -Built-in security mechanisms: - -```bash -# Run as unprivileged user -sudo chown irker:irker /var/run/vext.pid -sudo systemctl start vext # Runs as 'irker' user - -# Restrict listener port -IRKERD_LISTEN=127.0.0.1 # Local-only access -``` - -**Security Measures**: -- Unprivileged user execution -- Input validation and sanitization -- Rate limiting against abuse -- Optional TLS for IRC connections -- Configurable access controls - -## Advanced Features - -### 1. Extensible Hook System - -Modify notification behavior without changing core code: - -```python -# Custom hook for commit annotations -class CustomHook: - def enrich_notification(self, commit_data): - # Add custom fields - commit_data['ticket_url'] = extract_ticket_id(commit_data['message']) - return commit_data -``` - -### 2. Metrics and Monitoring - -Export metrics for infrastructure monitoring: - -```bash -# Prometheus metrics endpoint -curl http://localhost:8888/metrics -``` - -**Available Metrics**: -- Messages sent/received -- Connection state -- Message queue depth -- Error rates -- Latency histograms - -### 3. Web Administration Interface (Planned) - -Future version will include: - -- Real-time connection status dashboard -- Channel management UI -- Log viewer -- Statistics and graphs -- Configuration editor - -### 4. Multi-Server Support - -Connect to multiple IRC servers simultaneously: - -```json -{ - "servers": [ - "irc://irc.libera.chat/commits", - "irc://irc.freenode.net/backup", - "irc://internal.corp.com/team" - ] -} -``` - -### 5. Template-Based Formatting - -Professional, team-standard message formatting: - -```jinja2 -# Template: default.jinja2 -[{{ commit.hash_short }}] {{ commit.author }}: {{ commit.subject }} -{% if commit.files_changed < 10 %} - Files: {{ commit.files_changed }} | +{{ commit.additions }}-{{ commit.deletions }} -{% endif %} -``` - -### 6. Integration with CI/CD - -Trigger notifications from CI pipelines: - -```bash -# From CI job -curl -X POST http://localhost:6659/notify \ - -H "Content-Type: application/json" \ - -d '{"to":"irc://irc.libera.chat/builds","privmsg":"Build #42 passed"}' -``` - -## Comparison: Feature Matrix - -| Feature | vext | irker | Email | Slack | -|---------|------|-------|-------|-------| -| Git support | ✓ | ✓ | ✓ | ✓ | -| Hg support | ✓ | ✓ | ✗ | ✗ | -| SVN support | ✓ | ✓ | ✗ | ✗ | -| Multi-channel | ✓ | ✓ | ✗ | ✓ | -| Color codes | ✓ | ✓ | ✗ | ✓ | -| Rate limiting | ✓ | Limited | ✓ | ✓ | -| Logging | ✓ | Basic | ✓ | ✓ | -| TLS/SSL | ✓ | ✓ | ✓ | ✓ | -| Custom formatting | ✓ | Partial | ✓ | ✓ | -| Metrics export | ✓ | ✗ | ✗ | ✓ | -| Web UI | Planned | ✗ | ✗ | ✓ | -| No join/leave spam | ✓ | ✓ | N/A | N/A | -| Self-hosted | ✓ | ✓ | ✓ | ✗ | - -## Feature Highlights - -### Why Choose vext? - -1. **Complete VCS Support**: Works with Git, Mercurial, and Subversion -2. **Zero Join/Leave Spam**: Persistent connections eliminate channel noise -3. **Lightweight**: Minimal resource usage suitable for any size organization -4. **Self-Hosted**: No external dependencies or cloud requirements -5. **Well-Documented**: Comprehensive guides and examples -6. **Modern Python**: Fully compatible with Python 3.6+ -7. **Production-Ready**: Used in enterprise environments -8. **Extensible**: Hook system allows customization -9. **Monitored**: Logging and metrics for troubleshooting -10. **Community-Driven**: Active maintenance and contributions - diff --git a/vext/INSTALLATION_GUIDE.md b/vext/INSTALLATION_GUIDE.adoc similarity index 78% rename from vext/INSTALLATION_GUIDE.md rename to vext/INSTALLATION_GUIDE.adoc index 8abc0ef..fc9ae70 100644 --- a/vext/INSTALLATION_GUIDE.md +++ b/vext/INSTALLATION_GUIDE.adoc @@ -1,22 +1,21 @@ - -# vext Installation Guide +== vext Installation Guide -## Prerequisites +=== Prerequisites -### System Requirements +==== System Requirements -- **Operating System**: Linux (Ubuntu, Debian, CentOS), macOS, or FreeBSD -- **Python**: Version 2.7+ or 3.4+ (3.6+ recommended) -- **Version Control Tools**: Git, Mercurial (optional), or Subversion (optional) -- **Network**: Outbound TCP/UDP access to IRC server -- **User Privileges**: Ability to create system users and install to `/usr/local` or `/opt` +* *Operating System*: Linux (Ubuntu, Debian, CentOS), macOS, or FreeBSD +* *Python*: Version 2.7+ or 3.4+ (3.6+ recommended) +* *Version Control Tools*: Git, Mercurial (optional), or Subversion +(optional) +* *Network*: Outbound TCP/UDP access to IRC server +* *User Privileges*: Ability to create system users and install to +`+/usr/local+` or `+/opt+` -### Required Tools +==== Required Tools -```bash +[source,bash] +---- # Check Python installation python --version # Should show 2.7+ or 3.4+ python3 --version # For Python 3 @@ -27,31 +26,34 @@ git --version # Optional: Check other VCS tools hg --version # For Mercurial support svn --version # For Subversion support -``` +---- -### Network Requirements +==== Network Requirements -- **Outbound**: TCP/UDP port 6667-6697 (IRC servers, 6697 is typically TLS) -- **Inbound**: TCP/UDP port 6659 (daemon listener, configurable) -- **DNS**: Access to IRC server DNS records -- **Firewall**: Allow bidirectional traffic with IRC servers +* *Outbound*: TCP/UDP port 6667-6697 (IRC servers, 6697 is typically +TLS) +* *Inbound*: TCP/UDP port 6659 (daemon listener, configurable) +* *DNS*: Access to IRC server DNS records +* *Firewall*: Allow bidirectional traffic with IRC servers -## Installation Methods +=== Installation Methods -### Method 1: From Source (Recommended for Development) +==== Method 1: From Source (Recommended for Development) -#### Step 1: Clone Repository +===== Step 1: Clone Repository -```bash +[source,bash] +---- # Clone the vext repository git clone https://github.com/Hyperpolymath/vext.git cd vext git checkout main # or latest stable branch -``` +---- -#### Step 2: Create Virtual Environment (Optional but Recommended) +===== Step 2: Create Virtual Environment (Optional but Recommended) -```bash +[source,bash] +---- # Create isolated Python environment python3 -m venv venv source venv/bin/activate # On macOS/Linux @@ -60,21 +62,23 @@ venv\Scripts\activate # On Windows # Upgrade pip pip install --upgrade pip setuptools wheel -``` +---- -#### Step 3: Install Dependencies +===== Step 3: Install Dependencies -```bash +[source,bash] +---- # Install package and dependencies pip install -e . # Or with development dependencies pip install -e ".[dev,test]" -``` +---- -#### Step 4: Verify Installation +===== Step 4: Verify Installation -```bash +[source,bash] +---- # Check daemon installation irkerd --help @@ -83,22 +87,24 @@ python -m irker.irkerhook --help # Test import python -c "import irker; print(irker.__version__)" -``` +---- -#### Step 5: Create System User (Recommended) +===== Step 5: Create System User (Recommended) -```bash +[source,bash] +---- # Create unprivileged user for daemon sudo useradd -r -s /bin/false -d /var/empty irker # Or on macOS sudo dscl . -create /Users/irker UserShell /usr/bin/false sudo dscl . -create /Users/irker RealName "IRC Notification Daemon" -``` +---- -#### Step 6: Install as System Service +===== Step 6: Install as System Service -```bash +[source,bash] +---- # Copy systemd service file sudo cp systemd/vext.service /etc/systemd/system/ @@ -127,13 +133,14 @@ sudo systemctl daemon-reload sudo systemctl enable vext sudo systemctl start vext sudo systemctl status vext -``` +---- -### Method 2: Package Manager Installation +==== Method 2: Package Manager Installation -#### Ubuntu/Debian +===== Ubuntu/Debian -```bash +[source,bash] +---- # Update package list sudo apt-get update @@ -145,11 +152,12 @@ sudo apt-get install python3-dev git git clone https://github.com/Hyperpolymath/vext.git cd vext sudo python3 setup.py install -``` +---- -#### CentOS/RHEL +===== CentOS/RHEL -```bash +[source,bash] +---- # Install dependencies sudo yum install python36-devel git @@ -157,11 +165,12 @@ sudo yum install python36-devel git git clone https://github.com/Hyperpolymath/vext.git cd vext sudo python36 setup.py install -``` +---- -#### macOS (Homebrew) +===== macOS (Homebrew) -```bash +[source,bash] +---- # If formula is available brew install vext @@ -170,13 +179,14 @@ brew install python3 git clone https://github.com/Hyperpolymath/vext.git cd vext pip3 install -e . -``` +---- -### Method 3: Docker Container Deployment +==== Method 3: Docker Container Deployment -#### Create Dockerfile +===== Create Dockerfile -```dockerfile +[source,dockerfile] +---- FROM python:3.9-slim # Install dependencies @@ -202,11 +212,12 @@ EXPOSE 6659 # Run daemon CMD ["irkerd", "--listen", "0.0.0.0", "--port", "6659"] -``` +---- -#### Build and Run +===== Build and Run -```bash +[source,bash] +---- # Build image docker build -t vext:latest . @@ -223,21 +234,23 @@ docker logs -f vext-daemon # Stop container docker stop vext-daemon -``` +---- -### Method 4: System-Wide Installation (Manual) +==== Method 4: System-Wide Installation (Manual) -#### Step 1: Create Installation Directory +===== Step 1: Create Installation Directory -```bash +[source,bash] +---- # Create install directory sudo mkdir -p /opt/vext/{bin,lib,etc} sudo chown root:root /opt/vext -``` +---- -#### Step 2: Copy Files +===== Step 2: Copy Files -```bash +[source,bash] +---- # Copy daemon and scripts sudo cp irkerd /opt/vext/bin/ sudo cp irkerhook.py /opt/vext/bin/ @@ -247,21 +260,23 @@ sudo cp -r irker/ /opt/vext/lib/ sudo cp etc/vext.conf /opt/vext/etc/ sudo chmod 640 /opt/vext/etc/vext.conf sudo chown root:irker /opt/vext/etc/vext.conf -``` +---- -#### Step 3: Create Symlinks +===== Step 3: Create Symlinks -```bash +[source,bash] +---- # Link executables to standard locations sudo ln -s /opt/vext/bin/irkerd /usr/local/bin/irkerd sudo ln -s /opt/vext/bin/irkerhook.py /usr/local/bin/irkerhook -``` +---- -## Post-Installation Configuration +=== Post-Installation Configuration -### 1. Create Configuration File +==== 1. Create Configuration File -```bash +[source,bash] +---- # Create vext configuration directory sudo mkdir -p /etc/vext sudo chown root:root /etc/vext @@ -299,11 +314,12 @@ flood_limit = 1000 EOF sudo chmod 640 /etc/vext/vext.conf -``` +---- -### 2. Create Log Directory +==== 2. Create Log Directory -```bash +[source,bash] +---- # Create log directory sudo mkdir -p /var/log/vext sudo chown irker:irker /var/log/vext @@ -324,11 +340,12 @@ sudo tee /etc/logrotate.d/vext > /dev/null <<'EOF' endscript } EOF -``` +---- -### 3. Configure Environment Variables +==== 3. Configure Environment Variables -```bash +[source,bash] +---- # Create environment file sudo tee /etc/default/vext > /dev/null <<'EOF' # vext daemon environment configuration @@ -348,15 +365,16 @@ ExecStart=/usr/local/bin/irkerd --listen $IRKERD_HOST --port $IRKERD_PORT EOF sudo systemctl daemon-reload -``` +---- -## Repository-Specific Setup +=== Repository-Specific Setup -### Git Repository Hook Installation +==== Git Repository Hook Installation -#### Method 1: Server-Side Post-Receive Hook +===== Method 1: Server-Side Post-Receive Hook -```bash +[source,bash] +---- # Navigate to bare repository cd /path/to/myproject.git @@ -447,11 +465,12 @@ chmod +x hooks/post-receive # Verify ls -la hooks/post-receive -``` +---- -#### Method 2: Using irkerhook.py +===== Method 2: Using irkerhook.py -```bash +[source,bash] +---- # Copy irkerhook.py to repository cp /usr/local/bin/irkerhook /path/to/myproject.git/hooks/ @@ -461,11 +480,12 @@ chmod +x /path/to/myproject.git/hooks/irkerhook # Test the hook cd /path/to/myproject.git python hooks/irkerhook --help -``` +---- -### Mercurial Repository Hook Installation +==== Mercurial Repository Hook Installation -```bash +[source,bash] +---- # Add to .hg/hgrc cat >> /path/to/myrepo/.hg/hgrc << 'EOF' [hooks] @@ -478,11 +498,12 @@ EOF # Verify hg logs -``` +---- -### Subversion Repository Hook Installation +==== Subversion Repository Hook Installation -```bash +[source,bash] +---- # Create hook script cat > /path/to/svnrepo/hooks/post-commit << 'EOF' #!/bin/bash @@ -501,13 +522,14 @@ chmod +x /path/to/svnrepo/hooks/post-commit # Verify permissions ls -la /path/to/svnrepo/hooks/post-commit -``` +---- -## Testing Installation +=== Testing Installation -### 1. Verify Daemon Installation +==== 1. Verify Daemon Installation -```bash +[source,bash] +---- # Check daemon is executable which irkerd irkerd --version @@ -518,11 +540,12 @@ irkerd --foreground --debug & DAEMON_PID=$! sleep 2 kill $DAEMON_PID -``` +---- -### 2. Test Daemon Connectivity +==== 2. Test Daemon Connectivity -```bash +[source,bash] +---- # Start daemon irkerd --listen 127.0.0.1 --port 6659 --foreground & @@ -533,11 +556,12 @@ echo '{"to":"irc://irc.libera.chat/test","privmsg":"Hello from vext"}' | \ # Or with TCP echo '{"to":"irc://irc.libera.chat/test","privmsg":"Hello from vext"}' | \ nc 127.0.0.1 6659 -``` +---- -### 3. Test Hook Execution +==== 3. Test Hook Execution -```bash +[source,bash] +---- # Create test commit in Git repo cd /tmp mkdir test-repo @@ -558,11 +582,12 @@ chmod +x .git/hooks/post-receive echo "test" > testfile.txt git add testfile.txt git commit -m "Test commit" -``` +---- -### 4. System Service Testing +==== 4. System Service Testing -```bash +[source,bash] +---- # Check service status sudo systemctl status vext @@ -577,11 +602,12 @@ sudo systemctl status vext sudo netstat -tlnp | grep 6659 # or sudo ss -tlnp | grep 6659 -``` +---- -### 5. End-to-End Testing +==== 5. End-to-End Testing -```bash +[source,bash] +---- # 1. Start daemon sudo systemctl start vext @@ -607,31 +633,34 @@ EOTEST # 3. Check daemon logs sudo journalctl -u vext -n 20 -``` +---- -## Troubleshooting Installation +=== Troubleshooting Installation -### Issue: Python Version Mismatch +==== Issue: Python Version Mismatch -```bash +[source,bash] +---- # Solution: Use explicit Python version python3 setup.py install # or specify shebang in hook scripts #!/usr/bin/env python3 -``` +---- -### Issue: Permission Denied Errors +==== Issue: Permission Denied Errors -```bash +[source,bash] +---- # Solution: Fix file permissions sudo chown -R irker:irker /var/log/vext sudo chmod 755 /var/log/vext sudo chmod 644 /var/log/vext/*.log -``` +---- -### Issue: Port Already in Use +==== Issue: Port Already in Use -```bash +[source,bash] +---- # Find process using port 6659 sudo lsof -i :6659 # or @@ -640,11 +669,12 @@ sudo ss -tlnp | grep 6659 # Change daemon port in systemd service sudo systemctl edit vext # Add: Environment="IRKERD_PORT=6660" -``` +---- -### Issue: Cannot Connect to IRC Server +==== Issue: Cannot Connect to IRC Server -```bash +[source,bash] +---- # Test network connectivity ping irc.libera.chat telnet irc.libera.chat 6667 @@ -655,11 +685,12 @@ sudo ufw status # Enable outbound IRC ports sudo ufw allow out 6667,6697/tcp -``` +---- -### Issue: Daemon Not Starting +==== Issue: Daemon Not Starting -```bash +[source,bash] +---- # Check for syntax errors python3 -m py_compile /usr/local/bin/irkerd @@ -668,11 +699,12 @@ irkerd --foreground --debug # Check systemd logs sudo journalctl -u vext -n 50 -``` +---- -## Uninstallation +=== Uninstallation -```bash +[source,bash] +---- # Stop service sudo systemctl stop vext sudo systemctl disable vext @@ -694,12 +726,10 @@ sudo rm -rf /var/log/vext # Remove user sudo userdel irker sudo groupdel irker -``` +---- -## Next Steps - -After installation, see: -- [USAGE_GUIDE.md](USAGE_GUIDE.md) for operating vext -- [CONFIGURATION.md](CONFIGURATION.md) for detailed configuration options -- [README.md](README.md) for project overview +=== Next Steps +After installation, see: - USAGE_GUIDE.md for operating vext - +CONFIGURATION.md for detailed configuration options - README.md for +project overview diff --git a/vext/MAINTAINERS.adoc b/vext/MAINTAINERS.adoc index aa23a55..3246b7e 100644 --- a/vext/MAINTAINERS.adoc +++ b/vext/MAINTAINERS.adoc @@ -1,48 +1,296 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +**SPDX-License-Identifier: CC-BY-SA-4.0 -== Current Maintainers +This document lists the maintainers of the vext project and their areas +of responsibility. -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +=== 🏛️ Governance Model -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] -|=== +vext uses the *Tri-Perimeter Contribution Framework (TPCF)*, a graduated +trust model that balances security with openness. See +governance/PROJECT_GOVERNANCE.md for full details. -== Responsibilities +==== Perimeter 1: Core Maintainers -Maintainers are responsible for: +*Responsibilities*: Architecture decisions, security reviews, release +management, strategic direction -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +==== Perimeter 2: Active Contributors -== Becoming a Maintainer +*Responsibilities*: Code review, issue triage, documentation, community +support -Contributors who demonstrate: +==== Perimeter 3: Community -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +*Responsibilities*: Contributions, testing, feedback, bug reports -May be invited to become maintainers at the discretion of existing maintainers. +=== 👥 Core Maintainers (Perimeter 1) -== Decision Making +==== Lead Maintainer -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +*Name*: [Primary Maintainer] - *Email*: lead@vext.dev - *GitHub*: +@maintainer - *GitLab*: @maintainer - *Areas*: Overall project +direction, releases, security - *Timezone*: UTC-5 (EST/EDT) - *Active +Since*: 2025-01 -== Contact +==== Core Team -For questions about project governance, open an issue or contact the maintainers listed above. +*Name*: [Core Developer 1] - *Email*: dev1@vext.dev - *GitHub*: @dev1 - +*GitLab*: @dev1 - *Areas*: IRC protocol implementation, network layer - +*Timezone*: UTC+0 (GMT) - *Active Since*: 2025-01 + +*Name*: [Core Developer 2] - *Email*: dev2@vext.dev - *GitHub*: @dev2 - +*GitLab*: @dev2 - *Areas*: Build systems, CI/CD, release automation - +*Timezone*: UTC+8 (CST) - *Active Since*: 2025-01 + +=== 🌟 Active Contributors (Perimeter 2) + +Active contributors have demonstrated consistent, quality contributions +and assist with: - Code review - Issue triage - Documentation +improvements - Community support + +*Name*: [Contributor 1] - *GitHub*: @contributor1 - *Areas*: +Documentation, user support - *Active Since*: 2025-01 + +*Name*: [Contributor 2] - *GitHub*: @contributor2 - *Areas*: Testing, +quality assurance - *Active Since*: 2025-01 + +=== 📋 Areas of Responsibility + +==== IRC Protocol & Network Layer + +*Lead*: [Core Developer 1] - IRC RFC 1459 implementation - Connection +management - Protocol extensions (TLS, SASL) + +*Reviewers*: @dev1, @lead + +==== Configuration & CLI + +*Lead*: [Core Developer 2] - Command-line interface - Configuration file +parsing - Daemon management + +*Reviewers*: @dev2, @lead + +==== VCS Integrations + +*Lead*: [Core Developer 1] - Git hooks - Mercurial integration - +Subversion support + +*Reviewers*: @dev1, @contributor1 + +==== Build & Release + +*Lead*: [Core Developer 2] - Justfile, Makefile - Nix flakes - CI/CD +pipelines - Release process + +*Reviewers*: @dev2, @lead + +==== Documentation + +*Lead*: [Contributor 1] - README, guides, tutorials - API documentation +- Examples and recipes + +*Reviewers*: @contributor1, @dev2 + +==== Security + +*Lead*: link:#lead-maintainer[Lead Maintainer] - Security reviews - +Vulnerability assessment - Security advisories + +*Reviewers*: @lead, @dev1 (security team only) + +==== Community & Support + +*Lead*: [Contributor 1] - Issue triage - Discussion moderation - User +support + +*Reviewers*: @contributor1, @contributor2 + +=== 🔐 Security Team + +The security team handles confidential security issues: + +* *Lead*: link:#lead-maintainer[Lead Maintainer] (lead@vext.dev) +* *Members*: [Core Developer 1] (dev1@vext.dev) +* *Contact*: security@vext.dev +* *PGP Keys*: See `+.well-known/security.txt+` + +See SECURITY.md for vulnerability disclosure process. + +=== 🗳️ Decision Making + +==== Minor Decisions + +* *Who*: Any core maintainer +* *Process*: Direct commit or self-merge PR +* *Examples*: Bug fixes, documentation updates, small refactors + +==== Major Decisions + +* *Who*: Consensus among core maintainers +* *Process*: RFC (Request for Comments) in issues/discussions +* *Examples*: Architecture changes, new features, breaking changes +* *Timeline*: Minimum 7 days for community feedback + +==== Critical Decisions + +* *Who*: All core maintainers must agree +* *Process*: Formal vote with public record +* *Examples*: License changes, governance changes, repository transfers +* *Timeline*: Minimum 30 days for community feedback + +==== Voting Process + +[arabic] +. *Proposal*: Create RFC with detailed rationale +. *Discussion*: Community feedback period (7-30 days) +. *Vote*: Core maintainers vote (+1, 0, -1) +. *Resolution*: +* Major: 2/3 majority +* Critical: Unanimous +. *Record*: Document decision and rationale + +==== Conflict Resolution + +If consensus cannot be reached: 1. *Mediation*: Uninvolved maintainer +mediates 2. *Vote*: Formal vote if mediation fails 3. *Escalation*: +Community vote for governance changes + +=== 🚀 Release Process + +==== Release Managers + +* *Primary*: link:#lead-maintainer[Lead Maintainer] +* *Backup*: [Core Developer 2] + +==== Release Schedule + +* *Major* (X.0.0): Annually or as needed +* *Minor* (x.Y.0): Quarterly (Jan, Apr, Jul, Oct) +* *Patch* (x.y.Z): As needed for bug fixes +* *Security*: Immediately upon fix availability + +==== Release Checklist + +[arabic] +. All tests pass +. Documentation updated +. CHANGELOG.md updated +. Version numbers bumped +. Security review completed +. Release notes prepared +. Tagged and signed with GPG +. Uploaded to package repositories +. Announced to community + +See `+docs/release/RELEASE_PROCESS.md+` for detailed steps. + +=== 🎓 Becoming a Maintainer + +==== Path to Perimeter 2 (Active Contributor) + +*Requirements*: - 5+ merged pull requests - Consistent quality +contributions - Understanding of codebase and architecture - Adherence +to Code of Conduct - Active for 3+ months + +*Process*: 1. Express interest to existing maintainers 2. Current +maintainers discuss and vote 3. Invitation extended if consensus reached +4. Onboarding and mentorship period + +==== Path to Perimeter 1 (Core Maintainer) + +*Requirements*: - All Perimeter 2 requirements - Deep expertise in +project domain - Strong architectural judgment - Proven leadership and +mentorship - Consistent contributions for 6+ months - Endorsement by 2+ +current core maintainers + +*Process*: 1. Nomination by existing core maintainer 2. Discussion among +core team 3. Unanimous approval required 4. Public announcement 5. +Access granted incrementally + +=== 📤 Stepping Down + +Maintainers may step down voluntarily: + +[arabic] +. *Announce* intent to step down (minimum 2 weeks notice) +. *Transfer* responsibilities to other maintainers +. *Document* ongoing work and context +. *Update* this document +. *Retain* emeritus status if desired + +==== Emeritus Maintainers + +Former maintainers who retain advisory role: - Listed in CONTRIBUTORS.md +- May be consulted on major decisions - Retain community respect and +recognition + +=== 🔄 Inactive Maintainers + +If a maintainer is inactive for 6+ months without notice: 1. Attempt to +contact via multiple channels 2. If no response after 30 days, mark as +inactive 3. Redistribute responsibilities 4. Offer emeritus status 5. +Remove write access (can be restored upon return) + +=== 📊 Maintainer Statistics + +*Current Team Size*: - Perimeter 1 (Core): 3 maintainers - Perimeter 2 +(Active): 2 contributors - Perimeter 3 (Community): Open to all + +*Geographic Distribution*: - Americas: 1 - Europe: 1 - Asia: 1 + +*Timezone Coverage*: 24-hour coverage across all timezones + +=== 📞 Contacting Maintainers + +==== General Inquiries + +* *Email*: maintainers@vext.dev +* *Matrix*: #vext-dev:matrix.org +* *Discussions*: GitHub/GitLab discussions + +==== Specific Areas + +* *Security*: security@vext.dev +* *Releases*: release@vext.dev +* *Governance*: governance@vext.dev + +==== Individual Contact + +Contact individual maintainers for their specific areas of +responsibility. See email addresses above. + +=== 🙏 Acknowledgments + +We thank all maintainers, past and present, for their contributions: + +* *Current Maintainers*: See lists above +* *Emeritus Maintainers*: Listed in CONTRIBUTORS.md +* *All Contributors*: Listed in CONTRIBUTORS.md + +=== 📄 Historical Context + +==== Original Project + +vext is a Rhodium Standard Edition fork of *irker* by Eric S. Raymond: - +Original repository: https://gitlab.com/esr/irker - Original author: +Eric S. Raymond (esr) - Fork date: 2025-01-01 - Fork rationale: +Modernization, active maintenance, comprehensive documentation + +We acknowledge and thank Eric S. Raymond for creating irker and +releasing it under an open source license. + +=== 📝 Document History + +* *2025-01-01*: Initial version for vext fork +* *Version*: 1.0 +* *Next Review*: 2025-04-01 + +''''' + +*This document is maintained by*: link:#lead-maintainer[Lead Maintainer] +*Last Updated*: 2025-01-01 + +For questions about governance, see governance/PROJECT_GOVERNANCE.md. +For questions about contributing, see CONTRIBUTING.md. diff --git a/vext/MAINTAINERS.md b/vext/MAINTAINERS.md deleted file mode 100644 index 9855358..0000000 --- a/vext/MAINTAINERS.md +++ /dev/null @@ -1,318 +0,0 @@ - -# Maintainers - -**SPDX-License-Identifier: CC-BY-SA-4.0 - -This document lists the maintainers of the vext project and their areas of responsibility. - -## 🏛️ Governance Model - -vext uses the **Tri-Perimeter Contribution Framework (TPCF)**, a graduated trust model that balances security with openness. See [governance/PROJECT_GOVERNANCE.md](governance/PROJECT_GOVERNANCE.md) for full details. - -### Perimeter 1: Core Maintainers -**Responsibilities**: Architecture decisions, security reviews, release management, strategic direction - -### Perimeter 2: Active Contributors -**Responsibilities**: Code review, issue triage, documentation, community support - -### Perimeter 3: Community -**Responsibilities**: Contributions, testing, feedback, bug reports - -## 👥 Core Maintainers (Perimeter 1) - -### Lead Maintainer - -**Name**: [Primary Maintainer] -- **Email**: lead@vext.dev -- **GitHub**: @maintainer -- **GitLab**: @maintainer -- **Areas**: Overall project direction, releases, security -- **Timezone**: UTC-5 (EST/EDT) -- **Active Since**: 2025-01 - -### Core Team - -**Name**: [Core Developer 1] -- **Email**: dev1@vext.dev -- **GitHub**: @dev1 -- **GitLab**: @dev1 -- **Areas**: IRC protocol implementation, network layer -- **Timezone**: UTC+0 (GMT) -- **Active Since**: 2025-01 - -**Name**: [Core Developer 2] -- **Email**: dev2@vext.dev -- **GitHub**: @dev2 -- **GitLab**: @dev2 -- **Areas**: Build systems, CI/CD, release automation -- **Timezone**: UTC+8 (CST) -- **Active Since**: 2025-01 - -## 🌟 Active Contributors (Perimeter 2) - -Active contributors have demonstrated consistent, quality contributions and assist with: -- Code review -- Issue triage -- Documentation improvements -- Community support - -**Name**: [Contributor 1] -- **GitHub**: @contributor1 -- **Areas**: Documentation, user support -- **Active Since**: 2025-01 - -**Name**: [Contributor 2] -- **GitHub**: @contributor2 -- **Areas**: Testing, quality assurance -- **Active Since**: 2025-01 - -## 📋 Areas of Responsibility - -### IRC Protocol & Network Layer -**Lead**: [Core Developer 1] -- IRC RFC 1459 implementation -- Connection management -- Protocol extensions (TLS, SASL) - -**Reviewers**: @dev1, @lead - -### Configuration & CLI -**Lead**: [Core Developer 2] -- Command-line interface -- Configuration file parsing -- Daemon management - -**Reviewers**: @dev2, @lead - -### VCS Integrations -**Lead**: [Core Developer 1] -- Git hooks -- Mercurial integration -- Subversion support - -**Reviewers**: @dev1, @contributor1 - -### Build & Release -**Lead**: [Core Developer 2] -- Justfile, Makefile -- Nix flakes -- CI/CD pipelines -- Release process - -**Reviewers**: @dev2, @lead - -### Documentation -**Lead**: [Contributor 1] -- README, guides, tutorials -- API documentation -- Examples and recipes - -**Reviewers**: @contributor1, @dev2 - -### Security -**Lead**: [Lead Maintainer] -- Security reviews -- Vulnerability assessment -- Security advisories - -**Reviewers**: @lead, @dev1 (security team only) - -### Community & Support -**Lead**: [Contributor 1] -- Issue triage -- Discussion moderation -- User support - -**Reviewers**: @contributor1, @contributor2 - -## 🔐 Security Team - -The security team handles confidential security issues: - -- **Lead**: [Lead Maintainer] (lead@vext.dev) -- **Members**: [Core Developer 1] (dev1@vext.dev) -- **Contact**: security@vext.dev -- **PGP Keys**: See `.well-known/security.txt` - -See [SECURITY.md](SECURITY.md) for vulnerability disclosure process. - -## 🗳️ Decision Making - -### Minor Decisions -- **Who**: Any core maintainer -- **Process**: Direct commit or self-merge PR -- **Examples**: Bug fixes, documentation updates, small refactors - -### Major Decisions -- **Who**: Consensus among core maintainers -- **Process**: RFC (Request for Comments) in issues/discussions -- **Examples**: Architecture changes, new features, breaking changes -- **Timeline**: Minimum 7 days for community feedback - -### Critical Decisions -- **Who**: All core maintainers must agree -- **Process**: Formal vote with public record -- **Examples**: License changes, governance changes, repository transfers -- **Timeline**: Minimum 30 days for community feedback - -### Voting Process -1. **Proposal**: Create RFC with detailed rationale -2. **Discussion**: Community feedback period (7-30 days) -3. **Vote**: Core maintainers vote (+1, 0, -1) -4. **Resolution**: - - Major: 2/3 majority - - Critical: Unanimous -5. **Record**: Document decision and rationale - -### Conflict Resolution -If consensus cannot be reached: -1. **Mediation**: Uninvolved maintainer mediates -2. **Vote**: Formal vote if mediation fails -3. **Escalation**: Community vote for governance changes - -## 🚀 Release Process - -### Release Managers -- **Primary**: [Lead Maintainer] -- **Backup**: [Core Developer 2] - -### Release Schedule -- **Major** (X.0.0): Annually or as needed -- **Minor** (x.Y.0): Quarterly (Jan, Apr, Jul, Oct) -- **Patch** (x.y.Z): As needed for bug fixes -- **Security**: Immediately upon fix availability - -### Release Checklist -1. All tests pass -2. Documentation updated -3. CHANGELOG.md updated -4. Version numbers bumped -5. Security review completed -6. Release notes prepared -7. Tagged and signed with GPG -8. Uploaded to package repositories -9. Announced to community - -See `docs/release/RELEASE_PROCESS.md` for detailed steps. - -## 🎓 Becoming a Maintainer - -### Path to Perimeter 2 (Active Contributor) -**Requirements**: -- 5+ merged pull requests -- Consistent quality contributions -- Understanding of codebase and architecture -- Adherence to Code of Conduct -- Active for 3+ months - -**Process**: -1. Express interest to existing maintainers -2. Current maintainers discuss and vote -3. Invitation extended if consensus reached -4. Onboarding and mentorship period - -### Path to Perimeter 1 (Core Maintainer) -**Requirements**: -- All Perimeter 2 requirements -- Deep expertise in project domain -- Strong architectural judgment -- Proven leadership and mentorship -- Consistent contributions for 6+ months -- Endorsement by 2+ current core maintainers - -**Process**: -1. Nomination by existing core maintainer -2. Discussion among core team -3. Unanimous approval required -4. Public announcement -5. Access granted incrementally - -## 📤 Stepping Down - -Maintainers may step down voluntarily: - -1. **Announce** intent to step down (minimum 2 weeks notice) -2. **Transfer** responsibilities to other maintainers -3. **Document** ongoing work and context -4. **Update** this document -5. **Retain** emeritus status if desired - -### Emeritus Maintainers -Former maintainers who retain advisory role: -- Listed in CONTRIBUTORS.md -- May be consulted on major decisions -- Retain community respect and recognition - -## 🔄 Inactive Maintainers - -If a maintainer is inactive for 6+ months without notice: -1. Attempt to contact via multiple channels -2. If no response after 30 days, mark as inactive -3. Redistribute responsibilities -4. Offer emeritus status -5. Remove write access (can be restored upon return) - -## 📊 Maintainer Statistics - -**Current Team Size**: -- Perimeter 1 (Core): 3 maintainers -- Perimeter 2 (Active): 2 contributors -- Perimeter 3 (Community): Open to all - -**Geographic Distribution**: -- Americas: 1 -- Europe: 1 -- Asia: 1 - -**Timezone Coverage**: 24-hour coverage across all timezones - -## 📞 Contacting Maintainers - -### General Inquiries -- **Email**: maintainers@vext.dev -- **Matrix**: #vext-dev:matrix.org -- **Discussions**: GitHub/GitLab discussions - -### Specific Areas -- **Security**: security@vext.dev -- **Releases**: release@vext.dev -- **Governance**: governance@vext.dev - -### Individual Contact -Contact individual maintainers for their specific areas of responsibility. See email addresses above. - -## 🙏 Acknowledgments - -We thank all maintainers, past and present, for their contributions: - -- **Current Maintainers**: See lists above -- **Emeritus Maintainers**: Listed in CONTRIBUTORS.md -- **All Contributors**: Listed in CONTRIBUTORS.md - -## 📄 Historical Context - -### Original Project -vext is a Rhodium Standard Edition fork of **irker** by Eric S. Raymond: -- Original repository: https://gitlab.com/esr/irker -- Original author: Eric S. Raymond (esr) -- Fork date: 2025-01-01 -- Fork rationale: Modernization, active maintenance, comprehensive documentation - -We acknowledge and thank Eric S. Raymond for creating irker and releasing it under an open source license. - -## 📝 Document History - -- **2025-01-01**: Initial version for vext fork -- **Version**: 1.0 -- **Next Review**: 2025-04-01 - ---- - -**This document is maintained by**: [Lead Maintainer] -**Last Updated**: 2025-01-01 - -For questions about governance, see [governance/PROJECT_GOVERNANCE.md](governance/PROJECT_GOVERNANCE.md). -For questions about contributing, see [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/vext/PROJECT_OVERVIEW.adoc b/vext/PROJECT_OVERVIEW.adoc new file mode 100644 index 0000000..2b75427 --- /dev/null +++ b/vext/PROJECT_OVERVIEW.adoc @@ -0,0 +1,248 @@ +== vext Project Overview + +=== Executive Summary + +*vext* (Rhodium Standard Edition) is a modernized, well-maintained fork +of the irker IRC notification daemon. It provides real-time commit +notifications from version control systems (Git, Mercurial, Subversion) +to IRC channels with minimal resource overhead and no join/leave +connection spam. + +=== Problem Statement + +Traditional commit notification systems suffer from several challenges: + +[arabic] +. *Connection Overhead*: Individual notification scripts create new IRC +connections for each commit, generating wasteful join/leave spam +. *Resource Inefficiency*: Spawning new processes for every notification +consumes system resources +. *Single Point of Failure*: Centralized notification services create +dependencies +. *Inflexibility*: Hard-coded or difficult-to-configure notification +formats +. *Maintenance Burden*: Original irker lacks modern documentation and +active maintenance + +=== Solution + +vext solves these problems through: + +* *Persistent Daemon Architecture*: Single long-running process +maintains connection state +* *Decentralized Design*: Each repository maintains its own irker +instance, no central server +* *Lightweight Implementation*: Python-based with minimal dependencies +* *JSON Protocol*: Language-agnostic, extensible notification format +* *Active Maintenance*: Improved documentation, modern Python support, +community-driven development + +=== Core Concept + +vext works through a two-component system: + +.... +Repository Commit + ↓ +Post-Commit Hook (irkerhook.py) + ↓ JSON Notification +Daemon Listener (irkerd) + ↓ Long-lived connections +IRC Server & Channels +.... + +The hook script triggers on commit, sends a JSON message to the daemon, +and the daemon handles IRC delivery. This separation of concerns enables +efficient connection management while keeping hooks simple and +stateless. + +=== Use Cases + +==== Primary Use Cases + +[arabic] +. *Development Team Coordination* +* Real-time visibility of repository activity +* Multiple developers stay informed without email spam +* Rapid feedback for code reviews and merges +. *Continuous Integration Pipelines* +* Trigger CI workflows based on commit notifications +* Route test results and build status to project channels +* Integration with existing IRC-based workflows +. *Project Milestone Tracking* +* Announce releases and major commits +* Multi-channel broadcasting (e.g., #releases, #commits) +* Historical log of project activity in IRC archives +. *Multi-Team Awareness* +* Route commits from multiple repositories to dedicated channels +* Cross-team visibility and collaboration signals +* Integration with legacy IRC infrastructure + +==== Secondary Use Cases + +* Forge site deployment (GitHub, GitLab, Gitea instances) +* Academic project collaboration +* Open-source project governance +* Legacy system integration + +=== Technical Architecture + +==== Components + +[arabic] +. *irkerd*: Daemon process that: +* Listens on configurable TCP/UDP port (default 6659) +* Maintains connection state to IRC servers +* Parses JSON notification requests +* Routes messages to destination channels +* Handles rate limiting and flood prevention +. *irkerhook.py*: Hook script that: +* Integrates with repository post-commit hooks +* Extracts commit metadata from VCS +* Formats notification JSON +* Sends to daemon via network socket +* Supports Git, Mercurial, and Subversion +. *Configuration System*: +* Environment variables for simple deployment +* Configuration files for advanced setups +* Systemd service files for Linux integration + +==== Data Flow + +[source,json] +---- +{ + "to": "irc://irc.libera.chat#myproject", + "privmsg": "[abc1234] Alice: Fix critical bug in parser", + "nick": "myproject-bot", + "color": "ANSI" +} +---- + +=== Advantages + +[cols=",,,,",options="header",] +|=== +|Feature |vext |Email |Slack |Centralized CI +|Real-time |✓ |✗ |✓ |✓ +|No central dependency |✓ |✓ |✗ |✗ +|Self-hosted |✓ |✓ |✗ |✓ +|Low resource overhead |✓ |✗ |✓ |✗ +|Works offline |✗ |✗ |✗ |✗ +|IRC integration |✓ |✗ |✗ |✗ +|No spam (no join/leave) |✓ |✓ |✓ |✓ +|=== + +=== Technology Stack + +* *Primary Language*: Python 2.7+, Python 3.4+ +* *Architecture Style*: Event-driven daemon with threading +* *Network Protocols*: TCP, UDP, IRC (RFC 1459) +* *Data Format*: JSON +* *Deployment*: systemd (Linux), traditional sysvinit, manual process +management +* *Dependencies*: Python standard library (minimal external deps) + +=== Installation Footprint + +* *Binary Size*: ~50-100 KB (Python bytecode) +* *Memory Usage*: ~10-50 MB running (depends on connected channels) +* *Storage*: ~1 MB for code and configs +* *Network*: Outbound TCP/UDP to IRC server, inbound on configured port + +=== Security Considerations + +[arabic] +. *Network Security*: +* Restrict daemon listener to internal networks if not needed externally +* Use firewall rules to limit access to repository hooks +* Consider placing daemon behind SSH tunnel for remote deployments +. *Process Security*: +* Run daemon as unprivileged user (e.g., '`irker`') +* Use seccomp sandboxing if available +* Limit process file descriptor count +. *Data Security*: +* Commit messages may contain sensitive information +* Configure channel access controls +* Consider encrypted IRC connections (TLS) + +=== Performance Characteristics + +* *Notification Latency*: <100ms from commit to IRC message (typically +<50ms) +* *Memory per Channel*: ~1-5 MB +* *CPU Usage*: <1% idle, <5% under heavy notification load +* *Concurrent Connections*: 100+ channels from single daemon +* *Message Throughput*: 1000+ messages/second capacity + +=== Scalability + +vext scales through: + +[arabic] +. *Horizontal*: Deploy multiple daemon instances for different +projects/teams +. *Vertical*: Single daemon handles many channels efficiently +. *Geographic*: Route to different IRC servers by project/team +. *Topical*: Multiple channels per repository for different notification +types + +=== Maintenance Model + +vext uses a community-maintained development model: + +* Regular updates for Python version compatibility +* Bug fixes and security patches +* Documentation improvements +* Community contributions and extensions +* Compatibility with modern IRC servers (libera.chat, etc.) + +=== Comparison with irker + +[cols=",,",options="header",] +|=== +|Aspect |irker (original) |vext (RSR) +|Python 3 support |Partial |Full +|Documentation |Basic |Comprehensive +|Active maintenance |Maintenance mode |Active +|Configuration |Minimal |Enhanced +|VCS support |Git/Hg/SVN |Git/Hg/SVN + extensible +|Testing |Limited |Comprehensive +|Examples |Few |Many +|Community |Small |Growing +|=== + +=== Deployment Options + +[arabic] +. *Single Server*: One daemon instance for organization +. *Per-Team*: Separate daemons for different teams/projects +. *High Availability*: Multiple daemons with load balancing +. *Cloud Native*: Container deployment with orchestration + +=== Roadmap + +Planned enhancements for vext: + +[arabic] +. *Short Term* (v1.x): +* Enhanced configuration management +* Improved error handling and logging +* Better testing coverage +. *Medium Term* (v2.x): +* Matrix/Element support alongside IRC +* Kubernetes-native deployment +* Web-based administration interface +. *Long Term* (v3.x): +* Plugin architecture for custom VCS support +* Advanced routing and filtering +* Metrics and observability improvements + +=== Conclusion + +vext represents the Rhodium Standard Edition of IRC-based commit +notification, maintaining the elegant simplicity of irker while adding +modern maintenance, comprehensive documentation, and production-ready +tooling. It’s ideal for teams that already use IRC infrastructure or +need a lightweight, self-hosted notification system without external +dependencies. diff --git a/vext/PROJECT_OVERVIEW.md b/vext/PROJECT_OVERVIEW.md deleted file mode 100644 index 480e75f..0000000 --- a/vext/PROJECT_OVERVIEW.md +++ /dev/null @@ -1,225 +0,0 @@ - -# vext Project Overview - -## Executive Summary - -**vext** (Rhodium Standard Edition) is a modernized, well-maintained fork of the irker IRC notification daemon. It provides real-time commit notifications from version control systems (Git, Mercurial, Subversion) to IRC channels with minimal resource overhead and no join/leave connection spam. - -## Problem Statement - -Traditional commit notification systems suffer from several challenges: - -1. **Connection Overhead**: Individual notification scripts create new IRC connections for each commit, generating wasteful join/leave spam -2. **Resource Inefficiency**: Spawning new processes for every notification consumes system resources -3. **Single Point of Failure**: Centralized notification services create dependencies -4. **Inflexibility**: Hard-coded or difficult-to-configure notification formats -5. **Maintenance Burden**: Original irker lacks modern documentation and active maintenance - -## Solution - -vext solves these problems through: - -- **Persistent Daemon Architecture**: Single long-running process maintains connection state -- **Decentralized Design**: Each repository maintains its own irker instance, no central server -- **Lightweight Implementation**: Python-based with minimal dependencies -- **JSON Protocol**: Language-agnostic, extensible notification format -- **Active Maintenance**: Improved documentation, modern Python support, community-driven development - -## Core Concept - -vext works through a two-component system: - -``` -Repository Commit - ↓ -Post-Commit Hook (irkerhook.py) - ↓ JSON Notification -Daemon Listener (irkerd) - ↓ Long-lived connections -IRC Server & Channels -``` - -The hook script triggers on commit, sends a JSON message to the daemon, and the daemon handles IRC delivery. This separation of concerns enables efficient connection management while keeping hooks simple and stateless. - -## Use Cases - -### Primary Use Cases - -1. **Development Team Coordination** - - Real-time visibility of repository activity - - Multiple developers stay informed without email spam - - Rapid feedback for code reviews and merges - -2. **Continuous Integration Pipelines** - - Trigger CI workflows based on commit notifications - - Route test results and build status to project channels - - Integration with existing IRC-based workflows - -3. **Project Milestone Tracking** - - Announce releases and major commits - - Multi-channel broadcasting (e.g., #releases, #commits) - - Historical log of project activity in IRC archives - -4. **Multi-Team Awareness** - - Route commits from multiple repositories to dedicated channels - - Cross-team visibility and collaboration signals - - Integration with legacy IRC infrastructure - -### Secondary Use Cases - -- Forge site deployment (GitHub, GitLab, Gitea instances) -- Academic project collaboration -- Open-source project governance -- Legacy system integration - -## Technical Architecture - -### Components - -1. **irkerd**: Daemon process that: - - Listens on configurable TCP/UDP port (default 6659) - - Maintains connection state to IRC servers - - Parses JSON notification requests - - Routes messages to destination channels - - Handles rate limiting and flood prevention - -2. **irkerhook.py**: Hook script that: - - Integrates with repository post-commit hooks - - Extracts commit metadata from VCS - - Formats notification JSON - - Sends to daemon via network socket - - Supports Git, Mercurial, and Subversion - -3. **Configuration System**: - - Environment variables for simple deployment - - Configuration files for advanced setups - - Systemd service files for Linux integration - -### Data Flow - -```json -{ - "to": "irc://irc.libera.chat#myproject", - "privmsg": "[abc1234] Alice: Fix critical bug in parser", - "nick": "myproject-bot", - "color": "ANSI" -} -``` - -## Advantages - -| Feature | vext | Email | Slack | Centralized CI | -|---------|------|-------|-------|----------------| -| Real-time | ✓ | ✗ | ✓ | ✓ | -| No central dependency | ✓ | ✓ | ✗ | ✗ | -| Self-hosted | ✓ | ✓ | ✗ | ✓ | -| Low resource overhead | ✓ | ✗ | ✓ | ✗ | -| Works offline | ✗ | ✗ | ✗ | ✗ | -| IRC integration | ✓ | ✗ | ✗ | ✗ | -| No spam (no join/leave) | ✓ | ✓ | ✓ | ✓ | - -## Technology Stack - -- **Primary Language**: Python 2.7+, Python 3.4+ -- **Architecture Style**: Event-driven daemon with threading -- **Network Protocols**: TCP, UDP, IRC (RFC 1459) -- **Data Format**: JSON -- **Deployment**: systemd (Linux), traditional sysvinit, manual process management -- **Dependencies**: Python standard library (minimal external deps) - -## Installation Footprint - -- **Binary Size**: ~50-100 KB (Python bytecode) -- **Memory Usage**: ~10-50 MB running (depends on connected channels) -- **Storage**: ~1 MB for code and configs -- **Network**: Outbound TCP/UDP to IRC server, inbound on configured port - -## Security Considerations - -1. **Network Security**: - - Restrict daemon listener to internal networks if not needed externally - - Use firewall rules to limit access to repository hooks - - Consider placing daemon behind SSH tunnel for remote deployments - -2. **Process Security**: - - Run daemon as unprivileged user (e.g., 'irker') - - Use seccomp sandboxing if available - - Limit process file descriptor count - -3. **Data Security**: - - Commit messages may contain sensitive information - - Configure channel access controls - - Consider encrypted IRC connections (TLS) - -## Performance Characteristics - -- **Notification Latency**: <100ms from commit to IRC message (typically <50ms) -- **Memory per Channel**: ~1-5 MB -- **CPU Usage**: <1% idle, <5% under heavy notification load -- **Concurrent Connections**: 100+ channels from single daemon -- **Message Throughput**: 1000+ messages/second capacity - -## Scalability - -vext scales through: - -1. **Horizontal**: Deploy multiple daemon instances for different projects/teams -2. **Vertical**: Single daemon handles many channels efficiently -3. **Geographic**: Route to different IRC servers by project/team -4. **Topical**: Multiple channels per repository for different notification types - -## Maintenance Model - -vext uses a community-maintained development model: - -- Regular updates for Python version compatibility -- Bug fixes and security patches -- Documentation improvements -- Community contributions and extensions -- Compatibility with modern IRC servers (libera.chat, etc.) - -## Comparison with irker - -| Aspect | irker (original) | vext (RSR) | -|--------|------------------|-----------| -| Python 3 support | Partial | Full | -| Documentation | Basic | Comprehensive | -| Active maintenance | Maintenance mode | Active | -| Configuration | Minimal | Enhanced | -| VCS support | Git/Hg/SVN | Git/Hg/SVN + extensible | -| Testing | Limited | Comprehensive | -| Examples | Few | Many | -| Community | Small | Growing | - -## Deployment Options - -1. **Single Server**: One daemon instance for organization -2. **Per-Team**: Separate daemons for different teams/projects -3. **High Availability**: Multiple daemons with load balancing -4. **Cloud Native**: Container deployment with orchestration - -## Roadmap - -Planned enhancements for vext: - -1. **Short Term** (v1.x): - - Enhanced configuration management - - Improved error handling and logging - - Better testing coverage - -2. **Medium Term** (v2.x): - - Matrix/Element support alongside IRC - - Kubernetes-native deployment - - Web-based administration interface - -3. **Long Term** (v3.x): - - Plugin architecture for custom VCS support - - Advanced routing and filtering - - Metrics and observability improvements - -## Conclusion - -vext represents the Rhodium Standard Edition of IRC-based commit notification, maintaining the elegant simplicity of irker while adding modern maintenance, comprehensive documentation, and production-ready tooling. It's ideal for teams that already use IRC infrastructure or need a lightweight, self-hosted notification system without external dependencies. diff --git a/vext/REPO-CONTENTS.adoc b/vext/REPO-CONTENTS.adoc new file mode 100644 index 0000000..46ccfea --- /dev/null +++ b/vext/REPO-CONTENTS.adoc @@ -0,0 +1,156 @@ +== Vext Repository Contents + +*Created:* 2025-01-31 *Location:* `+/var$REPOS_DIR/vext+` *GitHub:* +https://github.com/hyperpolymath/vext (after push) + +''''' + +=== Files Created + +==== Core Documentation + +* ✅ `+README.adoc+` - Project overview, architecture, quick start +* ✅ `+ROADMAP.md+` - 5-phase implementation plan (Q1 2025 - Q4 2026) +* ✅ `+LICENSE+` - MPL-2.0 license text +* ✅ `+CONTRIBUTING.md+` - Contribution guidelines +* ✅ `+SECURITY.md+` - Security policy and vulnerability reporting + +==== Checkpoint Files (Scheme) + +* ✅ `+STATE.scm+` - Current project state, milestones, blockers, next +actions +* ✅ `+ECOSYSTEM.scm+` - Position in ecosystem, related projects, +integrations +* ✅ `+META.scm+` - ADRs (Architecture Decision Records), philosophy, +governance + +==== Documentation (`+docs/+` directory) + +Should contain (copied from `+/var$HOME+`): - `+VEXT-MANIFESTO.md+` - +Why vext exists, the problem and solution - `+VEXT-TECHNICAL-SPEC.md+` - +Protocol specification, message format - +`+VEXT-ANTI-ALGORITHM-ARCHITECTURE.md+` - a2ml architecture, +cryptographic design - `+VEXT-MULTICAST-ARCHITECTURE.md+` - Tag-based +multicast, unicast vs multicast - `+VEXT-MOBILE-SMS-EMAIL.md+` - Mobile +strategy, SMS/RCS/Email gateways - `+VEXT-ADDITIONAL-PROTOCOLS.md+` - +Protocol bridges (Matrix, Nostr, etc.) - `+VEXT-ARXIV-PAPER-PLAN.md+` - +arXiv paper structure and timeline - `+NUJ-VEXT-PROPOSAL.md+` - National +Union of Journalists discussion paper + +==== Setup Script + +* ✅ `+COMMIT-AND-PUSH.sh+` - Automated commit and push script + +''''' + +=== To Commit and Push + +[source,bash] +---- +# Open a new terminal (current one has broken bash) +cd /var$REPOS_DIR/vext + +# Make script executable +chmod +x COMMIT-AND-PUSH.sh + +# Run the script +./COMMIT-AND-PUSH.sh +---- + +The script will: 1. Copy documentation from `+/var$HOME+` to `+docs/+` +2. Create LICENSE, CONTRIBUTING.md, SECURITY.md 3. Initialize git (if +needed) 4. Commit all files with proper message 5. Create GitHub repo +(if doesn’t exist) 6. Push to `+https://github.com/hyperpolymath/vext+` + +''''' + +=== Repository Structure + +.... +vext/ +├── README.adoc # Main entry point +├── ROADMAP.md # Implementation plan +├── LICENSE # MPL-2.0 +├── CONTRIBUTING.md # How to contribute +├── SECURITY.md # Security policy +├── COMMIT-AND-PUSH.sh # Setup script +├── REPO-CONTENTS.md # This file +│ +├── STATE.scm # Current state +├── ECOSYSTEM.scm # Ecosystem position +├── META.scm # ADRs and philosophy +│ +├── docs/ # Documentation +│ ├── VEXT-MANIFESTO.md +│ ├── VEXT-TECHNICAL-SPEC.md +│ ├── VEXT-ANTI-ALGORITHM-ARCHITECTURE.md +│ ├── VEXT-MULTICAST-ARCHITECTURE.md +│ ├── VEXT-MOBILE-SMS-EMAIL.md +│ ├── VEXT-ADDITIONAL-PROTOCOLS.md +│ ├── VEXT-ARXIV-PAPER-PLAN.md +│ └── NUJ-VEXT-PROPOSAL.md +│ +├── src/ # (Not yet created - for Idris2/Rust code) +│ ├── a2ml/ # a2ml specification (Idris2) +│ └── lib/ # Core library +│ +├── ffi/ # (Not yet created - for Zig FFI) +│ └── zig/ # Zig FFI implementation +│ +└── .github/ # (Not yet created - CI/CD workflows) + └── workflows/ +.... + +''''' + +=== Next Steps After Push + +[arabic] +. *Visit GitHub:* https://github.com/hyperpolymath/vext +. *Enable GitHub Pages:* +* Settings → Pages +* Source: Deploy from a branch +* Branch: main, folder: /docs +* Save +. *Verify Documentation:* Visit https://hyperpolymath.github.io/vext +(after Pages enabled) +. *Start Implementation:* +* Install Idris2: https://idris-lang.org/pages/download.html +* Create `+src/a2ml/+` directory +* Begin a2ml specification +. *Begin arXiv Paper:* +* Start with sections 1-3 (Introduction, Threat Model, Design) +* Target submission: April 2025 + +''''' + +=== Status + +* ✅ *Documentation Complete* - All core docs written +* ✅ *Checkpoint Files Complete* - STATE.scm, ECOSYSTEM.scm, META.scm +* ✅ *Repository Structure Ready* - Follows RSR standards +* ⏳ *Awaiting Commit* - Run `+COMMIT-AND-PUSH.sh+` in fresh terminal +* ⏳ *Implementation Not Started* - a2ml specification next + +''''' + +=== Key Decisions (from META.scm) + +[arabic] +. *ADR-001:* Use Idris2 for a2ml (dependent types required) +. *ADR-002:* Build on NNTP (proven protocol, add a2ml verification) +. *ADR-003:* Matrix bridge is high priority (universal access) +. *ADR-004:* Target journalists as initial user base (NUJ engagement) +. *ADR-005:* Publish arXiv paper before production launch (credibility) + +''''' + +=== Questions & Contact + +* *Author:* Jonathan D.A. Jewell +* *Email:* j.d.a.jewell@open.ac.uk +* *GitHub:* https://github.com/hyperpolymath + +''''' + +*Status:* Ready to commit and push! 🚀 diff --git a/vext/REPO-CONTENTS.md b/vext/REPO-CONTENTS.md deleted file mode 100644 index 5183ea1..0000000 --- a/vext/REPO-CONTENTS.md +++ /dev/null @@ -1,152 +0,0 @@ - -# Vext Repository Contents - -**Created:** 2025-01-31 -**Location:** `/var$REPOS_DIR/vext` -**GitHub:** https://github.com/hyperpolymath/vext (after push) - ---- - -## Files Created - -### Core Documentation -- ✅ `README.adoc` - Project overview, architecture, quick start -- ✅ `ROADMAP.md` - 5-phase implementation plan (Q1 2025 - Q4 2026) -- ✅ `LICENSE` - MPL-2.0 license text -- ✅ `CONTRIBUTING.md` - Contribution guidelines -- ✅ `SECURITY.md` - Security policy and vulnerability reporting - -### Checkpoint Files (Scheme) -- ✅ `STATE.scm` - Current project state, milestones, blockers, next actions -- ✅ `ECOSYSTEM.scm` - Position in ecosystem, related projects, integrations -- ✅ `META.scm` - ADRs (Architecture Decision Records), philosophy, governance - -### Documentation (`docs/` directory) -Should contain (copied from `/var$HOME`): -- `VEXT-MANIFESTO.md` - Why vext exists, the problem and solution -- `VEXT-TECHNICAL-SPEC.md` - Protocol specification, message format -- `VEXT-ANTI-ALGORITHM-ARCHITECTURE.md` - a2ml architecture, cryptographic design -- `VEXT-MULTICAST-ARCHITECTURE.md` - Tag-based multicast, unicast vs multicast -- `VEXT-MOBILE-SMS-EMAIL.md` - Mobile strategy, SMS/RCS/Email gateways -- `VEXT-ADDITIONAL-PROTOCOLS.md` - Protocol bridges (Matrix, Nostr, etc.) -- `VEXT-ARXIV-PAPER-PLAN.md` - arXiv paper structure and timeline -- `NUJ-VEXT-PROPOSAL.md` - National Union of Journalists discussion paper - -### Setup Script -- ✅ `COMMIT-AND-PUSH.sh` - Automated commit and push script - ---- - -## To Commit and Push - -```bash -# Open a new terminal (current one has broken bash) -cd /var$REPOS_DIR/vext - -# Make script executable -chmod +x COMMIT-AND-PUSH.sh - -# Run the script -./COMMIT-AND-PUSH.sh -``` - -The script will: -1. Copy documentation from `/var$HOME` to `docs/` -2. Create LICENSE, CONTRIBUTING.md, SECURITY.md -3. Initialize git (if needed) -4. Commit all files with proper message -5. Create GitHub repo (if doesn't exist) -6. Push to `https://github.com/hyperpolymath/vext` - ---- - -## Repository Structure - -``` -vext/ -├── README.adoc # Main entry point -├── ROADMAP.md # Implementation plan -├── LICENSE # MPL-2.0 -├── CONTRIBUTING.md # How to contribute -├── SECURITY.md # Security policy -├── COMMIT-AND-PUSH.sh # Setup script -├── REPO-CONTENTS.md # This file -│ -├── STATE.scm # Current state -├── ECOSYSTEM.scm # Ecosystem position -├── META.scm # ADRs and philosophy -│ -├── docs/ # Documentation -│ ├── VEXT-MANIFESTO.md -│ ├── VEXT-TECHNICAL-SPEC.md -│ ├── VEXT-ANTI-ALGORITHM-ARCHITECTURE.md -│ ├── VEXT-MULTICAST-ARCHITECTURE.md -│ ├── VEXT-MOBILE-SMS-EMAIL.md -│ ├── VEXT-ADDITIONAL-PROTOCOLS.md -│ ├── VEXT-ARXIV-PAPER-PLAN.md -│ └── NUJ-VEXT-PROPOSAL.md -│ -├── src/ # (Not yet created - for Idris2/Rust code) -│ ├── a2ml/ # a2ml specification (Idris2) -│ └── lib/ # Core library -│ -├── ffi/ # (Not yet created - for Zig FFI) -│ └── zig/ # Zig FFI implementation -│ -└── .github/ # (Not yet created - CI/CD workflows) - └── workflows/ -``` - ---- - -## Next Steps After Push - -1. **Visit GitHub:** https://github.com/hyperpolymath/vext -2. **Enable GitHub Pages:** - - Settings → Pages - - Source: Deploy from a branch - - Branch: main, folder: /docs - - Save -3. **Verify Documentation:** Visit https://hyperpolymath.github.io/vext (after Pages enabled) -4. **Start Implementation:** - - Install Idris2: https://idris-lang.org/pages/download.html - - Create `src/a2ml/` directory - - Begin a2ml specification -5. **Begin arXiv Paper:** - - Start with sections 1-3 (Introduction, Threat Model, Design) - - Target submission: April 2025 - ---- - -## Status - -- ✅ **Documentation Complete** - All core docs written -- ✅ **Checkpoint Files Complete** - STATE.scm, ECOSYSTEM.scm, META.scm -- ✅ **Repository Structure Ready** - Follows RSR standards -- ⏳ **Awaiting Commit** - Run `COMMIT-AND-PUSH.sh` in fresh terminal -- ⏳ **Implementation Not Started** - a2ml specification next - ---- - -## Key Decisions (from META.scm) - -1. **ADR-001:** Use Idris2 for a2ml (dependent types required) -2. **ADR-002:** Build on NNTP (proven protocol, add a2ml verification) -3. **ADR-003:** Matrix bridge is high priority (universal access) -4. **ADR-004:** Target journalists as initial user base (NUJ engagement) -5. **ADR-005:** Publish arXiv paper before production launch (credibility) - ---- - -## Questions & Contact - -- **Author:** Jonathan D.A. Jewell -- **Email:** j.d.a.jewell@open.ac.uk -- **GitHub:** https://github.com/hyperpolymath - ---- - -**Status:** Ready to commit and push! 🚀 diff --git a/vext/RESEARCH_SUMMARY.adoc b/vext/RESEARCH_SUMMARY.adoc new file mode 100644 index 0000000..8fac64c --- /dev/null +++ b/vext/RESEARCH_SUMMARY.adoc @@ -0,0 +1,323 @@ +== vext - Research & Documentation Summary + +=== Research Conducted + +==== Primary Research Focus: Understanding irker + +Based on web research and documentation analysis, here’s what was +discovered about the irker project and how vext relates to it: + +=== What is irker? + +*irker* is an IRC client daemon that accepts commit notifications from +version control systems and relays them to IRC channels. Created and +maintained by Eric S. Raymond, it solves the problem of efficient, +scalable IRC notification delivery. + +==== Key Characteristics of irker: + +[arabic] +. *Architecture*: Daemon-based (not individual scripts per notification) +. *Communication*: Listens on port 6659 for JSON-formatted notifications +. *Transport*: Supports TCP, UDP, and email delivery +. *VCS Support*: Works with Git, Mercurial (Hg), and Subversion (SVN) +. *Language*: Python +. *Connection Management*: Maintains persistent IRC connections +. *Benefits*: Eliminates join/leave channel spam, efficient resource +usage +. *Protocol*: JSON-based notification format + +==== irker Resource Links: + +* *Official Project*: https://gitlab.com/esr/irker (GitLab) +* *Resource Page*: http://www.catb.org/~esr/irker/ +* *License*: Eclipse Public License 2.0 +* *Status*: Mature, actively maintained in stable state + +=== What is vext (Rhodium Standard Edition)? + +vext represents a modernized, community-maintained fork of irker with +these improvements: + +==== Improvements over irker: + +[arabic] +. *Documentation*: Comprehensive, modern documentation (this package) +. *Python 3 Support*: Full Python 3.6+ compatibility +. *Maintenance*: Active, responsive development +. *Configuration*: Enhanced configuration management options +. *Logging*: Improved logging and observability +. *Testing*: More comprehensive test coverage +. *Examples*: Practical examples for all use cases +. *Organization*: Community governance and contribution model + +==== vext Design Philosophy: + +* Maintain full backward compatibility with irker +* Improve developer experience through documentation +* Support modern Python versions +* Enable easier deployment (Docker, systemd, etc.) +* Add advanced features while keeping core simple +* Focus on production-ready tooling + +=== Core Functionality + +Both irker and vext share the same core functionality: + +==== How It Works (2-Component Design): + +.... +Repository Event (git push, svn commit, hg commit) + ↓ +Repository Hook Script (irkerhook.py) + • Extracts commit metadata + • Formats as JSON + ↓ +vext Daemon (localhost:6659) + • Receives JSON notification + • Maintains IRC connection state + • Manages rate limiting and queuing + ↓ +IRC Server (irc.libera.chat, etc.) + ↓ +IRC Channels & Users +.... + +==== Why Two Components? + +The separation of concerns enables: - *Efficiency*: Single daemon +handles many channels - *Reliability*: No join/leave spam on every +commit - *Simplicity*: Hooks remain simple and stateless - +*Scalability*: One daemon can notify 1000+ channels - *Maintainability*: +Clean separation of concerns + +=== Technology Stack Research + +==== Language & Runtime + +* *Primary*: Python 2.7+ and Python 3.4+ (3.6+ for vext) +* *Type System*: Dynamic (duck typing) +* *Paradigm*: Object-oriented with functional elements +* *Cross-Platform*: Works on Linux, macOS, FreeBSD, Windows (WSL) + +==== Dependencies + +vext maintains minimal external dependencies: - *Core Dependencies*: +None beyond Python stdlib - *Network*: Python socket module for TCP/UDP +- *IRC*: Custom IRC protocol implementation - *JSON*: Python built-in +json module - *Subprocess*: Execute git/hg/svn for commit info + +==== Optional Enhancements + +* *dnspython*: Better DNS/SRV record support +* *pyyaml*: YAML configuration files +* *python-daemon*: Better daemon management +* *pytest*: Testing framework (dev only) + +=== Key Features Documented + +==== 12 Core Features: + +[arabic] +. Multi-VCS Support (Git, Mercurial, SVN) +. Persistent Connection Management +. Flexible Communication Protocols (TCP, UDP, Email) +. JSON-Based Protocol +. Multi-Channel Broadcasting +. Color Formatting (ANSI, mIRC) +. Configurable Notification Format +. Rate Limiting & Flood Prevention +. Comprehensive Logging +. Flexible Routing +. Performance Optimization +. Security Features + +==== 6 Advanced Features: + +[arabic] +. Extensible Hook System +. Metrics and Monitoring +. Web-based Administration Interface (Planned) +. Multi-Server Support +. Template-Based Formatting +. CI/CD Pipeline Integration + +=== Use Cases Identified + +==== Primary Use Cases: + +[arabic] +. *Team Coordination*: Real-time commit visibility in IRC +. *Continuous Integration*: Triggering CI workflows from commits +. *Project Milestones*: Announcing releases and major events +. *Multi-Team Awareness*: Cross-team visibility + +==== Secondary Use Cases: + +* Open-source project governance +* Academic collaboration +* Forge site deployment (GitHub, GitLab, Gitea) +* Legacy system integration + +=== Advantages Over Alternatives + +[cols=",,,,",options="header",] +|=== +|Feature |vext |Email |Slack |CI Systems +|Real-time |✓ |✗ |✓ |✓ +|No central dependency |✓ |✓ |✗ |✗ +|Self-hosted |✓ |✓ |✗ |✓ +|Low resource overhead |✓ |✗ |✓ |✗ +|IRC integration |✓ |✗ |✗ |✗ +|No join/leave spam |✓ |✓ |✓ |✓ +|=== + +=== Installation Methods Researched + +[arabic] +. *From Source*: Clone repository, setup venv, install package +. *Package Manager*: Ubuntu apt, CentOS yum, macOS Homebrew +. *Docker*: Complete containerization with Dockerfile +. *Manual*: Directory structure, symlinks, service files + +=== Configuration Options Researched + +==== Environment Variables + +* `+IRKERD_HOST+`: Bind address (default: localhost) +* `+IRKERD_PORT+`: Listener port (default: 6659) +* `+IRKERD_NICK+`: Bot nickname +* `+IRKERD_COLOR_MODE+`: Color format (ANSI, mIRC, none) +* `+IRKERD_USE_TCP+`: Use TCP instead of UDP + +==== Configuration Files + +* INI format with sections: [daemon], [irc], [features] +* Per-repository .vext.conf for custom settings +* Environment file for systemd service + +==== Code-Based Configuration + +* Python classes for programmatic setup +* Custom hook implementations +* Direct API usage + +=== Performance Characteristics + +==== Resource Usage + +* *Base Memory*: 10-20 MB +* *Per-Channel*: ~160 KB +* *1000 channels*: ~150 MB total +* *CPU (idle)*: <1% +* *CPU (1000 msgs/sec)*: ~30% (single core) + +==== Latency + +* *End-to-end*: <100ms typical +* *TCP mode*: +5-10ms vs UDP +* *Local network*: <10ms +* *Internet*: 10-100ms + +==== Throughput + +* *Message capacity*: 1000+ msgs/sec +* *Concurrent channels*: 1000+ +* *Connections per daemon*: Limited by file descriptors + +=== Security Considerations + +[arabic] +. *Process Security*: Run as unprivileged user +. *Network Security*: Restrict listener to internal networks +. *Data Security*: Be aware commit messages may contain sensitive info +. *Encryption*: TLS/SSL support for IRC connections +. *Authentication*: SASL support for IRC servers + +=== Comparison with Original irker + +[cols=",,",options="header",] +|=== +|Aspect |irker (original) |vext (RSR) +|Python 3 support |Partial |Full +|Documentation |Basic |Comprehensive +|Active maintenance |Stable |Active +|Configuration |Minimal |Enhanced +|Logging |Basic |Comprehensive +|Examples |Few |Many +|Community |Small |Growing +|API docs |Limited |Detailed +|Troubleshooting guides |Minimal |Extensive +|=== + +=== Deployment Scenarios + +[arabic] +. *Single Server*: One daemon for organization +. *Per-Team*: Separate daemons for different teams +. *High Availability*: Multiple daemons with load balancing +. *Cloud Native*: Kubernetes/container deployment +. *Distributed*: Multiple daemons across locations + +=== Roadmap Based on Research + +==== Short Term (v1.x): + +* Enhanced configuration management +* Improved error handling +* Better testing coverage + +==== Medium Term (v2.x): + +* Matrix/Element protocol support +* Kubernetes-native deployment +* Web administration interface + +==== Long Term (v3.x): + +* Plugin architecture for VCS extensions +* Advanced routing and filtering +* Metrics and observability improvements + +=== Documentation Created + +This research informed creation of 3,332 lines of comprehensive +documentation across 7 files: + +[arabic] +. *README.md* (338 lines) - Main project documentation +. *PROJECT_OVERVIEW.md* (221 lines) - Executive overview +. *FEATURES.md* (372 lines) - Feature documentation +. *TECHNOLOGY_STACK.md* (580 lines) - Technical details +. *INSTALLATION_GUIDE.md* (701 lines) - Setup procedures +. *USAGE_GUIDE.md* (723 lines) - Operations guide +. *DOCUMENTATION_INDEX.md* (397 lines) - Navigation guide + +=== Conclusion + +vext (Rhodium Standard Edition) represents a modern, well-maintained +evolution of the irker IRC notification daemon. It maintains full +compatibility with the original while providing: + +* *Better Documentation*: Comprehensive guides for all scenarios +* *Modern Python*: Full Python 3 support +* *Production-Ready*: Clear installation and deployment paths +* *Active Maintenance*: Community-driven development +* *Enterprise-Ready*: Security, logging, and monitoring + +The project is ideal for organizations that: - Use IRC for team +communication - Want lightweight, self-hosted notification systems - +Need reliable version control system integration - Avoid external +service dependencies + +=== Research Sources Used + +* https://gitlab.com/esr/irker[GitLab - Eric S. Raymond / irker] +* http://www.catb.org/~esr/irker/[irker Resource Page] +* https://manpages.ubuntu.com/manpages/focal/man1/irkerhook-git.1.html[Ubuntu +Manpages - irkerhook] +* https://manpages.debian.org/testing/irker/irkerd.8.en.html[Debian +Manpages - irkerd] +* https://github.com/Hyperpolymath[GitHub - Hyperpolymath] +* https://docs.gitlab.com/ee/user/project/integrations/irker.html[GitLab +Documentation - irker integration] diff --git a/vext/RESEARCH_SUMMARY.md b/vext/RESEARCH_SUMMARY.md deleted file mode 100644 index 2556abe..0000000 --- a/vext/RESEARCH_SUMMARY.md +++ /dev/null @@ -1,290 +0,0 @@ - -# vext - Research & Documentation Summary - -## Research Conducted - -### Primary Research Focus: Understanding irker - -Based on web research and documentation analysis, here's what was discovered about the irker project and how vext relates to it: - -## What is irker? - -**irker** is an IRC client daemon that accepts commit notifications from version control systems and relays them to IRC channels. Created and maintained by Eric S. Raymond, it solves the problem of efficient, scalable IRC notification delivery. - -### Key Characteristics of irker: - -1. **Architecture**: Daemon-based (not individual scripts per notification) -2. **Communication**: Listens on port 6659 for JSON-formatted notifications -3. **Transport**: Supports TCP, UDP, and email delivery -4. **VCS Support**: Works with Git, Mercurial (Hg), and Subversion (SVN) -5. **Language**: Python -6. **Connection Management**: Maintains persistent IRC connections -7. **Benefits**: Eliminates join/leave channel spam, efficient resource usage -8. **Protocol**: JSON-based notification format - -### irker Resource Links: -- **Official Project**: https://gitlab.com/esr/irker (GitLab) -- **Resource Page**: http://www.catb.org/~esr/irker/ -- **License**: Eclipse Public License 2.0 -- **Status**: Mature, actively maintained in stable state - -## What is vext (Rhodium Standard Edition)? - -vext represents a modernized, community-maintained fork of irker with these improvements: - -### Improvements over irker: - -1. **Documentation**: Comprehensive, modern documentation (this package) -2. **Python 3 Support**: Full Python 3.6+ compatibility -3. **Maintenance**: Active, responsive development -4. **Configuration**: Enhanced configuration management options -5. **Logging**: Improved logging and observability -6. **Testing**: More comprehensive test coverage -7. **Examples**: Practical examples for all use cases -8. **Organization**: Community governance and contribution model - -### vext Design Philosophy: - -- Maintain full backward compatibility with irker -- Improve developer experience through documentation -- Support modern Python versions -- Enable easier deployment (Docker, systemd, etc.) -- Add advanced features while keeping core simple -- Focus on production-ready tooling - -## Core Functionality - -Both irker and vext share the same core functionality: - -### How It Works (2-Component Design): - -``` -Repository Event (git push, svn commit, hg commit) - ↓ -Repository Hook Script (irkerhook.py) - • Extracts commit metadata - • Formats as JSON - ↓ -vext Daemon (localhost:6659) - • Receives JSON notification - • Maintains IRC connection state - • Manages rate limiting and queuing - ↓ -IRC Server (irc.libera.chat, etc.) - ↓ -IRC Channels & Users -``` - -### Why Two Components? - -The separation of concerns enables: -- **Efficiency**: Single daemon handles many channels -- **Reliability**: No join/leave spam on every commit -- **Simplicity**: Hooks remain simple and stateless -- **Scalability**: One daemon can notify 1000+ channels -- **Maintainability**: Clean separation of concerns - -## Technology Stack Research - -### Language & Runtime -- **Primary**: Python 2.7+ and Python 3.4+ (3.6+ for vext) -- **Type System**: Dynamic (duck typing) -- **Paradigm**: Object-oriented with functional elements -- **Cross-Platform**: Works on Linux, macOS, FreeBSD, Windows (WSL) - -### Dependencies -vext maintains minimal external dependencies: -- **Core Dependencies**: None beyond Python stdlib -- **Network**: Python socket module for TCP/UDP -- **IRC**: Custom IRC protocol implementation -- **JSON**: Python built-in json module -- **Subprocess**: Execute git/hg/svn for commit info - -### Optional Enhancements -- **dnspython**: Better DNS/SRV record support -- **pyyaml**: YAML configuration files -- **python-daemon**: Better daemon management -- **pytest**: Testing framework (dev only) - -## Key Features Documented - -### 12 Core Features: -1. Multi-VCS Support (Git, Mercurial, SVN) -2. Persistent Connection Management -3. Flexible Communication Protocols (TCP, UDP, Email) -4. JSON-Based Protocol -5. Multi-Channel Broadcasting -6. Color Formatting (ANSI, mIRC) -7. Configurable Notification Format -8. Rate Limiting & Flood Prevention -9. Comprehensive Logging -10. Flexible Routing -11. Performance Optimization -12. Security Features - -### 6 Advanced Features: -1. Extensible Hook System -2. Metrics and Monitoring -3. Web-based Administration Interface (Planned) -4. Multi-Server Support -5. Template-Based Formatting -6. CI/CD Pipeline Integration - -## Use Cases Identified - -### Primary Use Cases: -1. **Team Coordination**: Real-time commit visibility in IRC -2. **Continuous Integration**: Triggering CI workflows from commits -3. **Project Milestones**: Announcing releases and major events -4. **Multi-Team Awareness**: Cross-team visibility - -### Secondary Use Cases: -- Open-source project governance -- Academic collaboration -- Forge site deployment (GitHub, GitLab, Gitea) -- Legacy system integration - -## Advantages Over Alternatives - -| Feature | vext | Email | Slack | CI Systems | -|---------|------|-------|-------|-----------| -| Real-time | ✓ | ✗ | ✓ | ✓ | -| No central dependency | ✓ | ✓ | ✗ | ✗ | -| Self-hosted | ✓ | ✓ | ✗ | ✓ | -| Low resource overhead | ✓ | ✗ | ✓ | ✗ | -| IRC integration | ✓ | ✗ | ✗ | ✗ | -| No join/leave spam | ✓ | ✓ | ✓ | ✓ | - -## Installation Methods Researched - -1. **From Source**: Clone repository, setup venv, install package -2. **Package Manager**: Ubuntu apt, CentOS yum, macOS Homebrew -3. **Docker**: Complete containerization with Dockerfile -4. **Manual**: Directory structure, symlinks, service files - -## Configuration Options Researched - -### Environment Variables -- `IRKERD_HOST`: Bind address (default: localhost) -- `IRKERD_PORT`: Listener port (default: 6659) -- `IRKERD_NICK`: Bot nickname -- `IRKERD_COLOR_MODE`: Color format (ANSI, mIRC, none) -- `IRKERD_USE_TCP`: Use TCP instead of UDP - -### Configuration Files -- INI format with sections: [daemon], [irc], [features] -- Per-repository .vext.conf for custom settings -- Environment file for systemd service - -### Code-Based Configuration -- Python classes for programmatic setup -- Custom hook implementations -- Direct API usage - -## Performance Characteristics - -### Resource Usage -- **Base Memory**: 10-20 MB -- **Per-Channel**: ~160 KB -- **1000 channels**: ~150 MB total -- **CPU (idle)**: <1% -- **CPU (1000 msgs/sec)**: ~30% (single core) - -### Latency -- **End-to-end**: <100ms typical -- **TCP mode**: +5-10ms vs UDP -- **Local network**: <10ms -- **Internet**: 10-100ms - -### Throughput -- **Message capacity**: 1000+ msgs/sec -- **Concurrent channels**: 1000+ -- **Connections per daemon**: Limited by file descriptors - -## Security Considerations - -1. **Process Security**: Run as unprivileged user -2. **Network Security**: Restrict listener to internal networks -3. **Data Security**: Be aware commit messages may contain sensitive info -4. **Encryption**: TLS/SSL support for IRC connections -5. **Authentication**: SASL support for IRC servers - -## Comparison with Original irker - -| Aspect | irker (original) | vext (RSR) | -|--------|------------------|-----------| -| Python 3 support | Partial | Full | -| Documentation | Basic | Comprehensive | -| Active maintenance | Stable | Active | -| Configuration | Minimal | Enhanced | -| Logging | Basic | Comprehensive | -| Examples | Few | Many | -| Community | Small | Growing | -| API docs | Limited | Detailed | -| Troubleshooting guides | Minimal | Extensive | - -## Deployment Scenarios - -1. **Single Server**: One daemon for organization -2. **Per-Team**: Separate daemons for different teams -3. **High Availability**: Multiple daemons with load balancing -4. **Cloud Native**: Kubernetes/container deployment -5. **Distributed**: Multiple daemons across locations - -## Roadmap Based on Research - -### Short Term (v1.x): -- Enhanced configuration management -- Improved error handling -- Better testing coverage - -### Medium Term (v2.x): -- Matrix/Element protocol support -- Kubernetes-native deployment -- Web administration interface - -### Long Term (v3.x): -- Plugin architecture for VCS extensions -- Advanced routing and filtering -- Metrics and observability improvements - -## Documentation Created - -This research informed creation of 3,332 lines of comprehensive documentation across 7 files: - -1. **README.md** (338 lines) - Main project documentation -2. **PROJECT_OVERVIEW.md** (221 lines) - Executive overview -3. **FEATURES.md** (372 lines) - Feature documentation -4. **TECHNOLOGY_STACK.md** (580 lines) - Technical details -5. **INSTALLATION_GUIDE.md** (701 lines) - Setup procedures -6. **USAGE_GUIDE.md** (723 lines) - Operations guide -7. **DOCUMENTATION_INDEX.md** (397 lines) - Navigation guide - -## Conclusion - -vext (Rhodium Standard Edition) represents a modern, well-maintained evolution of the irker IRC notification daemon. It maintains full compatibility with the original while providing: - -- **Better Documentation**: Comprehensive guides for all scenarios -- **Modern Python**: Full Python 3 support -- **Production-Ready**: Clear installation and deployment paths -- **Active Maintenance**: Community-driven development -- **Enterprise-Ready**: Security, logging, and monitoring - -The project is ideal for organizations that: -- Use IRC for team communication -- Want lightweight, self-hosted notification systems -- Need reliable version control system integration -- Avoid external service dependencies - -## Research Sources Used - -- [GitLab - Eric S. Raymond / irker](https://gitlab.com/esr/irker) -- [irker Resource Page](http://www.catb.org/~esr/irker/) -- [Ubuntu Manpages - irkerhook](https://manpages.ubuntu.com/manpages/focal/man1/irkerhook-git.1.html) -- [Debian Manpages - irkerd](https://manpages.debian.org/testing/irker/irkerd.8.en.html) -- [GitHub - Hyperpolymath](https://github.com/Hyperpolymath) -- [GitLab Documentation - irker integration](https://docs.gitlab.com/ee/user/project/integrations/irker.html) - diff --git a/vext/ROADMAP.adoc b/vext/ROADMAP.adoc index 174b56f..b820b73 100644 --- a/vext/ROADMAP.adoc +++ b/vext/ROADMAP.adoc @@ -1,129 +1,8 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= vext Roadmap -:toc: -:toclevels: 3 +== vext Roadmap (Canonical Location) -== Overview +The authoritative vext roadmap is maintained in: -This roadmap outlines the development plan for vext (IRC notification daemon for git operations). +* `+ROADMAP.adoc+` -== v1.0 - Production Release (Current) - -**Target:** 2026-02 -**Status:** Release candidate - -=== Core Features -* ✅ IRC notification daemon for git operations -* ✅ Connection pooling and management -* ✅ HTTP webhook receiver -* ✅ GitLab/GitHub webhook support -* ✅ Pandoc integration for document conversion -* ✅ Hunspell spell checking for commit messages -* ✅ Internationalization support (en-US, es-ES, fr-FR) - -=== Testing & Quality -* ✅ Unit tests -* ✅ Integration tests -* ✅ ClusterFuzzLite fuzzing -* ✅ Stress tests -* ✅ Benchmarks (criterion) - -=== Documentation -* ✅ README.adoc -* ✅ 6 SCM files (STATE, META, ECOSYSTEM, PLAYBOOK, AGENTIC, NEUROSYM) -* ✅ Security policy -* ✅ Usage guide -* ✅ Technology stack documentation - -=== Remaining for v1.0 -* [ ] Add SPDX headers to all SCM files -* [ ] Add image alt text for accessibility -* [ ] Complete feature documentation in README - -== v1.1 - Stability & Polish (Next) - -**Target:** 2026-03 -**Focus:** Bug fixes, performance improvements, accessibility - -=== Enhancements -* Enhanced error messages and debugging -* Performance optimization (connection pooling, message batching) -* Expanded i18n language support -* WCAG AAA accessibility compliance - -=== Documentation -* Video tutorials -* Integration examples with popular Git hosting platforms -* Performance tuning guide - -== v1.2 - Extended Integrations - -**Target:** 2026-04 - -=== New Integrations -* Gitea webhook support -* Bitbucket webhook support -* Custom webhook format support -* Discord notifications (optional feature) -* Slack notifications (optional feature) - -=== Advanced Features -* Message templating system -* Conditional notification rules -* Rate limiting per channel -* Message priority queues - -== v2.0 - Major Features - -**Target:** 2026-Q3 - -=== Architecture -* Plugin system for extensibility -* Message transformation pipeline -* Event filtering and routing -* Multi-protocol support (IRC, Matrix, XMPP) - -=== Neurosymbolic Features -* Commit message analysis and suggestions -* Automated code review notifications -* Integration with hypatia for rule-based notification routing -* A2ML integration for verified documentation - -=== K9-SVC Integration -* Self-validating component contracts -* Must-just-nickel validation -* Contractiles integration - -== v3.0 - Distributed & Cloud-Native - -**Target:** 2027 - -=== Cloud Features -* Kubernetes operator -* Multi-instance coordination -* Distributed notification delivery -* High availability setup -* Cloud-native monitoring and observability - -=== Advanced AI -* Natural language commit message generation -* Intelligent notification prioritization -* Anomaly detection in git activity -* Automated response generation - -== Long-term Vision - -* Full gitbot-fleet integration -* Hypatia rule-based orchestration -* Formal verification of notification delivery -* Proof-of-work integration for spam prevention -* Distributed trust network for notifications - -== Contributing - -See link:CONTRIBUTING.md[Contributing Guidelines] for how to contribute to vext development. - -== Versioning - -vext follows semantic versioning (SemVer). Breaking changes will only be introduced in major version releases. +This Markdown file is intentionally kept as a compatibility pointer to +avoid divergent planning documents. diff --git a/vext/ROADMAP.md b/vext/ROADMAP.md deleted file mode 100644 index 1d38f4f..0000000 --- a/vext/ROADMAP.md +++ /dev/null @@ -1,12 +0,0 @@ - -# vext Roadmap (Canonical Location) - -The authoritative vext roadmap is maintained in: - -- `ROADMAP.adoc` - -This Markdown file is intentionally kept as a compatibility pointer to avoid divergent planning documents. - diff --git a/vext/RSR_COMPLIANCE.adoc b/vext/RSR_COMPLIANCE.adoc new file mode 100644 index 0000000..8af821f --- /dev/null +++ b/vext/RSR_COMPLIANCE.adoc @@ -0,0 +1,436 @@ +== RSR Compliance Assessment + +**SPDX-License-Identifier: CC-BY-SA-4.0 + +*Project*: vext (Rhodium Standard Edition of irker) *Assessment Date*: +2025-01-01 *Assessor*: vext Team *Tool*: `+tools/rsr_checker.py+` + +=== 📊 Executive Summary + +[cols=",,",options="header",] +|=== +|Level |Score |Status +|*Bronze* |18/18 (100%) |✅ *PERFECT* +|*Silver* |6/6 (100%) |✅ *PERFECT* +|*Gold* |1/3 (33%) |⚠️ Partial +|*Platinum* |0/4 (0%) |⏳ Future +|=== + +*Overall Compliance Level*: 🥈 *SILVER* + +vext has achieved *100% Silver Level compliance*, demonstrating +comprehensive documentation, security practices, reproducible builds, +and automated compliance verification. + +=== 🏅 Achievement Badges + +[source,markdown] +---- +![RSR Compliance](https://img.shields.io/badge/RSR-Silver-silver) +![Bronze Level](https://img.shields.io/badge/Bronze-100%25-orange) +![Silver Level](https://img.shields.io/badge/Silver-100%25-silver) +---- + +=== 📋 Detailed Assessment + +==== ✅ Bronze Level (18/18 - 100%) + +Bronze level establishes foundational documentation, security policies, +build systems, and community governance. + +[width="100%",cols="5%,42%,23%,30%",options="header",] +|=== +|# |Requirement |Status |Location +|1 |README.md with comprehensive content |✅ |`+README.md+` + +|2 |LICENSE with SPDX identifier |✅ |`+LICENSE+` + +|3 |SECURITY.md with vulnerability disclosure |✅ |`+SECURITY.md+` + +|4 |CONTRIBUTING.md |✅ |`+CONTRIBUTING.md+` + +|5 |CODE_OF_CONDUCT.md |✅ |`+CODE_OF_CONDUCT.md+` + +|6 |MAINTAINERS.md |✅ |`+MAINTAINERS.md+` + +|7 |CHANGELOG.md |✅ |`+CHANGELOG.md+` + +|8 |.well-known/security.txt (RFC 9116) |✅ +|`+.well-known/security.txt+` + +|9 |.well-known/ai.txt |✅ |`+.well-known/ai.txt+` + +|10 |.well-known/humans.txt |✅ |`+.well-known/humans.txt+` + +|11 |Build system (Justfile) |✅ |`+justfile+` + +|12 |Nix flakes (flake.nix) |✅ |`+flake.nix+` + +|13 |CI/CD (.gitlab-ci.yml) |✅ |`+.gitlab-ci.yml+` + +|14 |TPCF governance documentation |✅ +|`+governance/PROJECT_GOVERNANCE.md+` + +|15 |.gitignore |✅ |`+.gitignore+` + +|16 |Test structure |✅ |`+tests/+` + +|17 |Documentation index |✅ |`+DOCUMENTATION_INDEX.md+` + +|18 |Project metadata |✅ |(Python project structure) +|=== + +===== Bronze Level Highlights + +*Documentation Excellence*: - 8 comprehensive documentation files (3,618 +total lines) - README, INSTALLATION_GUIDE, USAGE_GUIDE, FEATURES, +TECHNOLOGY_STACK - Clear navigation via DOCUMENTATION_INDEX.md - +Multiple audience levels (users, developers, deployers) + +*Security Foundations*: - RFC 9116 compliant +`+.well-known/security.txt+` - Comprehensive SECURITY.md with response +times - Multiple contact methods (email, GitHub advisories) - Clear +vulnerability disclosure process + +*Community Infrastructure*: - Code of Conduct with emotional safety +framework - Contribution guidelines with TPCF model - Maintainer +documentation with clear roles - Tri-Perimeter Contribution Framework +(TPCF) + +*Build Automation*: - Justfile with 40+ recipes - Nix flakes for +reproducible builds - GitLab CI/CD with multi-stage pipeline - Automated +testing and linting + +==== ✅ Silver Level (6/6 - 100%) + +Silver level adds automated compliance checking, advanced documentation, +dual licensing, and comprehensive .well-known directory. + +[width="100%",cols="5%,42%,23%,30%",options="header",] +|=== +|# |Requirement |Status |Location +|1 |RSR compliance checker tool |✅ |`+tools/rsr_checker.py+` +|2 |RSR compliance documentation |✅ |`+RSR_COMPLIANCE.md+` (this file) +|3 |Palimpsest dual licensing |✅ |`+LICENSE+` +|4 |Complete .well-known directory |✅ |`+.well-known/+` +|5 |Advanced documentation suite |✅ |Multiple guides (8 files) +|6 |Nix flakes with full configuration |✅ |`+flake.nix+` +|=== + +===== Silver Level Highlights + +*Automated Compliance Verification*: - Python-based RSR checker +(`+tools/rsr_checker.py+`) - Supports Bronze, Silver, Gold, Platinum +levels - JSON export for CI/CD integration - Badge generation for README +- Command-line interface with detailed reporting + +*Palimpsest Dual Licensing*: - MPL-2.0 - Clear SPDX identifier: +`+SPDX-License-Identifier: CC-BY-SA-4.0+` - Comprehensive LICENSE file +explaining both options - Guidance on when to choose each license - +Patent grants and trademark notices + +*Complete .well-known Directory*: - `+security.txt+` - RFC 9116 +compliant security contact - `+ai.txt+` - AI training policy (allowed +with conditions) - `+humans.txt+` - Team attribution and project info + +*Advanced Documentation*: - 8 comprehensive guides totaling 3,618 lines +- Installation, usage, features, technology stack - Project overview and +research summary - Documentation index for navigation - Multiple formats +(Markdown, future HTML) + +*Reproducible Builds*: - Nix flakes with inputs/outputs - Development +shell with tools pre-configured - NixOS module for system-wide +deployment - Build checks and CI integration + +==== ⚠️ Gold Level (1/3 - 33%) + +Gold level requires formal verification, multi-language support, or +advanced security features. + +[width="100%",cols="5%,42%,23%,30%",options="header",] +|=== +|# |Requirement |Status |Location +|1 |Formal verification or property-based testing |❌ |Future work +|2 |Multi-language support (2+ languages) |❌ |Python only (currently) +|3 |Advanced security features |✅ |CI/CD security scanning +|=== + +===== Gold Level Partial Achievement + +*Advanced Security* (✅ Achieved): - Bandit security scanner in CI/CD - +Safety dependency vulnerability checker - Secret scanning in GitLab CI - +SPDX license identifier checking - Automated security reporting + +*Opportunities for Improvement*: + +[arabic] +. *Formal Verification* (Future): +* Add property-based testing with Hypothesis +* Formal protocol specifications +* State machine verification +* TLA+ specifications for concurrent behavior +. *Multi-Language Support* (Potential): +* ReScript/Rescript for type-safe client +* Rust for high-performance daemon +* Ada/SPARK for formally verified core +* Elixir for distributed message routing + +==== ⏳ Platinum Level (0/4 - 0%) + +Platinum level represents research-grade achievements and advanced +distributed systems capabilities. + +[cols=",,,",options="header",] +|=== +|# |Requirement |Status |Location +|1 |CRDT or offline-first architecture |❌ |Future work +|2 |Academic paper |❌ |Future work +|3 |Conference materials |❌ |Future work +|4 |iSOS integration |❌ |Future work +|=== + +===== Platinum Level Roadmap + +*CRDT/Offline-First* (Future): - Conflict-free channel state replication +- Offline message queuing - Eventually consistent delivery - CADRE +architecture integration + +*Academic Paper* (Potential Topics): - "`IRC Notification Reliability: +Formal Analysis`" - "`Graduated Trust Models for Open Source Projects`" +- "`Emotional Safety Metrics in Code Review`" + +*Conference Materials* (Potential Venues): - FOSDEM (Developer Room: +Collaboration & Communication) - PyCon (IRC infrastructure) - OSCON +(Open Source Governance) + +*iSOS Integration* (Future): - Multi-language verification across +components - Compositional correctness proofs - FFI contract system - +WASM sandboxing for extensions + +=== 🎯 Compliance Verification + +==== Automated Checking + +Run the RSR compliance checker: + +[source,bash] +---- +# Basic check +just rsr-check + +# Or directly +python3 tools/rsr_checker.py . + +# JSON export +just rsr-check-json + +# Generate badge +just rsr-badge +---- + +==== Manual Verification + +All compliance requirements can be manually verified: + +[source,bash] +---- +# Check documentation +ls -lh *.md governance/*.md .well-known/ + +# Check build systems +ls -lh Justfile flake.nix .gitlab-ci.yml + +# Check tests +pytest tests/ -v + +# Check Nix builds +nix build +nix flake check +---- + +=== 📈 Compliance Metrics + +==== Documentation Coverage + +[cols=",,,",options="header",] +|=== +|Category |Files |Lines |Status +|Core Documentation |8 |3,618 |✅ Complete +|Security Policies |2 |500+ |✅ Complete +|Community Governance |3 |800+ |✅ Complete +|Build Configuration |3 |600+ |✅ Complete +|.well-known |3 |300+ |✅ Complete +|=== + +==== Security Posture + +[cols=",,",options="header",] +|=== +|Aspect |Implementation |Status +|RFC 9116 security.txt |✅ Yes |Complete +|Vulnerability disclosure |✅ Documented |Complete +|Response times |✅ Defined |Complete +|Security scanning |✅ Automated |Complete +|Dependency checking |✅ CI/CD |Complete +|SPDX identifiers |✅ All files |Complete +|=== + +==== Build & Testing + +[cols=",,",options="header",] +|=== +|Aspect |Implementation |Status +|Build automation |just, Make, Nix |✅ Complete +|CI/CD pipeline |GitLab CI (5 stages) |✅ Complete +|Test framework |pytest + unittest |✅ Basic +|Test coverage |Placeholder tests |⚠️ Need expansion +|Reproducible builds |Nix flakes |✅ Complete +|NixOS module |System-wide deployment |✅ Complete +|=== + +=== 🔄 Continuous Compliance + +==== Maintenance Schedule + +* *Weekly*: Automated compliance checks in CI/CD +* *Monthly*: Review and update documentation +* *Quarterly*: Comprehensive RSR assessment +* *Annually*: Full governance and security review + +==== CI/CD Integration + +RSR compliance is checked automatically: + +[source,yaml] +---- +# .gitlab-ci.yml +compliance:rsr: + script: + - python tools/rsr_checker.py . --json --badge + artifacts: + paths: + - rsr_compliance.json +---- + +==== Badge Integration + +Add to README.md: + +[source,markdown] +---- +![RSR Compliance](https://img.shields.io/badge/RSR-Silver-silver) +---- + +=== 🚀 Roadmap to Gold Level + +To achieve Gold level (66%+ of Gold requirements), we need 2/3: + +==== Path 1: Formal Verification ⭐ *Recommended* + +* Implement property-based testing with Hypothesis +* Add state machine tests for IRC protocol +* Create TLA+ specifications for concurrency +* *Effort*: Medium (2-4 weeks) +* *Impact*: High (improves correctness) + +==== Path 2: Multi-Language Support + +* Add TypeScript/ReScript client library +* Rust-based performance daemon variant +* *Effort*: High (4-8 weeks) +* *Impact*: Medium (expands ecosystem) + +==== Path 3: Enhanced Security ✅ *Already Achieved* + +* Security scanning (Bandit) ✅ +* Dependency checking (Safety) ✅ +* CI/CD integration ✅ + +*Recommendation*: Pursue Path 1 (Formal Verification) for maximum +quality impact with reasonable effort. + +=== 🏆 Roadmap to Platinum Level + +Platinum requires 66%+ (3/4): + +==== Realistic Targets + +[arabic] +. *Conference Materials* (Easiest) +* Write talk proposal for FOSDEM/PyCon +* Create slide deck +* Submit to 3+ conferences +* *Effort*: Low (1 week) +. *Academic Paper* (Medium) +* "`Tri-Perimeter Contribution Framework: Graduated Trust in Open +Source`" +* Submit to CHI, CSCW, or OpenSym +* *Effort*: Medium (4-6 weeks) +. *CRDT/Offline-First* (Aspirational) +* Design offline message queue +* Implement CRDT for channel state +* *Effort*: High (8-12 weeks) + +*Recommendation*: Target Conference Materials + Academic Paper for +realistic Platinum achievement. + +=== 📞 Contact + +Questions about RSR compliance: - *Email*: dev@vext.dev - *Issues*: +https://github.com/Hyperpolymath/vext/issues - *Discussions*: +https://github.com/Hyperpolymath/vext/discussions + +=== 📚 References + +* https://rhodium.sh[Rhodium Standard Repository] (hypothetical) +* https://www.rfc-editor.org/rfc/rfc9116.html[RFC 9116: security.txt] +* https://palimpsest.license[Palimpsest License] (hypothetical) +* link:governance/PROJECT_GOVERNANCE.md[Tri-Perimeter Contribution +Framework] + +=== 📄 Appendices + +==== Appendix A: File Checklist + +.... +✅ README.md +✅ LICENSE +✅ SECURITY.md +✅ CONTRIBUTING.md +✅ CODE_OF_CONDUCT.md +✅ MAINTAINERS.md +✅ CHANGELOG.md +✅ .well-known/security.txt +✅ .well-known/ai.txt +✅ .well-known/humans.txt +✅ Justfile +✅ flake.nix +✅ .gitlab-ci.yml +✅ .gitignore +✅ governance/PROJECT_GOVERNANCE.md +✅ tests/test_placeholder.py +✅ DOCUMENTATION_INDEX.md +✅ RSR_COMPLIANCE.md (this file) +✅ tools/rsr_checker.py +.... + +==== Appendix B: SPDX Identifiers + +All source files include: + +.... +SPDX-License-Identifier: CC-BY-SA-4.0 +.... + +==== Appendix C: Compliance Evidence + +Evidence of compliance is available at: - Repository: +https://github.com/Hyperpolymath/vext - CI/CD Reports: GitLab CI +pipelines - RSR Checker Output: `+rsr_compliance.json+` + +''''' + +*Document Version*: 1.0 *Last Updated*: 2025-01-01 *Next Assessment*: +2025-04-01 *Maintained By*: vext Core Team + +*Compliance Level Achieved*: 🥈 *SILVER* (100% Bronze + 100% Silver) diff --git a/vext/RSR_COMPLIANCE.md b/vext/RSR_COMPLIANCE.md deleted file mode 100644 index 76b60e5..0000000 --- a/vext/RSR_COMPLIANCE.md +++ /dev/null @@ -1,416 +0,0 @@ - -# RSR Compliance Assessment - -**SPDX-License-Identifier: CC-BY-SA-4.0 - -**Project**: vext (Rhodium Standard Edition of irker) -**Assessment Date**: 2025-01-01 -**Assessor**: vext Team -**Tool**: `tools/rsr_checker.py` - -## 📊 Executive Summary - -| Level | Score | Status | -| ----- | ----- | ------ | -| **Bronze** | 18/18 (100%) | ✅ **PERFECT** | -| **Silver** | 6/6 (100%) | ✅ **PERFECT** | -| **Gold** | 1/3 (33%) | ⚠️ Partial | -| **Platinum** | 0/4 (0%) | ⏳ Future | - -**Overall Compliance Level**: 🥈 **SILVER** - -vext has achieved **100% Silver Level compliance**, demonstrating comprehensive documentation, security practices, reproducible builds, and automated compliance verification. - -## 🏅 Achievement Badges - -```markdown -![RSR Compliance](https://img.shields.io/badge/RSR-Silver-silver) -![Bronze Level](https://img.shields.io/badge/Bronze-100%25-orange) -![Silver Level](https://img.shields.io/badge/Silver-100%25-silver) -``` - -## 📋 Detailed Assessment - -### ✅ Bronze Level (18/18 - 100%) - -Bronze level establishes foundational documentation, security policies, build systems, and community governance. - -| # | Requirement | Status | Location | -| - | ----------- | ------ | -------- | -| 1 | README.md with comprehensive content | ✅ | `README.md` | -| 2 | LICENSE with SPDX identifier | ✅ | `LICENSE` | -| 3 | SECURITY.md with vulnerability disclosure | ✅ | `SECURITY.md` | -| 4 | CONTRIBUTING.md | ✅ | `CONTRIBUTING.md` | -| 5 | CODE_OF_CONDUCT.md | ✅ | `CODE_OF_CONDUCT.md` | -| 6 | MAINTAINERS.md | ✅ | `MAINTAINERS.md` | -| 7 | CHANGELOG.md | ✅ | `CHANGELOG.md` | -| 8 | .well-known/security.txt (RFC 9116) | ✅ | `.well-known/security.txt` | -| 9 | .well-known/ai.txt | ✅ | `.well-known/ai.txt` | -| 10 | .well-known/humans.txt | ✅ | `.well-known/humans.txt` | -| 11 | Build system (Justfile) | ✅ | `justfile` | -| 12 | Nix flakes (flake.nix) | ✅ | `flake.nix` | -| 13 | CI/CD (.gitlab-ci.yml) | ✅ | `.gitlab-ci.yml` | -| 14 | TPCF governance documentation | ✅ | `governance/PROJECT_GOVERNANCE.md` | -| 15 | .gitignore | ✅ | `.gitignore` | -| 16 | Test structure | ✅ | `tests/` | -| 17 | Documentation index | ✅ | `DOCUMENTATION_INDEX.md` | -| 18 | Project metadata | ✅ | (Python project structure) | - -#### Bronze Level Highlights - -**Documentation Excellence**: -- 8 comprehensive documentation files (3,618 total lines) -- README, INSTALLATION_GUIDE, USAGE_GUIDE, FEATURES, TECHNOLOGY_STACK -- Clear navigation via DOCUMENTATION_INDEX.md -- Multiple audience levels (users, developers, deployers) - -**Security Foundations**: -- RFC 9116 compliant `.well-known/security.txt` -- Comprehensive SECURITY.md with response times -- Multiple contact methods (email, GitHub advisories) -- Clear vulnerability disclosure process - -**Community Infrastructure**: -- Code of Conduct with emotional safety framework -- Contribution guidelines with TPCF model -- Maintainer documentation with clear roles -- Tri-Perimeter Contribution Framework (TPCF) - -**Build Automation**: -- Justfile with 40+ recipes -- Nix flakes for reproducible builds -- GitLab CI/CD with multi-stage pipeline -- Automated testing and linting - -### ✅ Silver Level (6/6 - 100%) - -Silver level adds automated compliance checking, advanced documentation, dual licensing, and comprehensive .well-known directory. - -| # | Requirement | Status | Location | -| - | ----------- | ------ | -------- | -| 1 | RSR compliance checker tool | ✅ | `tools/rsr_checker.py` | -| 2 | RSR compliance documentation | ✅ | `RSR_COMPLIANCE.md` (this file) | -| 3 | Palimpsest dual licensing | ✅ | `LICENSE` | -| 4 | Complete .well-known directory | ✅ | `.well-known/` | -| 5 | Advanced documentation suite | ✅ | Multiple guides (8 files) | -| 6 | Nix flakes with full configuration | ✅ | `flake.nix` | - -#### Silver Level Highlights - -**Automated Compliance Verification**: -- Python-based RSR checker (`tools/rsr_checker.py`) -- Supports Bronze, Silver, Gold, Platinum levels -- JSON export for CI/CD integration -- Badge generation for README -- Command-line interface with detailed reporting - -**Palimpsest Dual Licensing**: -- MPL-2.0 -- Clear SPDX identifier: `SPDX-License-Identifier: CC-BY-SA-4.0` -- Comprehensive LICENSE file explaining both options -- Guidance on when to choose each license -- Patent grants and trademark notices - -**Complete .well-known Directory**: -- `security.txt` - RFC 9116 compliant security contact -- `ai.txt` - AI training policy (allowed with conditions) -- `humans.txt` - Team attribution and project info - -**Advanced Documentation**: -- 8 comprehensive guides totaling 3,618 lines -- Installation, usage, features, technology stack -- Project overview and research summary -- Documentation index for navigation -- Multiple formats (Markdown, future HTML) - -**Reproducible Builds**: -- Nix flakes with inputs/outputs -- Development shell with tools pre-configured -- NixOS module for system-wide deployment -- Build checks and CI integration - -### ⚠️ Gold Level (1/3 - 33%) - -Gold level requires formal verification, multi-language support, or advanced security features. - -| # | Requirement | Status | Location | -| - | ----------- | ------ | -------- | -| 1 | Formal verification or property-based testing | ❌ | Future work | -| 2 | Multi-language support (2+ languages) | ❌ | Python only (currently) | -| 3 | Advanced security features | ✅ | CI/CD security scanning | - -#### Gold Level Partial Achievement - -**Advanced Security** (✅ Achieved): -- Bandit security scanner in CI/CD -- Safety dependency vulnerability checker -- Secret scanning in GitLab CI -- SPDX license identifier checking -- Automated security reporting - -**Opportunities for Improvement**: - -1. **Formal Verification** (Future): - - Add property-based testing with Hypothesis - - Formal protocol specifications - - State machine verification - - TLA+ specifications for concurrent behavior - -2. **Multi-Language Support** (Potential): - - ReScript/Rescript for type-safe client - - Rust for high-performance daemon - - Ada/SPARK for formally verified core - - Elixir for distributed message routing - -### ⏳ Platinum Level (0/4 - 0%) - -Platinum level represents research-grade achievements and advanced distributed systems capabilities. - -| # | Requirement | Status | Location | -| - | ----------- | ------ | -------- | -| 1 | CRDT or offline-first architecture | ❌ | Future work | -| 2 | Academic paper | ❌ | Future work | -| 3 | Conference materials | ❌ | Future work | -| 4 | iSOS integration | ❌ | Future work | - -#### Platinum Level Roadmap - -**CRDT/Offline-First** (Future): -- Conflict-free channel state replication -- Offline message queuing -- Eventually consistent delivery -- CADRE architecture integration - -**Academic Paper** (Potential Topics): -- "IRC Notification Reliability: Formal Analysis" -- "Graduated Trust Models for Open Source Projects" -- "Emotional Safety Metrics in Code Review" - -**Conference Materials** (Potential Venues): -- FOSDEM (Developer Room: Collaboration & Communication) -- PyCon (IRC infrastructure) -- OSCON (Open Source Governance) - -**iSOS Integration** (Future): -- Multi-language verification across components -- Compositional correctness proofs -- FFI contract system -- WASM sandboxing for extensions - -## 🎯 Compliance Verification - -### Automated Checking - -Run the RSR compliance checker: - -```bash -# Basic check -just rsr-check - -# Or directly -python3 tools/rsr_checker.py . - -# JSON export -just rsr-check-json - -# Generate badge -just rsr-badge -``` - -### Manual Verification - -All compliance requirements can be manually verified: - -```bash -# Check documentation -ls -lh *.md governance/*.md .well-known/ - -# Check build systems -ls -lh Justfile flake.nix .gitlab-ci.yml - -# Check tests -pytest tests/ -v - -# Check Nix builds -nix build -nix flake check -``` - -## 📈 Compliance Metrics - -### Documentation Coverage - -| Category | Files | Lines | Status | -| -------- | ----- | ----- | ------ | -| Core Documentation | 8 | 3,618 | ✅ Complete | -| Security Policies | 2 | 500+ | ✅ Complete | -| Community Governance | 3 | 800+ | ✅ Complete | -| Build Configuration | 3 | 600+ | ✅ Complete | -| .well-known | 3 | 300+ | ✅ Complete | - -### Security Posture - -| Aspect | Implementation | Status | -| ------ | -------------- | ------ | -| RFC 9116 security.txt | ✅ Yes | Complete | -| Vulnerability disclosure | ✅ Documented | Complete | -| Response times | ✅ Defined | Complete | -| Security scanning | ✅ Automated | Complete | -| Dependency checking | ✅ CI/CD | Complete | -| SPDX identifiers | ✅ All files | Complete | - -### Build & Testing - -| Aspect | Implementation | Status | -| ------ | -------------- | ------ | -| Build automation | just, Make, Nix | ✅ Complete | -| CI/CD pipeline | GitLab CI (5 stages) | ✅ Complete | -| Test framework | pytest + unittest | ✅ Basic | -| Test coverage | Placeholder tests | ⚠️ Need expansion | -| Reproducible builds | Nix flakes | ✅ Complete | -| NixOS module | System-wide deployment | ✅ Complete | - -## 🔄 Continuous Compliance - -### Maintenance Schedule - -- **Weekly**: Automated compliance checks in CI/CD -- **Monthly**: Review and update documentation -- **Quarterly**: Comprehensive RSR assessment -- **Annually**: Full governance and security review - -### CI/CD Integration - -RSR compliance is checked automatically: - -```yaml -# .gitlab-ci.yml -compliance:rsr: - script: - - python tools/rsr_checker.py . --json --badge - artifacts: - paths: - - rsr_compliance.json -``` - -### Badge Integration - -Add to README.md: - -```markdown -![RSR Compliance](https://img.shields.io/badge/RSR-Silver-silver) -``` - -## 🚀 Roadmap to Gold Level - -To achieve Gold level (66%+ of Gold requirements), we need 2/3: - -### Path 1: Formal Verification ⭐ **Recommended** -- Implement property-based testing with Hypothesis -- Add state machine tests for IRC protocol -- Create TLA+ specifications for concurrency -- **Effort**: Medium (2-4 weeks) -- **Impact**: High (improves correctness) - -### Path 2: Multi-Language Support -- Add TypeScript/ReScript client library -- Rust-based performance daemon variant -- **Effort**: High (4-8 weeks) -- **Impact**: Medium (expands ecosystem) - -### Path 3: Enhanced Security ✅ **Already Achieved** -- Security scanning (Bandit) ✅ -- Dependency checking (Safety) ✅ -- CI/CD integration ✅ - -**Recommendation**: Pursue Path 1 (Formal Verification) for maximum quality impact with reasonable effort. - -## 🏆 Roadmap to Platinum Level - -Platinum requires 66%+ (3/4): - -### Realistic Targets - -1. **Conference Materials** (Easiest) - - Write talk proposal for FOSDEM/PyCon - - Create slide deck - - Submit to 3+ conferences - - **Effort**: Low (1 week) - -2. **Academic Paper** (Medium) - - "Tri-Perimeter Contribution Framework: Graduated Trust in Open Source" - - Submit to CHI, CSCW, or OpenSym - - **Effort**: Medium (4-6 weeks) - -3. **CRDT/Offline-First** (Aspirational) - - Design offline message queue - - Implement CRDT for channel state - - **Effort**: High (8-12 weeks) - -**Recommendation**: Target Conference Materials + Academic Paper for realistic Platinum achievement. - -## 📞 Contact - -Questions about RSR compliance: -- **Email**: dev@vext.dev -- **Issues**: https://github.com/Hyperpolymath/vext/issues -- **Discussions**: https://github.com/Hyperpolymath/vext/discussions - -## 📚 References - -- [Rhodium Standard Repository](https://rhodium.sh) (hypothetical) -- [RFC 9116: security.txt](https://www.rfc-editor.org/rfc/rfc9116.html) -- [Palimpsest License](https://palimpsest.license) (hypothetical) -- [Tri-Perimeter Contribution Framework](governance/PROJECT_GOVERNANCE.md) - -## 📄 Appendices - -### Appendix A: File Checklist - -``` -✅ README.md -✅ LICENSE -✅ SECURITY.md -✅ CONTRIBUTING.md -✅ CODE_OF_CONDUCT.md -✅ MAINTAINERS.md -✅ CHANGELOG.md -✅ .well-known/security.txt -✅ .well-known/ai.txt -✅ .well-known/humans.txt -✅ Justfile -✅ flake.nix -✅ .gitlab-ci.yml -✅ .gitignore -✅ governance/PROJECT_GOVERNANCE.md -✅ tests/test_placeholder.py -✅ DOCUMENTATION_INDEX.md -✅ RSR_COMPLIANCE.md (this file) -✅ tools/rsr_checker.py -``` - -### Appendix B: SPDX Identifiers - -All source files include: -``` -SPDX-License-Identifier: CC-BY-SA-4.0 -``` - -### Appendix C: Compliance Evidence - -Evidence of compliance is available at: -- Repository: https://github.com/Hyperpolymath/vext -- CI/CD Reports: GitLab CI pipelines -- RSR Checker Output: `rsr_compliance.json` - ---- - -**Document Version**: 1.0 -**Last Updated**: 2025-01-01 -**Next Assessment**: 2025-04-01 -**Maintained By**: vext Core Team - -**Compliance Level Achieved**: 🥈 **SILVER** (100% Bronze + 100% Silver) diff --git a/vext/SECURITY.adoc b/vext/SECURITY.adoc new file mode 100644 index 0000000..e9b252b --- /dev/null +++ b/vext/SECURITY.adoc @@ -0,0 +1,203 @@ +== Security Policy + +**SPDX-License-Identifier: CC-BY-SA-4.0 + +=== 🛡️ Security Overview + +vext (Rhodium Standard Edition of irker) takes security seriously. This +document outlines our security policies, vulnerability disclosure +process, and supported versions. + +=== 📋 Supported Versions + +We provide security updates for the following versions: + +[cols=",,",options="header",] +|=== +|Version |Supported |End of Life +|1.x |✅ Yes |TBD +|0.x |⚠️ Best effort |2025-12-31 +|=== + +=== 🔒 Security Features + +vext implements multiple layers of security: + +==== Network Security + +* *Rate Limiting*: Prevents IRC flooding and abuse +* *Connection Pooling*: Limits concurrent connections +* *Input Validation*: Sanitizes all user-provided data +* *Protocol Enforcement*: Strict IRC RFC 1459 compliance + +==== Process Security + +* *Privilege Separation*: Runs with minimal required permissions +* *Sandboxing*: Optional systemd sandboxing support +* *Resource Limits*: Memory and CPU usage constraints +* *Safe Defaults*: Secure configuration out-of-the-box + +==== Data Security + +* *No Credential Storage*: Never stores IRC passwords +* *Transport Security*: Optional TLS/SSL support +* *Logging Controls*: Configurable log sanitization +* *Audit Trail*: Comprehensive security event logging + +==== Code Security + +* *Memory Safety*: Python’s built-in memory safety +* *Dependency Minimalism*: Minimal external dependencies +* *Static Analysis*: Automated security scanning (bandit, semgrep) +* *Code Review*: All changes reviewed before merge + +=== 🔍 Vulnerability Disclosure + +==== Reporting a Vulnerability + +*DO NOT* open public GitHub/GitLab issues for security vulnerabilities. + +Instead, please report security issues privately: + +*Primary Contact:* - Email: security@vext.dev (PGP: 0x1234567890ABCDEF) +- Response time: Within 48 hours + +*Alternative Contacts:* - security.txt: See `+.well-known/security.txt+` +(RFC 9116 compliant) - Matrix: @security:vext.dev - Signal: Available +upon request + +==== What to Include + +When reporting vulnerabilities, please include: + +[arabic] +. *Description*: Clear description of the vulnerability +. *Impact*: Potential security impact and attack scenarios +. *Reproduction*: Step-by-step reproduction instructions +. *Environment*: Version, OS, configuration details +. *PoC*: Proof-of-concept code (if available) +. *Suggestions*: Proposed fixes or mitigations (optional) + +==== Response Process + +[arabic] +. *Acknowledgment* (24-48 hours) +* We’ll confirm receipt of your report +* Assign a tracking number +* Provide initial assessment timeline +. *Investigation* (1-7 days) +* Verify and reproduce the vulnerability +* Assess severity and impact +* Develop and test fixes +. *Resolution* (7-30 days) +* Prepare security patch +* Coordinate disclosure timeline +* Release fixed version +. *Disclosure* (After fix release) +* Public security advisory +* CVE assignment (if applicable) +* Credit to reporter (if desired) + +==== Severity Classification + +We use CVSS 3.1 for severity ratings: + +[cols=",,,",options="header",] +|=== +|Severity |CVSS Score |Response Time |Fix Timeline +|Critical |9.0-10.0 |24 hours |7 days +|High |7.0-8.9 |48 hours |14 days +|Medium |4.0-6.9 |7 days |30 days +|Low |0.1-3.9 |14 days |90 days +|=== + +=== 🏆 Security Rewards + +We appreciate security researchers who help keep vext secure: + +* *Hall of Fame*: Public acknowledgment in SECURITY_CREDITS.md +* *Swag*: vext t-shirts, stickers, and merchandise +* *Early Access*: Beta access to new features +* *Consulting*: Opportunity to consult on security features + +We do not currently offer monetary bug bounties, but we deeply value and +acknowledge all security contributions. + +=== ✅ Security Best Practices + +==== For Deployers + +[arabic] +. *Keep Updated*: Always run the latest version +. *Restrict Access*: Limit who can send notifications +. *Monitor Logs*: Enable security event logging +. *Use TLS*: Enable TLS for IRC connections when possible +. *Firewall Rules*: Restrict network access appropriately +. *Sandboxing*: Use systemd sandboxing in production +. *Rate Limits*: Configure appropriate rate limits +. *Least Privilege*: Run with minimal required permissions + +==== For Developers + +[arabic] +. *Review Changes*: All code changes undergo security review +. *Test Thoroughly*: Include security test cases +. *Validate Input*: Sanitize all external input +. *Avoid Secrets*: Never commit credentials or keys +. *Dependencies*: Keep dependencies minimal and updated +. *Static Analysis*: Run security scanners before commits +. *Secure Defaults*: Configuration defaults should be secure + +=== 🔐 Cryptographic Disclosure + +vext does not implement custom cryptography. When encryption is needed: + +* *TLS/SSL*: Uses Python’s `+ssl+` module (OpenSSL) +* *Random Numbers*: Uses `+secrets+` module for CSPRNG +* *Hashing*: Uses `+hashlib+` for non-cryptographic hashing + +=== 📜 Compliance + +vext follows these security standards: + +* *RFC 9116*: `+.well-known/security.txt+` (security contact +information) +* *CWE*: Common Weakness Enumeration awareness +* *OWASP Top 10*: Protection against common vulnerabilities +* *CVE*: CVE assignment for significant vulnerabilities + +=== 🔗 Security Resources + +* *Security.txt*: `+.well-known/security.txt+` (RFC 9116) +* *PGP Keys*: `+docs/security/pgp-keys.asc+` +* *Security Advisories*: `+docs/security/advisories/+` +* *Security Credits*: `+SECURITY_CREDITS.md+` +* *Hardening Guide*: `+docs/security/HARDENING.md+` + +=== 📞 Contact Information + +* *Security Team*: security@vext.dev +* *Security.txt*: `+.well-known/security.txt+` +* *PGP Fingerprint*: 1234 5678 90AB CDEF 1234 5678 90AB CDEF 1234 5678 +* *Expires*: See `+.well-known/security.txt+` for current expiration + +=== 📄 Security Audit History + +[cols=",,,,",options="header",] +|=== +|Date |Auditor |Scope |Findings |Status +|2025-01-15 |Internal |Full codebase |0 High |Completed +|=== + +=== 🔄 Policy Updates + +This security policy is reviewed quarterly and updated as needed. + +*Last Updated*: 2025-01-01 *Next Review*: 2025-04-01 *Version*: 1.0 + +''''' + +*Thank you for helping keep vext secure!* 🙏 + +For general questions, see CONTRIBUTING.md. For security questions, +contact: security@vext.dev diff --git a/vext/SECURITY.md b/vext/SECURITY.md deleted file mode 100644 index 52a560d..0000000 --- a/vext/SECURITY.md +++ /dev/null @@ -1,196 +0,0 @@ - -# Security Policy - -**SPDX-License-Identifier: CC-BY-SA-4.0 - -## 🛡️ Security Overview - -vext (Rhodium Standard Edition of irker) takes security seriously. This document outlines our security policies, vulnerability disclosure process, and supported versions. - -## 📋 Supported Versions - -We provide security updates for the following versions: - -| Version | Supported | End of Life | -| ------- | ------------------ | ----------- | -| 1.x | ✅ Yes | TBD | -| 0.x | ⚠️ Best effort | 2025-12-31 | - -## 🔒 Security Features - -vext implements multiple layers of security: - -### Network Security -- **Rate Limiting**: Prevents IRC flooding and abuse -- **Connection Pooling**: Limits concurrent connections -- **Input Validation**: Sanitizes all user-provided data -- **Protocol Enforcement**: Strict IRC RFC 1459 compliance - -### Process Security -- **Privilege Separation**: Runs with minimal required permissions -- **Sandboxing**: Optional systemd sandboxing support -- **Resource Limits**: Memory and CPU usage constraints -- **Safe Defaults**: Secure configuration out-of-the-box - -### Data Security -- **No Credential Storage**: Never stores IRC passwords -- **Transport Security**: Optional TLS/SSL support -- **Logging Controls**: Configurable log sanitization -- **Audit Trail**: Comprehensive security event logging - -### Code Security -- **Memory Safety**: Python's built-in memory safety -- **Dependency Minimalism**: Minimal external dependencies -- **Static Analysis**: Automated security scanning (bandit, semgrep) -- **Code Review**: All changes reviewed before merge - -## 🔍 Vulnerability Disclosure - -### Reporting a Vulnerability - -**DO NOT** open public GitHub/GitLab issues for security vulnerabilities. - -Instead, please report security issues privately: - -**Primary Contact:** -- Email: security@vext.dev (PGP: 0x1234567890ABCDEF) -- Response time: Within 48 hours - -**Alternative Contacts:** -- security.txt: See `.well-known/security.txt` (RFC 9116 compliant) -- Matrix: @security:vext.dev -- Signal: Available upon request - -### What to Include - -When reporting vulnerabilities, please include: - -1. **Description**: Clear description of the vulnerability -2. **Impact**: Potential security impact and attack scenarios -3. **Reproduction**: Step-by-step reproduction instructions -4. **Environment**: Version, OS, configuration details -5. **PoC**: Proof-of-concept code (if available) -6. **Suggestions**: Proposed fixes or mitigations (optional) - -### Response Process - -1. **Acknowledgment** (24-48 hours) - - We'll confirm receipt of your report - - Assign a tracking number - - Provide initial assessment timeline - -2. **Investigation** (1-7 days) - - Verify and reproduce the vulnerability - - Assess severity and impact - - Develop and test fixes - -3. **Resolution** (7-30 days) - - Prepare security patch - - Coordinate disclosure timeline - - Release fixed version - -4. **Disclosure** (After fix release) - - Public security advisory - - CVE assignment (if applicable) - - Credit to reporter (if desired) - -### Severity Classification - -We use CVSS 3.1 for severity ratings: - -| Severity | CVSS Score | Response Time | Fix Timeline | -| -------- | ---------- | ------------- | ------------ | -| Critical | 9.0-10.0 | 24 hours | 7 days | -| High | 7.0-8.9 | 48 hours | 14 days | -| Medium | 4.0-6.9 | 7 days | 30 days | -| Low | 0.1-3.9 | 14 days | 90 days | - -## 🏆 Security Rewards - -We appreciate security researchers who help keep vext secure: - -- **Hall of Fame**: Public acknowledgment in SECURITY_CREDITS.md -- **Swag**: vext t-shirts, stickers, and merchandise -- **Early Access**: Beta access to new features -- **Consulting**: Opportunity to consult on security features - -We do not currently offer monetary bug bounties, but we deeply value and acknowledge all security contributions. - -## ✅ Security Best Practices - -### For Deployers - -1. **Keep Updated**: Always run the latest version -2. **Restrict Access**: Limit who can send notifications -3. **Monitor Logs**: Enable security event logging -4. **Use TLS**: Enable TLS for IRC connections when possible -5. **Firewall Rules**: Restrict network access appropriately -6. **Sandboxing**: Use systemd sandboxing in production -7. **Rate Limits**: Configure appropriate rate limits -8. **Least Privilege**: Run with minimal required permissions - -### For Developers - -1. **Review Changes**: All code changes undergo security review -2. **Test Thoroughly**: Include security test cases -3. **Validate Input**: Sanitize all external input -4. **Avoid Secrets**: Never commit credentials or keys -5. **Dependencies**: Keep dependencies minimal and updated -6. **Static Analysis**: Run security scanners before commits -7. **Secure Defaults**: Configuration defaults should be secure - -## 🔐 Cryptographic Disclosure - -vext does not implement custom cryptography. When encryption is needed: - -- **TLS/SSL**: Uses Python's `ssl` module (OpenSSL) -- **Random Numbers**: Uses `secrets` module for CSPRNG -- **Hashing**: Uses `hashlib` for non-cryptographic hashing - -## 📜 Compliance - -vext follows these security standards: - -- **RFC 9116**: `.well-known/security.txt` (security contact information) -- **CWE**: Common Weakness Enumeration awareness -- **OWASP Top 10**: Protection against common vulnerabilities -- **CVE**: CVE assignment for significant vulnerabilities - -## 🔗 Security Resources - -- **Security.txt**: `.well-known/security.txt` (RFC 9116) -- **PGP Keys**: `docs/security/pgp-keys.asc` -- **Security Advisories**: `docs/security/advisories/` -- **Security Credits**: `SECURITY_CREDITS.md` -- **Hardening Guide**: `docs/security/HARDENING.md` - -## 📞 Contact Information - -- **Security Team**: security@vext.dev -- **Security.txt**: `.well-known/security.txt` -- **PGP Fingerprint**: 1234 5678 90AB CDEF 1234 5678 90AB CDEF 1234 5678 -- **Expires**: See `.well-known/security.txt` for current expiration - -## 📄 Security Audit History - -| Date | Auditor | Scope | Findings | Status | -| ---------- | ---------------- | ------------ | -------- | --------- | -| 2025-01-15 | Internal | Full codebase| 0 High | Completed | - -## 🔄 Policy Updates - -This security policy is reviewed quarterly and updated as needed. - -**Last Updated**: 2025-01-01 -**Next Review**: 2025-04-01 -**Version**: 1.0 - ---- - -**Thank you for helping keep vext secure!** 🙏 - -For general questions, see [CONTRIBUTING.md](CONTRIBUTING.md). -For security questions, contact: security@vext.dev diff --git a/vext/TECHNOLOGY_STACK.md b/vext/TECHNOLOGY_STACK.adoc similarity index 56% rename from vext/TECHNOLOGY_STACK.md rename to vext/TECHNOLOGY_STACK.adoc index c16936c..adc9093 100644 --- a/vext/TECHNOLOGY_STACK.md +++ b/vext/TECHNOLOGY_STACK.adoc @@ -1,76 +1,72 @@ - -# vext Technology Stack +== vext Technology Stack -## Overview +=== Overview -vext uses a hybrid architecture combining Rust for the high-performance daemon and Deno/TypeScript for developer-friendly hooks and tooling. +vext uses a hybrid architecture combining Rust for the high-performance +daemon and Deno/TypeScript for developer-friendly hooks and tooling. -## Languages & Runtimes +=== Languages & Runtimes -### Rust (vext-core) +==== Rust (vext-core) -**Role**: High-performance IRC notification daemon +*Role*: High-performance IRC notification daemon -- **Version**: Rust 1.70+ (2021 edition) -- **Runtime**: Native binary (no runtime dependencies) -- **Build Tool**: Cargo +* *Version*: Rust 1.70+ (2021 edition) +* *Runtime*: Native binary (no runtime dependencies) +* *Build Tool*: Cargo -**Key Advantages**: -- Memory safety without garbage collection -- Zero-cost abstractions -- Excellent async/await support via Tokio -- Single binary deployment -- Cross-compilation support +*Key Advantages*: - Memory safety without garbage collection - Zero-cost +abstractions - Excellent async/await support via Tokio - Single binary +deployment - Cross-compilation support -### TypeScript/Deno (vext-tools) +==== TypeScript/Deno (vext-tools) -**Role**: Hook scripts, CLI utilities, configuration tools +*Role*: Hook scripts, CLI utilities, configuration tools -- **Runtime**: Deno 1.40+ -- **Type Safety**: Full TypeScript with strict mode -- **Permissions**: Explicit security permissions model +* *Runtime*: Deno 1.40+ +* *Type Safety*: Full TypeScript with strict mode +* *Permissions*: Explicit security permissions model -**Key Advantages**: -- Modern JavaScript/TypeScript runtime -- Built-in TypeScript support (no transpilation step) -- Secure by default (explicit permissions) -- Single-file scripts with URL imports -- Excellent cross-platform support +*Key Advantages*: - Modern JavaScript/TypeScript runtime - Built-in +TypeScript support (no transpilation step) - Secure by default (explicit +permissions) - Single-file scripts with URL imports - Excellent +cross-platform support -## Core Dependencies +=== Core Dependencies -### Rust Dependencies (vext-core) +==== Rust Dependencies (vext-core) -| Crate | Version | Purpose | -|-------|---------|---------| -| `tokio` | 1.35 | Async runtime and I/O | -| `irc` | 0.15 | IRC protocol implementation | -| `serde` | 1.0 | Serialization/deserialization | -| `serde_json` | 1.0 | JSON parsing | -| `toml` | 0.8 | TOML configuration files | -| `clap` | 4.4 | Command-line argument parsing | -| `tracing` | 0.1 | Structured logging | -| `native-tls` | 0.2 | TLS support | -| `trust-dns-resolver` | 0.23 | DNS resolution (SRV records) | -| `thiserror` | 1.0 | Error type derivation | -| `anyhow` | 1.0 | Error handling | +[cols=",,",options="header",] +|=== +|Crate |Version |Purpose +|`+tokio+` |1.35 |Async runtime and I/O +|`+irc+` |0.15 |IRC protocol implementation +|`+serde+` |1.0 |Serialization/deserialization +|`+serde_json+` |1.0 |JSON parsing +|`+toml+` |0.8 |TOML configuration files +|`+clap+` |4.4 |Command-line argument parsing +|`+tracing+` |0.1 |Structured logging +|`+native-tls+` |0.2 |TLS support +|`+trust-dns-resolver+` |0.23 |DNS resolution (SRV records) +|`+thiserror+` |1.0 |Error type derivation +|`+anyhow+` |1.0 |Error handling +|=== -### Deno Dependencies (vext-tools) +==== Deno Dependencies (vext-tools) -| Module | Source | Purpose | -|--------|--------|---------| -| `@std/path` | JSR | Path manipulation | -| `@std/fs` | JSR | File system operations | -| `@std/cli` | JSR | CLI argument parsing | +[cols=",,",options="header",] +|=== +|Module |Source |Purpose +|`+@std/path+` |JSR |Path manipulation +|`+@std/fs+` |JSR |File system operations +|`+@std/cli+` |JSR |CLI argument parsing +|=== -## Architecture +=== Architecture -### vext-core (Rust Daemon) +==== vext-core (Rust Daemon) -``` +.... ┌─────────────────────────────────────────────────────────┐ │ vextd │ ├─────────────────────────────────────────────────────────┤ @@ -92,11 +88,11 @@ vext uses a hybrid architecture combining Rust for the high-performance daemon a │ │ Token Bucket Algorithm (per-server) │ │ │ └─────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ -``` +.... -### vext-tools (Deno Hooks) +==== vext-tools (Deno Hooks) -``` +.... ┌─────────────────────────────────────────────────────────┐ │ Git Repository │ ├─────────────────────────────────────────────────────────┤ @@ -120,13 +116,14 @@ vext uses a hybrid architecture combining Rust for the high-performance daemon a └───────────────────┼─────────────────────────────────────┘ ▼ vextd daemon -``` +.... -## Communication Protocol +=== Communication Protocol -### JSON Notification Format +==== JSON Notification Format -```json +[source,json] +---- { "to": ["ircs://server/channel"], "privmsg": "Message text", @@ -137,22 +134,25 @@ vext uses a hybrid architecture combining Rust for the high-performance daemon a "url": "https://example.com/commit/abc1234", "colors": "mirc" } -``` +---- -### IRC URL Schema +==== IRC URL Schema -| URL Format | Description | -|------------|-------------| -| `irc://server/channel` | Plain IRC (port 6667) | -| `ircs://server/channel` | TLS IRC (port 6697) | -| `irc://server:port/channel` | Custom port | -| `irc://server/channel?key=pass` | Channel with key | +[cols=",",options="header",] +|=== +|URL Format |Description +|`+irc://server/channel+` |Plain IRC (port 6667) +|`+ircs://server/channel+` |TLS IRC (port 6697) +|`+irc://server:port/channel+` |Custom port +|`+irc://server/channel?key=pass+` |Channel with key +|=== -## Build System +=== Build System -### Cargo (Rust) +==== Cargo (Rust) -```toml +[source,toml] +---- [workspace] members = ["vext-core"] resolver = "2" @@ -162,11 +162,12 @@ lto = true codegen-units = 1 panic = "abort" strip = true -``` +---- -### Deno (TypeScript) +==== Deno (TypeScript) -```json +[source,json] +---- { "tasks": { "build": "deno check src/**/*.ts", @@ -174,68 +175,72 @@ strip = true "hook:git": "deno run --allow-net --allow-env --allow-read src/hooks/git.ts" } } -``` +---- -### Just (Task Runner) +==== Just (Task Runner) -Common tasks via [just](https://github.com/casey/just): +Common tasks via https://github.com/casey/just[just]: -```bash +[source,bash] +---- just build # Build all components just test # Run all tests just lint # Run linters just format # Format code just validate # Full CI check -``` +---- -## Security Considerations +=== Security Considerations -### Rust (vext-core) +==== Rust (vext-core) -- Memory-safe by design -- No unsafe code in critical paths -- TLS enabled by default -- Rate limiting prevents flood attacks -- Sandboxed IRC commands (no arbitrary execution) +* Memory-safe by design +* No unsafe code in critical paths +* TLS enabled by default +* Rate limiting prevents flood attacks +* Sandboxed IRC commands (no arbitrary execution) -### Deno (vext-tools) +==== Deno (vext-tools) -- Explicit permission model -- Only `--allow-net`, `--allow-read`, `--allow-env` required -- No arbitrary file system access -- URL imports verified by integrity checks +* Explicit permission model +* Only `+--allow-net+`, `+--allow-read+`, `+--allow-env+` required +* No arbitrary file system access +* URL imports verified by integrity checks -## Platform Support +=== Platform Support -| Platform | vext-core | vext-tools | -|----------|-----------|------------| -| Linux x86_64 | Full | Full | -| Linux ARM64 | Full | Full | -| macOS x86_64 | Full | Full | -| macOS ARM64 | Full | Full | -| Windows | Partial | Full | -| FreeBSD | Full | Partial | +[cols=",,",options="header",] +|=== +|Platform |vext-core |vext-tools +|Linux x86_64 |Full |Full +|Linux ARM64 |Full |Full +|macOS x86_64 |Full |Full +|macOS ARM64 |Full |Full +|Windows |Partial |Full +|FreeBSD |Full |Partial +|=== -## Performance Characteristics +=== Performance Characteristics -### vext-core Daemon +==== vext-core Daemon -- **Memory**: ~5-10 MB base, ~1 MB per active connection -- **CPU**: Minimal (async I/O, event-driven) -- **Throughput**: 10,000+ notifications/second -- **Latency**: <10ms notification to IRC send +* *Memory*: ~5-10 MB base, ~1 MB per active connection +* *CPU*: Minimal (async I/O, event-driven) +* *Throughput*: 10,000+ notifications/second +* *Latency*: <10ms notification to IRC send -### Connection Pool +==== Connection Pool -- **Max Connections**: Configurable (default: 4 per server) -- **Idle Timeout**: 5 minutes (configurable) -- **Reconnection**: Automatic with exponential backoff +* *Max Connections*: Configurable (default: 4 per server) +* *Idle Timeout*: 5 minutes (configurable) +* *Reconnection*: Automatic with exponential backoff -## Development Dependencies +=== Development Dependencies -### Rust +==== Rust -```bash +[source,bash] +---- # Testing cargo install cargo-tarpaulin # Coverage cargo install cargo-audit # Security audit @@ -243,29 +248,30 @@ cargo install cargo-audit # Security audit # Linting rustup component add clippy rustup component add rustfmt -``` +---- -### Deno +==== Deno -Built-in tooling: -- `deno fmt` - Code formatting -- `deno lint` - Linting -- `deno test` - Testing -- `deno check` - Type checking +Built-in tooling: - `+deno fmt+` - Code formatting - `+deno lint+` - +Linting - `+deno test+` - Testing - `+deno check+` - Type checking -## Migration from Python +=== Migration from Python This project was migrated from Python to Rust + Deno for: -1. **Performance**: Rust's async I/O handles more connections with less memory -2. **Safety**: Memory safety and type safety reduce runtime errors -3. **Deployment**: Single binary simplifies installation -4. **Modern Tooling**: Deno provides better developer experience for scripting -5. **Policy Compliance**: RSR (Rhodium Standard Repository) language requirements +[arabic] +. *Performance*: Rust’s async I/O handles more connections with less +memory +. *Safety*: Memory safety and type safety reduce runtime errors +. *Deployment*: Single binary simplifies installation +. *Modern Tooling*: Deno provides better developer experience for +scripting +. *Policy Compliance*: RSR (Rhodium Standard Repository) language +requirements -See `.migration/PYTHON_TO_RUST_RESCRIPT.md` for migration details. +See `+.migration/PYTHON_TO_RUST_RESCRIPT.md+` for migration details. -## License +=== License -- **SPDX Identifier**: `MPL-2.0` -- **Style**: Palimpsest dual licensing +* *SPDX Identifier*: `+MPL-2.0+` +* *Style*: Palimpsest dual licensing diff --git a/vext/USAGE_GUIDE.md b/vext/USAGE_GUIDE.adoc similarity index 86% rename from vext/USAGE_GUIDE.md rename to vext/USAGE_GUIDE.adoc index a53bfe0..43dbf0b 100644 --- a/vext/USAGE_GUIDE.md +++ b/vext/USAGE_GUIDE.adoc @@ -1,14 +1,11 @@ - -# vext Usage Guide +== vext Usage Guide -## Quick Start +=== Quick Start -### 1. Start the Daemon +==== 1. Start the Daemon -```bash +[source,bash] +---- # Start vext daemon with default settings irkerd @@ -18,33 +15,37 @@ irkerd --foreground --debug # Or run as background service sudo systemctl start vext sudo systemctl status vext -``` +---- -### 2. Send Your First Notification +==== 2. Send Your First Notification -```bash +[source,bash] +---- # Send notification to IRC channel echo '{"to":"irc://irc.libera.chat/testchannel","privmsg":"Hello from vext!"}' | \ nc -u 127.0.0.1 6659 -``` +---- -### 3. Configure Repository Hook +==== 3. Configure Repository Hook For Git: -```bash + +[source,bash] +---- # Copy example hook to repository cp irkerhook.py /path/to/repo.git/hooks/post-receive chmod +x /path/to/repo.git/hooks/post-receive # Edit to set IRC channel # Then make a commit to test! -``` +---- -## Starting and Managing the Daemon +=== Starting and Managing the Daemon -### Command-Line Options +==== Command-Line Options -```bash +[source,bash] +---- # Show help irkerd --help irkerd -h @@ -75,11 +76,12 @@ irkerd --logfile /var/log/vext/vext.log # Combine options irkerd --listen 0.0.0.0 --port 6659 --debug --foreground -``` +---- -### Systemd Service Management +==== Systemd Service Management -```bash +[source,bash] +---- # Start daemon sudo systemctl start vext @@ -105,11 +107,12 @@ sudo systemctl disable vext sudo journalctl -u vext -f # Follow logs sudo journalctl -u vext -n 50 # Last 50 lines sudo journalctl -u vext -S "1 hour ago" # Last hour -``` +---- -### Manual Service Management +==== Manual Service Management -```bash +[source,bash] +---- # Start in background (manual) irkerd --pidfile /var/run/vext.pid --logfile /var/log/vext/vext.log & @@ -122,21 +125,23 @@ pkill -f irkerd # Check if running pgrep -f irkerd ps aux | grep irkerd -``` +---- -## Sending Notifications +=== Sending Notifications -### Basic Notification +==== Basic Notification -```bash +[source,bash] +---- # Simple message to single channel echo '{"to":"irc://irc.libera.chat/commits","privmsg":"New commit pushed!"}' | \ nc -u localhost 6659 -``` +---- -### Multi-Channel Notification +==== Multi-Channel Notification -```bash +[source,bash] +---- # Send to multiple channels in one request echo '{ "to": [ @@ -145,11 +150,12 @@ echo '{ ], "privmsg": "Major release v1.2.0 published!" }' | nc -u localhost 6659 -``` +---- -### With Color Formatting +==== With Color Formatting -```bash +[source,bash] +---- # ANSI color codes echo '{ "to": "irc://irc.libera.chat/commits", @@ -163,22 +169,24 @@ echo '{ "privmsg": "[abc123d] Alice: Fix critical bug", "color": "mIRC" }' | nc -u localhost 6659 -``` +---- -### Custom Bot Nickname +==== Custom Bot Nickname -```bash +[source,bash] +---- # Override default bot nick echo '{ "to": "irc://irc.libera.chat/commits", "privmsg": "Notification message", "nick": "my-custom-bot" }' | nc -u localhost 6659 -``` +---- -### Using Python Script +==== Using Python Script -```python +[source,python] +---- #!/usr/bin/env python3 import json import socket @@ -207,19 +215,21 @@ send_notification( ) print("Notification sent!") -``` +---- -### Using TCP Instead of UDP +==== Using TCP Instead of UDP -```bash +[source,bash] +---- # TCP is more reliable but slightly slower echo '{"to":"irc://irc.libera.chat/commits","privmsg":"Important message"}' | \ nc localhost 6659 # nc without -u uses TCP -``` +---- -### Using Bash Script +==== Using Bash Script -```bash +[source,bash] +---- #!/bin/bash # Configuration @@ -249,15 +259,16 @@ EOF send_irc_notification "Build started for commit abc123d" send_irc_notification "Build completed successfully" "announcements" send_irc_notification "Deployment to production failed" "alerts" -``` +---- -## Repository Hook Configuration +=== Repository Hook Configuration -### Git Configuration +==== Git Configuration -#### Basic Git Hook +===== Basic Git Hook -```python +[source,python] +---- #!/usr/bin/env python3 """ Git post-receive hook for vext notifications @@ -348,11 +359,12 @@ while True: print(f"Error processing push: {e}", file=sys.stderr) print("Git hook executed successfully") -``` +---- -#### Advanced Git Hook with Environment Configuration +===== Advanced Git Hook with Environment Configuration -```python +[source,python] +---- #!/usr/bin/env python3 """ Advanced Git hook with configuration file support @@ -423,11 +435,12 @@ def send_notification(message): # Process commits... # (same as basic example) -``` +---- -### Mercurial Configuration +==== Mercurial Configuration -```python +[source,python] +---- #!/usr/bin/env python3 """ Mercurial hook for vext notifications @@ -470,11 +483,12 @@ def notify(ui, repo, **kwargs): sock.close() except Exception as e: ui.write(f"Error sending notification: {e}\n") -``` +---- -### Subversion Configuration +==== Subversion Configuration -```bash +[source,bash] +---- #!/bin/bash # SVN post-commit hook # Save as: /path/to/repo/hooks/post-commit @@ -509,13 +523,14 @@ EOF echo "$PAYLOAD" | nc -u "$VEXT_HOST" "$VEXT_PORT" exit 0 -``` +---- -## Configuration Management +=== Configuration Management -### Environment Variables +==== Environment Variables -```bash +[source,bash] +---- # Set in shell or systemd service export IRKERD_HOST=0.0.0.0 export IRKERD_PORT=6659 @@ -524,11 +539,12 @@ export IRKERD_COLOR_MODE=ANSI export IRKERD_USE_TCP=false export IRKERD_LOGLEVEL=INFO export IRKERD_LOGFILE=/var/log/vext/vext.log -``` +---- -### Configuration File (.vext.conf) +==== Configuration File (.vext.conf) -```ini +[source,ini] +---- [daemon] host = 0.0.0.0 port = 6659 @@ -545,11 +561,12 @@ timeout = 120 color_mode = ANSI rate_limit = 2 flood_limit = 1000 -``` +---- -### Per-Repository Configuration (.vext-repo.conf) +==== Per-Repository Configuration (.vext-repo.conf) -```ini +[source,ini] +---- [vext] host = localhost port = 6659 @@ -558,13 +575,14 @@ port = 6659 server = irc.libera.chat channel = #myproject color = ANSI -``` +---- -## Monitoring and Troubleshooting +=== Monitoring and Troubleshooting -### Check Daemon Status +==== Check Daemon Status -```bash +[source,bash] +---- # Is daemon running? ps aux | grep irkerd pgrep -f irkerd @@ -576,22 +594,24 @@ ss -tlnp | grep 6659 # Recent activity in logs? tail -f /var/log/vext/vext.log journalctl -u vext -f -``` +---- -### Test IRC Connectivity +==== Test IRC Connectivity -```bash +[source,bash] +---- # Can you reach the IRC server? ping irc.libera.chat telnet irc.libera.chat 6667 # Check with nc echo -n "" | nc -w 5 irc.libera.chat 6667 -``` +---- -### Debug Hook Execution +==== Debug Hook Execution -```bash +[source,bash] +---- # Test hook manually cd /path/to/repo.git python3 hooks/post-receive <<< "0000000000000000000000000000000000000000 abc123 refs/heads/main" @@ -602,12 +622,14 @@ python3 -u hooks/post-receive 2>&1 | tee hook-debug.log # Check hook permissions ls -la hooks/post-receive # Should be: -rwxr-xr-x (755) -``` +---- + +==== Common Issues and Solutions -### Common Issues and Solutions +*Issue: Notifications not appearing in IRC* -**Issue: Notifications not appearing in IRC** -```bash +[source,bash] +---- # 1. Check daemon is running systemctl status vext @@ -620,10 +642,12 @@ echo '{"to":"irc://irc.libera.chat/testchannel","privmsg":"test"}' | \ # 4. Check firewall sudo ufw status -``` +---- + +*Issue: Hook script not executing* -**Issue: Hook script not executing** -```bash +[source,bash] +---- # 1. Check permissions ls -la /path/to/repo.git/hooks/post-receive # Should be executable (x) @@ -637,10 +661,12 @@ head -1 /path/to/repo.git/hooks/post-receive # 4. Check git config cat /path/to/repo.git/config -``` +---- -**Issue: Connection refused** -```bash +*Issue: Connection refused* + +[source,bash] +---- # 1. Check daemon port sudo ss -tlnp | grep 6659 @@ -649,13 +675,14 @@ IRKERD_PORT=6660 irkerd --foreground # 3. Check firewall sudo ufw allow 6659 -``` +---- -## Advanced Usage +=== Advanced Usage -### Rotating Logs +==== Rotating Logs -```bash +[source,bash] +---- # Manual rotation sudo systemctl stop vext sudo mv /var/log/vext/vext.log /var/log/vext/vext.log.1 @@ -672,11 +699,12 @@ cat > /etc/logrotate.d/vext << 'EOF' create 0640 irker irker } EOF -``` +---- -### High-Availability Setup +==== High-Availability Setup -```bash +[source,bash] +---- # Primary daemon irkerd --listen 0.0.0.0 --port 6659 & @@ -688,40 +716,44 @@ echo '{"to":"irc://irc.libera.chat/commits","privmsg":"msg"}' | \ nc -u localhost 6659 & echo '{"to":"irc://irc.libera.chat/commits","privmsg":"msg"}' | \ nc -u localhost 6660 -``` +---- -### Rate Limiting and Batching +==== Rate Limiting and Batching -```bash +[source,bash] +---- # Configure rate limits to prevent IRC flooding IRKERD_RATE_LIMIT=2 # 2 messages per second IRKERD_FLOOD_LIMIT=1000 # 1000 messages per minute irkerd --foreground --debug -``` +---- -## Performance Tuning +=== Performance Tuning -### Memory Optimization +==== Memory Optimization -```bash +[source,bash] +---- # Monitor daemon memory usage watch -n 1 'ps aux | grep irkerd | grep -v grep' # Limit memory usage (if needed) # Use cgroups or systemd unit configuration -``` +---- -### Connection Pooling +==== Connection Pooling -```bash +[source,bash] +---- # Daemon automatically pools IRC connections # Configure thread pool size in config: [daemon] threads = 4 # Adjust based on number of channels -``` - -## Conclusion +---- -vext provides flexible, powerful IRC notifications for your repositories. Start with the basic examples and expand based on your specific needs. For more information, see [README.md](README.md) and [FEATURES.md](FEATURES.md). +=== Conclusion +vext provides flexible, powerful IRC notifications for your +repositories. Start with the basic examples and expand based on your +specific needs. For more information, see README.md and FEATURES.md. diff --git a/vext/docs/conference-materials.adoc b/vext/docs/conference-materials.adoc new file mode 100644 index 0000000..e885788 --- /dev/null +++ b/vext/docs/conference-materials.adoc @@ -0,0 +1,196 @@ +== Conference Materials - vext + +**SPDX-License-Identifier: CC-BY-SA-4.0 + +This document contains talk proposals, abstracts, and presentation +materials for vext (Rhodium Standard Edition of irker). + +=== 🎤 Talk Proposals + +==== 1. IRC Notifications Done Right: Introducing vext + +*Target Conferences*: FOSDEM, PyCon, OSCON + +*Duration*: 30 minutes + +*Abstract*: + +Version control notifications are essential for team coordination, but +most solutions create IRC join/leave spam or require complex +integrations. vext (Rhodium Standard Edition of irker) solves this with +a lightweight daemon that maintains persistent IRC connections while +accepting notifications via simple JSON over TCP/UDP. + +This talk introduces vext’s architecture, demonstrates integration with +Git/Mercurial/SVN, and showcases the Tri-Perimeter Contribution +Framework (TPCF) governance model that makes the project sustainable and +welcoming. + +*Key Takeaways*: - How persistent IRC connections reduce channel noise - +Integrating vext with your VCS infrastructure - Building sustainable +open source projects with TPCF + +*Audience*: DevOps engineers, sysadmins, open source maintainers + +==== 2. Tri-Perimeter Contribution Framework: Graduated Trust in Open Source + +*Target Conferences*: FOSDEM (Community Devroom), OSCON, All Things Open + +*Duration*: 20 minutes (Lightning talk) + +*Abstract*: + +How do you balance open contribution with security and project quality? +The Tri-Perimeter Contribution Framework (TPCF) implements graduated +trust with three concentric circles: Core Maintainers (Perimeter 1), +Active Contributors (Perimeter 2), and Community (Perimeter 3). + +Drawing from vext’s implementation, this talk presents TPCF as a +governance pattern that welcomes newcomers while protecting critical +infrastructure. Learn how to apply TPCF to your own projects for +sustainable, inclusive growth. + +*Key Takeaways*: - Three-perimeter trust model fundamentals - Practical +implementation in small/medium projects - Measuring governance +effectiveness + +*Audience*: Project maintainers, community managers, governance +enthusiasts + +==== 3. Rhodium Standard Repository: Excellence in Open Source Packaging + +*Target Conferences*: PyCon, FOSDEM, SCALE + +*Duration*: 45 minutes + +*Abstract*: + +What makes a repository "`production-ready`"? The Rhodium Standard +Repository (RSR) framework defines Bronze, Silver, Gold, and Platinum +compliance levels covering documentation, security, build systems, +testing, and governance. + +This talk walks through vext’s journey to RSR Silver compliance, +demonstrating automated compliance checking, Nix-based reproducible +builds, RFC 9116 security.txt implementation, and Palimpsest dual +licensing. Attendees will learn actionable steps to elevate their own +projects. + +*Key Takeaways*: - RSR compliance levels and requirements - Automated +compliance verification tooling - Practical path from Bronze to Silver +compliance + +*Audience*: Python developers, DevOps, project maintainers + +=== 📊 Slide Deck Outlines + +==== Talk 1: IRC Notifications Done Right (30 min) + +*Slide Structure*: + +[arabic] +. *Title* (1 min) +* vext: Rhodium Standard Edition of irker +* Speaker introduction +. *Problem Statement* (3 min) +* IRC join/leave spam from per-commit scripts +* Delayed notifications with cron-based solutions +* Complex setups with dedicated bots +. *Solution: vext Architecture* (5 min) +* Persistent daemon maintains IRC connections +* JSON protocol over TCP/UDP +* VCS hooks send notifications to daemon +* Demo: Message flow diagram +. *Integration Examples* (10 min) +* Git post-receive hook +* Mercurial integration +* Subversion post-commit +* Multi-channel routing +* Live demo: Push commit, see IRC notification +. *TPCF Governance* (5 min) +* Three-perimeter trust model +* Community, Active Contributors, Core Maintainers +* Sustainable project health +. *RSR Compliance* (4 min) +* Silver level achievement +* Automated compliance checking +* Reproducible builds with Nix +. *Q&A* (2 min) +* Questions and discussion + +=== 🎯 Submission Timeline + +[cols=",,,",options="header",] +|=== +|Conference |Submission Deadline |Event Date |Status +|FOSDEM 2026 |Nov 2025 |Feb 2026 |Planned +|PyCon US 2026 |Dec 2025 |May 2026 |Planned +|OSCON 2026 |Jan 2026 |Jul 2026 |Planned +|SCALE 22x |Jan 2026 |Mar 2026 |Planned +|=== + +=== 📝 Speaker Bio + +*Short (100 words)*: + +The vext team maintains the Rhodium Standard Edition of irker, a +lightweight IRC notification daemon for version control systems. The +project focuses on sustainable open source governance through the +Tri-Perimeter Contribution Framework (TPCF) and achieves RSR Silver +compliance with comprehensive documentation, security practices, and +reproducible builds. + +*Long (250 words)*: + +The vext project represents a modernized, community-driven fork of irker +(by Eric S. Raymond), bringing IRC notifications for version control +systems into the era of comprehensive documentation, formal governance, +and production-grade quality standards. + +Our team implements the Tri-Perimeter Contribution Framework (TPCF), a +graduated trust model that welcomes community contributions while +maintaining project security and quality. We’ve achieved Rhodium +Standard Repository (RSR) Silver compliance, demonstrating excellence in +documentation, security policies (RFC 9116), reproducible builds (Nix), +and automated compliance verification. + +The project uses Palimpsest dual licensing (MPL-2.0) to support both +permissive and copyleft use cases, and maintains backward compatibility +with the original irker while adding modern features like comprehensive +testing, CI/CD automation, and detailed operational guides. + +=== 🖼️ Slide Assets + +==== Diagrams + +[arabic] +. *Architecture Diagram*: VCS → Hook → JSON → Daemon → IRC +. *TPCF Model*: Three concentric circles showing perimeter levels +. *Message Flow*: Detailed sequence diagram of notification path + +==== Code Samples + +[source,python] +---- +# Git hook example +#!/usr/bin/env python3 +import json, socket + +notification = { + "to": "irc://irc.libera.chat#commits", + "privmsg": "New commit by alice: Fix authentication bug" +} + +sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) +sock.sendto(json.dumps(notification).encode(), ("localhost", 6659)) +---- + +=== 📧 Contact for Speaking Engagements + +* *Email*: talks@vext.dev +* *Matrix*: #vext:matrix.org +* *General*: hello@vext.dev + +''''' + +*Last Updated*: 2025-01-01 *Maintained By*: vext Team diff --git a/vext/docs/conference-materials.md b/vext/docs/conference-materials.md deleted file mode 100644 index 768b651..0000000 --- a/vext/docs/conference-materials.md +++ /dev/null @@ -1,167 +0,0 @@ - -# Conference Materials - vext - -**SPDX-License-Identifier: CC-BY-SA-4.0 - -This document contains talk proposals, abstracts, and presentation materials for vext (Rhodium Standard Edition of irker). - -## 🎤 Talk Proposals - -### 1. IRC Notifications Done Right: Introducing vext - -**Target Conferences**: FOSDEM, PyCon, OSCON - -**Duration**: 30 minutes - -**Abstract**: - -Version control notifications are essential for team coordination, but most solutions create IRC join/leave spam or require complex integrations. vext (Rhodium Standard Edition of irker) solves this with a lightweight daemon that maintains persistent IRC connections while accepting notifications via simple JSON over TCP/UDP. - -This talk introduces vext's architecture, demonstrates integration with Git/Mercurial/SVN, and showcases the Tri-Perimeter Contribution Framework (TPCF) governance model that makes the project sustainable and welcoming. - -**Key Takeaways**: -- How persistent IRC connections reduce channel noise -- Integrating vext with your VCS infrastructure -- Building sustainable open source projects with TPCF - -**Audience**: DevOps engineers, sysadmins, open source maintainers - -### 2. Tri-Perimeter Contribution Framework: Graduated Trust in Open Source - -**Target Conferences**: FOSDEM (Community Devroom), OSCON, All Things Open - -**Duration**: 20 minutes (Lightning talk) - -**Abstract**: - -How do you balance open contribution with security and project quality? The Tri-Perimeter Contribution Framework (TPCF) implements graduated trust with three concentric circles: Core Maintainers (Perimeter 1), Active Contributors (Perimeter 2), and Community (Perimeter 3). - -Drawing from vext's implementation, this talk presents TPCF as a governance pattern that welcomes newcomers while protecting critical infrastructure. Learn how to apply TPCF to your own projects for sustainable, inclusive growth. - -**Key Takeaways**: -- Three-perimeter trust model fundamentals -- Practical implementation in small/medium projects -- Measuring governance effectiveness - -**Audience**: Project maintainers, community managers, governance enthusiasts - -### 3. Rhodium Standard Repository: Excellence in Open Source Packaging - -**Target Conferences**: PyCon, FOSDEM, SCALE - -**Duration**: 45 minutes - -**Abstract**: - -What makes a repository "production-ready"? The Rhodium Standard Repository (RSR) framework defines Bronze, Silver, Gold, and Platinum compliance levels covering documentation, security, build systems, testing, and governance. - -This talk walks through vext's journey to RSR Silver compliance, demonstrating automated compliance checking, Nix-based reproducible builds, RFC 9116 security.txt implementation, and Palimpsest dual licensing. Attendees will learn actionable steps to elevate their own projects. - -**Key Takeaways**: -- RSR compliance levels and requirements -- Automated compliance verification tooling -- Practical path from Bronze to Silver compliance - -**Audience**: Python developers, DevOps, project maintainers - -## 📊 Slide Deck Outlines - -### Talk 1: IRC Notifications Done Right (30 min) - -**Slide Structure**: - -1. **Title** (1 min) - - vext: Rhodium Standard Edition of irker - - Speaker introduction - -2. **Problem Statement** (3 min) - - IRC join/leave spam from per-commit scripts - - Delayed notifications with cron-based solutions - - Complex setups with dedicated bots - -3. **Solution: vext Architecture** (5 min) - - Persistent daemon maintains IRC connections - - JSON protocol over TCP/UDP - - VCS hooks send notifications to daemon - - Demo: Message flow diagram - -4. **Integration Examples** (10 min) - - Git post-receive hook - - Mercurial integration - - Subversion post-commit - - Multi-channel routing - - Live demo: Push commit, see IRC notification - -5. **TPCF Governance** (5 min) - - Three-perimeter trust model - - Community, Active Contributors, Core Maintainers - - Sustainable project health - -6. **RSR Compliance** (4 min) - - Silver level achievement - - Automated compliance checking - - Reproducible builds with Nix - -7. **Q&A** (2 min) - - Questions and discussion - -## 🎯 Submission Timeline - -| Conference | Submission Deadline | Event Date | Status | -| ---------- | ------------------- | ---------- | ------ | -| FOSDEM 2026 | Nov 2025 | Feb 2026 | Planned | -| PyCon US 2026 | Dec 2025 | May 2026 | Planned | -| OSCON 2026 | Jan 2026 | Jul 2026 | Planned | -| SCALE 22x | Jan 2026 | Mar 2026 | Planned | - -## 📝 Speaker Bio - -**Short (100 words)**: - -The vext team maintains the Rhodium Standard Edition of irker, a lightweight IRC notification daemon for version control systems. The project focuses on sustainable open source governance through the Tri-Perimeter Contribution Framework (TPCF) and achieves RSR Silver compliance with comprehensive documentation, security practices, and reproducible builds. - -**Long (250 words)**: - -The vext project represents a modernized, community-driven fork of irker (by Eric S. Raymond), bringing IRC notifications for version control systems into the era of comprehensive documentation, formal governance, and production-grade quality standards. - -Our team implements the Tri-Perimeter Contribution Framework (TPCF), a graduated trust model that welcomes community contributions while maintaining project security and quality. We've achieved Rhodium Standard Repository (RSR) Silver compliance, demonstrating excellence in documentation, security policies (RFC 9116), reproducible builds (Nix), and automated compliance verification. - -The project uses Palimpsest dual licensing (MPL-2.0) to support both permissive and copyleft use cases, and maintains backward compatibility with the original irker while adding modern features like comprehensive testing, CI/CD automation, and detailed operational guides. - -## 🖼️ Slide Assets - -### Diagrams - -1. **Architecture Diagram**: VCS → Hook → JSON → Daemon → IRC -2. **TPCF Model**: Three concentric circles showing perimeter levels -3. **Message Flow**: Detailed sequence diagram of notification path - -### Code Samples - -```python -# Git hook example -#!/usr/bin/env python3 -import json, socket - -notification = { - "to": "irc://irc.libera.chat#commits", - "privmsg": "New commit by alice: Fix authentication bug" -} - -sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) -sock.sendto(json.dumps(notification).encode(), ("localhost", 6659)) -``` - -## 📧 Contact for Speaking Engagements - -- **Email**: talks@vext.dev -- **Matrix**: #vext:matrix.org -- **General**: hello@vext.dev - ---- - -**Last Updated**: 2025-01-01 -**Maintained By**: vext Team diff --git a/vext/governance/PROJECT_GOVERNANCE.adoc b/vext/governance/PROJECT_GOVERNANCE.adoc new file mode 100644 index 0000000..60455be --- /dev/null +++ b/vext/governance/PROJECT_GOVERNANCE.adoc @@ -0,0 +1,330 @@ +== Project Governance + +**SPDX-License-Identifier: CC-BY-SA-4.0 + +=== 🏛️ Overview + +vext uses the *Tri-Perimeter Contribution Framework (TPCF)*, a graduated +trust model that balances security, community openness, and sustainable +project governance. + +TPCF organizes contributors into three concentric perimeters based on +trust, expertise, and responsibility. + +=== 🎯 Governance Philosophy + +Our governance is designed to: + +* *Foster Community*: Welcome contributors at all skill levels +* *Maintain Quality*: Ensure high standards through graduated +responsibilities +* *Enable Security*: Protect critical infrastructure through access +controls +* *Promote Transparency*: Make decisions openly and documentably +* *Support Sustainability*: Build long-term project health +* *Respect Autonomy*: Allow contributors to self-organize within +guidelines + +=== 🔷 Three-Perimeter Model + +.... +┌──────────────────────────────────────────────────────┐ +│ │ +│ Perimeter 3: Community (Open) │ +│ ┌──────────────────────────────────────────┐ │ +│ │ │ │ +│ │ Perimeter 2: Active Contributors │ │ +│ │ ┌────────────────────────────────┐ │ │ +│ │ │ │ │ │ +│ │ │ Perimeter 1: Core Maintainers │ │ │ +│ │ │ │ │ │ +│ │ │ • Write access │ │ │ +│ │ │ • Security decisions │ │ │ +│ │ │ • Release management │ │ │ +│ │ │ │ │ │ +│ │ └────────────────────────────────┘ │ │ +│ │ │ │ +│ │ • Code review │ │ +│ │ • Issue triage │ │ +│ │ • Mentoring │ │ +│ │ │ │ +│ └──────────────────────────────────────────┘ │ +│ │ +│ • Fork and PR │ +│ • Issues and discussions │ +│ • Testing and feedback │ +│ │ +└──────────────────────────────────────────────────────┘ +.... + +==== Perimeter 1: Core Maintainers + +*Access Level*: Full write access to repository + +*Responsibilities*: - Architectural decisions - Security vulnerability +response - Release management and versioning - Maintainer +onboarding/offboarding - Conflict resolution - Strategic direction - +License and legal decisions - Infrastructure management + +*Requirements*: - Deep expertise in project domain - Proven track record +of quality contributions - Strong architectural judgment - Commitment to +project values - Active for 6+ months - Endorsed by 2+ current core +maintainers - Unanimous approval from existing core team + +*Current Members*: See link:../MAINTAINERS.md[MAINTAINERS.md] + +==== Perimeter 2: Active Contributors + +*Access Level*: Triage permissions, reviewer status + +*Responsibilities*: - Code review for community PRs - Issue triage and +labeling - Documentation improvements - Community support and mentoring +- Testing and quality assurance - Feature discussions and RFC +participation + +*Requirements*: - 5+ merged pull requests - Consistent quality +contributions - Understanding of codebase architecture - Adherence to +Code of Conduct - Active for 3+ months - Recommendation from core +maintainer + +*Path to Perimeter 1*: - Demonstrate deep expertise - Show leadership in +specific areas - Mentor new contributors - 6+ months as active +contributor - Endorsement by 2+ core maintainers + +==== Perimeter 3: Community + +*Access Level*: Public (fork and pull request) + +*Responsibilities*: - Submit bug reports and feature requests - +Contribute code via pull requests - Improve documentation - Test and +provide feedback - Participate in discussions - Help other community +members + +*Requirements*: - None! Everyone is welcome - Follow Code of Conduct - +Respect community guidelines + +*Path to Perimeter 2*: - Make quality contributions over time - +Demonstrate understanding of project - Show commitment to community +values - Request promotion after meeting requirements + +=== 📋 Decision-Making Process + +==== Minor Decisions + +*Who*: Any core maintainer *Process*: Direct implementation *Examples*: +- Bug fixes - Documentation updates - Small refactors - Dependency +updates + +*Timeline*: Immediate + +==== Major Decisions + +*Who*: Consensus among core maintainers *Process*: RFC (Request for +Comments) *Examples*: - New features - Architecture changes - Breaking +changes - Governance modifications (minor) + +*Timeline*: Minimum 7 days for community feedback + +*RFC Process*: 1. Create issue with `+[RFC]+` prefix 2. Detail proposal +with rationale 3. Community discussion (7+ days) 4. Core maintainers +discuss and vote 5. 2/3 majority required 6. Decision documented and +implemented + +==== Critical Decisions + +*Who*: All core maintainers (unanimous) *Process*: Formal vote with +public record *Examples*: - License changes - Major governance changes - +Repository transfers - Project dissolution + +*Timeline*: Minimum 30 days for community feedback + +*Voting Process*: 1. Formal proposal with detailed rationale 2. +Community feedback period (30 days) 3. Core maintainer discussion 4. +Formal vote (+1, 0, -1) 5. Unanimous approval required 6. Public +announcement with rationale 7. Implementation timeline + +=== 🗳️ Voting Guidelines + +==== Vote Types + +* *+1*: Approve +* *0*: Neutral (abstain) +* *-1*: Block (must provide rationale and alternatives) + +==== Vote Requirements + +[cols=",,",options="header",] +|=== +|Decision Type |Threshold |Participation +|Minor |1 maintainer |Optional +|Major |2/3 majority |Encouraged +|Critical |Unanimous |Required +|=== + +==== Vote Conduct + +* *Good Faith*: Votes based on project best interest +* *Rationale*: Blocks must include detailed reasoning +* *Alternatives*: Blockers should propose alternatives +* *Transparency*: Votes are public record +* *Time Limits*: 7 days for major, 30 days for critical + +=== 🤝 Conflict Resolution + +==== Level 1: Direct Discussion + +* Contributors discuss directly +* Assume good faith +* Seek mutual understanding +* Document resolution + +==== Level 2: Mediator + +* Uninvolved maintainer mediates +* Facilitate respectful dialogue +* Help find common ground +* Document outcome + +==== Level 3: Vote + +* If mediation fails +* Core maintainers vote +* Decision is binding +* Document reasoning + +==== Level 4: Code of Conduct + +* If conduct violations occur +* See link:../CODE_OF_CONDUCT.md[CODE_OF_CONDUCT.md] +* Conduct team handles +* Separate from technical decisions + +=== 🔐 Security Governance + +==== Security Team + +*Members*: Subset of core maintainers *Communication*: Private channel +for vulnerabilities *Contact*: security@vext.dev + +*Responsibilities*: - Receive and triage vulnerability reports - +Coordinate security fixes - Manage disclosure timeline - Publish +security advisories - Maintain security.txt (RFC 9116) + +*Process*: See link:../SECURITY.md[SECURITY.md] + +==== Security Decision Making + +* *Immediate Response*: Security team acts independently +* *Coordinated Disclosure*: 90-day maximum timeline +* *Public Advisory*: After fixes are available +* *Retrospectives*: Learn from incidents + +=== 📊 Transparency and Accountability + +==== Public Records + +All governance decisions are publicly documented: + +* *Issues/Discussions*: Technical decisions +* *RFCs*: Major proposals +* *Votes*: Formal voting records +* *Meeting Notes*: Maintainer meetings (if any) +* *CHANGELOG.md*: Version decisions +* *governance/*: Policy documents + +==== Reporting + +* *Quarterly Reports*: Project health metrics +* *Annual Review*: Governance effectiveness +* *Transparency Reports*: Code of Conduct enforcement (anonymized) + +==== Accountability + +* *Code Review*: All changes reviewed +* *Decision Rationale*: Documented reasoning +* *Feedback Loops*: Community input welcomed +* *Appeals Process*: Decisions can be appealed + +=== 🔄 Governance Evolution + +This governance model can evolve: + +==== Amendment Process + +[arabic] +. *Proposal*: Any core maintainer can propose changes +. *Discussion*: Minimum 30-day community feedback +. *Vote*: Unanimous approval from core maintainers +. *Implementation*: Update documentation +. *Announcement*: Public communication of changes + +==== Review Schedule + +* *Quarterly*: Light review of processes +* *Annually*: Comprehensive governance review +* *As Needed*: Emergency changes for critical issues + +==== Version History + +[cols=",,",options="header",] +|=== +|Version |Date |Changes +|1.0 |2025-01-01 |Initial TPCF governance model +|=== + +=== 🌟 Community Values + +Our governance embodies these values: + +==== Emotional Safety + +* *Psychological Safety*: Safe to experiment, question, disagree +* *Anxiety Reduction*: Clear processes, predictable outcomes +* *Stress Management*: Sustainable pace, no crunch culture +* *Compassionate Communication*: Assume good intent + +==== Inclusivity + +* *Welcoming*: All backgrounds and skill levels +* *Accessibility*: Remove barriers to contribution +* *Diversity*: Actively seek diverse perspectives +* *Respect*: Value all contributions + +==== Quality + +* *Excellence*: High standards with support +* *Testing*: Comprehensive test coverage +* *Review*: Thoughtful code review +* *Documentation*: Clear and complete + +==== Sustainability + +* *Long-term*: Build for the future +* *Maintainer Health*: Prevent burnout +* *Succession*: Plan for transitions +* *Community*: Build resilient community + +=== 📚 Related Documents + +* link:../MAINTAINERS.md[MAINTAINERS.md] - Current team structure +* link:../CONTRIBUTING.md[CONTRIBUTING.md] - How to contribute +* link:../CODE_OF_CONDUCT.md[CODE_OF_CONDUCT.md] - Community standards +* link:../SECURITY.md[SECURITY.md] - Security policies + +=== 📞 Contact + +* *Governance Questions*: governance@vext.dev +* *Maintainer Application*: maintainers@vext.dev +* *General*: hello@vext.dev + +=== 📄 License + +This governance document is licensed under +https://creativecommons.org/licenses/by/4.0/[CC BY 4.0]. + +''''' + +*Last Updated*: 2025-01-01 *Version*: 1.0 *Next Review*: 2025-04-01 + +Governance maintained by: Core Maintainers (see +link:../MAINTAINERS.md[MAINTAINERS.md]) diff --git a/vext/governance/PROJECT_GOVERNANCE.md b/vext/governance/PROJECT_GOVERNANCE.md deleted file mode 100644 index 79327b7..0000000 --- a/vext/governance/PROJECT_GOVERNANCE.md +++ /dev/null @@ -1,363 +0,0 @@ - -# Project Governance - -**SPDX-License-Identifier: CC-BY-SA-4.0 - -## 🏛️ Overview - -vext uses the **Tri-Perimeter Contribution Framework (TPCF)**, a graduated trust model that balances security, community openness, and sustainable project governance. - -TPCF organizes contributors into three concentric perimeters based on trust, expertise, and responsibility. - -## 🎯 Governance Philosophy - -Our governance is designed to: - -- **Foster Community**: Welcome contributors at all skill levels -- **Maintain Quality**: Ensure high standards through graduated responsibilities -- **Enable Security**: Protect critical infrastructure through access controls -- **Promote Transparency**: Make decisions openly and documentably -- **Support Sustainability**: Build long-term project health -- **Respect Autonomy**: Allow contributors to self-organize within guidelines - -## 🔷 Three-Perimeter Model - -``` -┌──────────────────────────────────────────────────────┐ -│ │ -│ Perimeter 3: Community (Open) │ -│ ┌──────────────────────────────────────────┐ │ -│ │ │ │ -│ │ Perimeter 2: Active Contributors │ │ -│ │ ┌────────────────────────────────┐ │ │ -│ │ │ │ │ │ -│ │ │ Perimeter 1: Core Maintainers │ │ │ -│ │ │ │ │ │ -│ │ │ • Write access │ │ │ -│ │ │ • Security decisions │ │ │ -│ │ │ • Release management │ │ │ -│ │ │ │ │ │ -│ │ └────────────────────────────────┘ │ │ -│ │ │ │ -│ │ • Code review │ │ -│ │ • Issue triage │ │ -│ │ • Mentoring │ │ -│ │ │ │ -│ └──────────────────────────────────────────┘ │ -│ │ -│ • Fork and PR │ -│ • Issues and discussions │ -│ • Testing and feedback │ -│ │ -└──────────────────────────────────────────────────────┘ -``` - -### Perimeter 1: Core Maintainers - -**Access Level**: Full write access to repository - -**Responsibilities**: -- Architectural decisions -- Security vulnerability response -- Release management and versioning -- Maintainer onboarding/offboarding -- Conflict resolution -- Strategic direction -- License and legal decisions -- Infrastructure management - -**Requirements**: -- Deep expertise in project domain -- Proven track record of quality contributions -- Strong architectural judgment -- Commitment to project values -- Active for 6+ months -- Endorsed by 2+ current core maintainers -- Unanimous approval from existing core team - -**Current Members**: See [MAINTAINERS.md](../MAINTAINERS.md) - -### Perimeter 2: Active Contributors - -**Access Level**: Triage permissions, reviewer status - -**Responsibilities**: -- Code review for community PRs -- Issue triage and labeling -- Documentation improvements -- Community support and mentoring -- Testing and quality assurance -- Feature discussions and RFC participation - -**Requirements**: -- 5+ merged pull requests -- Consistent quality contributions -- Understanding of codebase architecture -- Adherence to Code of Conduct -- Active for 3+ months -- Recommendation from core maintainer - -**Path to Perimeter 1**: -- Demonstrate deep expertise -- Show leadership in specific areas -- Mentor new contributors -- 6+ months as active contributor -- Endorsement by 2+ core maintainers - -### Perimeter 3: Community - -**Access Level**: Public (fork and pull request) - -**Responsibilities**: -- Submit bug reports and feature requests -- Contribute code via pull requests -- Improve documentation -- Test and provide feedback -- Participate in discussions -- Help other community members - -**Requirements**: -- None! Everyone is welcome -- Follow Code of Conduct -- Respect community guidelines - -**Path to Perimeter 2**: -- Make quality contributions over time -- Demonstrate understanding of project -- Show commitment to community values -- Request promotion after meeting requirements - -## 📋 Decision-Making Process - -### Minor Decisions - -**Who**: Any core maintainer -**Process**: Direct implementation -**Examples**: -- Bug fixes -- Documentation updates -- Small refactors -- Dependency updates - -**Timeline**: Immediate - -### Major Decisions - -**Who**: Consensus among core maintainers -**Process**: RFC (Request for Comments) -**Examples**: -- New features -- Architecture changes -- Breaking changes -- Governance modifications (minor) - -**Timeline**: Minimum 7 days for community feedback - -**RFC Process**: -1. Create issue with `[RFC]` prefix -2. Detail proposal with rationale -3. Community discussion (7+ days) -4. Core maintainers discuss and vote -5. 2/3 majority required -6. Decision documented and implemented - -### Critical Decisions - -**Who**: All core maintainers (unanimous) -**Process**: Formal vote with public record -**Examples**: -- License changes -- Major governance changes -- Repository transfers -- Project dissolution - -**Timeline**: Minimum 30 days for community feedback - -**Voting Process**: -1. Formal proposal with detailed rationale -2. Community feedback period (30 days) -3. Core maintainer discussion -4. Formal vote (+1, 0, -1) -5. Unanimous approval required -6. Public announcement with rationale -7. Implementation timeline - -## 🗳️ Voting Guidelines - -### Vote Types - -- **+1**: Approve -- **0**: Neutral (abstain) -- **-1**: Block (must provide rationale and alternatives) - -### Vote Requirements - -| Decision Type | Threshold | Participation | -| ------------- | --------- | ------------- | -| Minor | 1 maintainer | Optional | -| Major | 2/3 majority | Encouraged | -| Critical | Unanimous | Required | - -### Vote Conduct - -- **Good Faith**: Votes based on project best interest -- **Rationale**: Blocks must include detailed reasoning -- **Alternatives**: Blockers should propose alternatives -- **Transparency**: Votes are public record -- **Time Limits**: 7 days for major, 30 days for critical - -## 🤝 Conflict Resolution - -### Level 1: Direct Discussion -- Contributors discuss directly -- Assume good faith -- Seek mutual understanding -- Document resolution - -### Level 2: Mediator -- Uninvolved maintainer mediates -- Facilitate respectful dialogue -- Help find common ground -- Document outcome - -### Level 3: Vote -- If mediation fails -- Core maintainers vote -- Decision is binding -- Document reasoning - -### Level 4: Code of Conduct -- If conduct violations occur -- See [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) -- Conduct team handles -- Separate from technical decisions - -## 🔐 Security Governance - -### Security Team - -**Members**: Subset of core maintainers -**Communication**: Private channel for vulnerabilities -**Contact**: security@vext.dev - -**Responsibilities**: -- Receive and triage vulnerability reports -- Coordinate security fixes -- Manage disclosure timeline -- Publish security advisories -- Maintain security.txt (RFC 9116) - -**Process**: See [SECURITY.md](../SECURITY.md) - -### Security Decision Making - -- **Immediate Response**: Security team acts independently -- **Coordinated Disclosure**: 90-day maximum timeline -- **Public Advisory**: After fixes are available -- **Retrospectives**: Learn from incidents - -## 📊 Transparency and Accountability - -### Public Records - -All governance decisions are publicly documented: - -- **Issues/Discussions**: Technical decisions -- **RFCs**: Major proposals -- **Votes**: Formal voting records -- **Meeting Notes**: Maintainer meetings (if any) -- **CHANGELOG.md**: Version decisions -- **governance/**: Policy documents - -### Reporting - -- **Quarterly Reports**: Project health metrics -- **Annual Review**: Governance effectiveness -- **Transparency Reports**: Code of Conduct enforcement (anonymized) - -### Accountability - -- **Code Review**: All changes reviewed -- **Decision Rationale**: Documented reasoning -- **Feedback Loops**: Community input welcomed -- **Appeals Process**: Decisions can be appealed - -## 🔄 Governance Evolution - -This governance model can evolve: - -### Amendment Process - -1. **Proposal**: Any core maintainer can propose changes -2. **Discussion**: Minimum 30-day community feedback -3. **Vote**: Unanimous approval from core maintainers -4. **Implementation**: Update documentation -5. **Announcement**: Public communication of changes - -### Review Schedule - -- **Quarterly**: Light review of processes -- **Annually**: Comprehensive governance review -- **As Needed**: Emergency changes for critical issues - -### Version History - -| Version | Date | Changes | -| ------- | ---------- | ------- | -| 1.0 | 2025-01-01 | Initial TPCF governance model | - -## 🌟 Community Values - -Our governance embodies these values: - -### Emotional Safety -- **Psychological Safety**: Safe to experiment, question, disagree -- **Anxiety Reduction**: Clear processes, predictable outcomes -- **Stress Management**: Sustainable pace, no crunch culture -- **Compassionate Communication**: Assume good intent - -### Inclusivity -- **Welcoming**: All backgrounds and skill levels -- **Accessibility**: Remove barriers to contribution -- **Diversity**: Actively seek diverse perspectives -- **Respect**: Value all contributions - -### Quality -- **Excellence**: High standards with support -- **Testing**: Comprehensive test coverage -- **Review**: Thoughtful code review -- **Documentation**: Clear and complete - -### Sustainability -- **Long-term**: Build for the future -- **Maintainer Health**: Prevent burnout -- **Succession**: Plan for transitions -- **Community**: Build resilient community - -## 📚 Related Documents - -- [MAINTAINERS.md](../MAINTAINERS.md) - Current team structure -- [CONTRIBUTING.md](../CONTRIBUTING.md) - How to contribute -- [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) - Community standards -- [SECURITY.md](../SECURITY.md) - Security policies - -## 📞 Contact - -- **Governance Questions**: governance@vext.dev -- **Maintainer Application**: maintainers@vext.dev -- **General**: hello@vext.dev - -## 📄 License - -This governance document is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). - ---- - -**Last Updated**: 2025-01-01 -**Version**: 1.0 -**Next Review**: 2025-04-01 - -Governance maintained by: Core Maintainers (see [MAINTAINERS.md](../MAINTAINERS.md)) diff --git a/vext/papers/tpcf-graduated-trust.adoc b/vext/papers/tpcf-graduated-trust.adoc new file mode 100644 index 0000000..6fbb646 --- /dev/null +++ b/vext/papers/tpcf-graduated-trust.adoc @@ -0,0 +1,275 @@ +== Tri-Perimeter Contribution Framework: A Graduated Trust Model for Open Source Governance + +**SPDX-License-Identifier: CC-BY-SA-4.0 + +*Status*: Draft *Target Venue*: CHI, CSCW, OpenSym *Category*: Social +Computing, Governance, Open Source + +=== Abstract + +Open source projects face a fundamental tension: welcoming broad +community participation while maintaining security and code quality. +Existing governance models often fall into two extremes—fully open +(exposing projects to security risks) or tightly controlled +(discouraging contribution). + +We present the Tri-Perimeter Contribution Framework (TPCF), a graduated +trust model organizing contributors into three concentric perimeters +based on expertise, commitment, and trust level. Through a mixed-methods +study of TPCF implementation in vext (N=100 developers surveyed, 20 +interviewed), we demonstrate that graduated trust models can +simultaneously increase community participation (+43% first-time +contributors), maintain code quality (zero security incidents), and +improve contributor well-being (31% reduction in contribution anxiety). + +TPCF provides a practical, replicable governance pattern for small to +medium open source projects seeking sustainable, inclusive growth +without sacrificing security or quality. + +=== 1. Introduction + +==== 1.1 The Governance Dilemma + +Open source software powers critical infrastructure, yet project +governance remains an unsolved challenge. Projects must balance: + +* *Openness*: Welcoming diverse contributors +* *Security*: Protecting against malicious or low-quality contributions +* *Sustainability*: Preventing maintainer burnout +* *Quality*: Maintaining high code standards + +==== 1.2 Research Questions + +RQ1: Can graduated trust models increase community participation while +maintaining security? + +RQ2: How does formalized perimeter progression affect contributor +motivation and anxiety? + +RQ3: What organizational patterns support sustainable governance in +small/medium projects? + +==== 1.3 Contributions + +[arabic] +. *TPCF Framework*: A formal three-perimeter governance model +. *Empirical Evaluation*: Mixed-methods study (N=100 survey, N=20 +interviews) +. *Implementation Guide*: Practical patterns for adoption +. *Tools*: Automated governance enforcement mechanisms + +=== 2. Related Work + +==== 2.1 Open Source Governance + +* *Benevolent Dictator* (Linux, Python): Centralized decision-making +* *Meritocracy* (Apache): Contribution-based advancement +* *Consensus* (IETF): Group decision processes +* *Corporate* (Android, .NET): Company-controlled projects + +==== 2.2 Trust and Security + +* *Commit Access Models*: All-or-nothing vs. graduated +* *Code Review Practices*: Pre-commit vs. post-commit +* *Security Perimeters*: Infrastructure access controls + +==== 2.3 Community Health + +* *Contributor Retention*: Onboarding and mentorship +* *Psychological Safety*: Reducing anxiety in contribution +* *Burnout Prevention*: Sustainable maintainer practices + +=== 3. The TPCF Model + +==== 3.1 Three Perimeters + +.... +┌─────────────────────────────────────┐ +│ Perimeter 3: Community (Open) │ +│ ┌──────────────────────────────┐ │ +│ │ Perimeter 2: Active │ │ +│ │ ┌────────────────────────┐ │ │ +│ │ │ Perimeter 1: Core │ │ │ +│ │ │ • Write access │ │ │ +│ │ │ • Security decisions │ │ │ +│ │ │ • Releases │ │ │ +│ │ └────────────────────────┘ │ │ +│ │ • Code review │ │ +│ │ • Issue triage │ │ +│ │ • Mentoring │ │ +│ └──────────────────────────────┘ │ +│ • Fork & PR │ +│ • Issues & discussions │ +│ • Testing │ +└─────────────────────────────────────┘ +.... + +==== 3.2 Formal Access Control Model + +Let C = \{c₁, c₂, …, cₙ} be the set of contributors. Let P : C → \{1, 2, +3} be the perimeter assignment function. Let A = \{read, write, deploy, +security} be the set of access rights. + +*Access rules*: - P(c) = 3 ⟹ rights(c) = \{read, fork, issue} - P(c) = 2 +⟹ rights(c) = \{read, fork, issue, triage, review} - P(c) = 1 ⟹ +rights(c) = A (all rights) + +==== 3.3 Progression Criteria + +*Perimeter 3 → 2*: - Contributions: ≥5 merged PRs - Quality: 0 critical +bugs introduced - Time: ≥3 months active - Community: 0 CoC violations + +*Perimeter 2 → 1*: - Contributions: ≥20 merged PRs - Leadership: +Mentored ≥2 P3 contributors - Time: ≥6 months active - Endorsement: 2+ +P1 maintainers + +=== 4. Methodology + +==== 4.1 Study Design + +* *Project*: vext (Rhodium Standard Edition of irker) +* *Timeline*: 12 months (Jan 2025 - Dec 2025) +* *Participants*: 100 contributors (survey), 20 (interviews) + +==== 4.2 Quantitative Measures + +* Contribution velocity (PRs/month) +* Code quality (bugs introduced, review iterations) +* Security incidents +* Contributor retention (3-month, 6-month, 12-month) +* Time-to-merge for PRs + +==== 4.3 Qualitative Measures + +* Semi-structured interviews (N=20) +* Anxiety and emotional safety scales +* Contributor motivation themes +* Governance clarity perceptions + +=== 5. Results + +==== 5.1 Contribution Metrics (Quantitative) + +[cols=",,,",options="header",] +|=== +|Metric |Before TPCF |After TPCF |Change +|First-time contributors/month |3.2 |4.6 |+43% +|PR acceptance rate |68% |71% |+4% +|Security incidents |2 |0 |-100% +|Median time-to-merge |6.2 days |5.1 days |-18% +|Maintainer hours/week |12 |9 |-25% +|=== + +==== 5.2 Contributor Well-Being (Qualitative) + +*Anxiety Reduction*: 31% of contributors reported lower contribution +anxiety after TPCF implementation + +*Common Themes*: - "`Clear expectations reduced fear of rejection`" - +"`Progression path made contributions feel meaningful`" - "`Perimeter 3 +felt safe to experiment`" + +==== 5.3 Code Quality + +* *Bug Introduction Rate*: No significant change (p=0.23) +* *Review Depth*: Increased for P3 PRs (+2.1 comments/PR) +* *Test Coverage*: Increased from 73% to 81% + +=== 6. Discussion + +==== 6.1 Effectiveness of Graduated Trust + +TPCF successfully balances openness and security through: + +[arabic] +. *Low Barrier to Entry*: P3 remains fully open +. *Earned Privilege*: Clear progression criteria +. *Distributed Review*: P2 contributors share load +. *Security Isolation*: Critical access limited to P1 + +==== 6.2 Psychological Safety + +The formal perimeter model reduces anxiety by: + +* *Explicit Expectations*: Clear progression criteria +* *Safe Experimentation*: P3 as a "`practice space`" +* *Recognition*: Formal advancement ceremonies +* *Reversibility*: Ability to step back without shame + +==== 6.3 Limitations + +* *Single Project*: Results from one project (vext) +* *Small Sample*: N=100 may not generalize +* *Self-Reported*: Anxiety measures are subjective +* *Timeline*: 12 months may not capture long-term effects + +=== 7. Implementation Guidelines + +==== 7.1 Adoption Checklist + +* [ ] Document perimeter definitions +* [ ] Define progression criteria +* [ ] Create onboarding guides for each perimeter +* [ ] Implement access controls (GitHub teams, GitLab permissions) +* [ ] Establish review processes +* [ ] Set up mentorship matching + +==== 7.2 Tool Support + +* *Automation*: GitHub Actions for access management +* *Dashboards*: Contributor progression tracking +* *Metrics*: Automated contribution counting +* *Governance Bot*: Perimeter assignment suggestions + +=== 8. Conclusion + +The Tri-Perimeter Contribution Framework demonstrates that graduated +trust models can simultaneously improve community participation, code +quality, and contributor well-being. By formalizing progression paths +and access controls, TPCF provides a replicable governance pattern for +sustainable open source projects. + +Future work should explore TPCF application to larger projects (>1000 +contributors), multi-repository organizations, and integration with +existing governance frameworks (Apache, CNCF). + +=== References + +[arabic] +. Raymond, E. S. (1999). _The Cathedral and the Bazaar_ +. Fogel, K. (2005). _Producing Open Source Software_ +. Eghbal, N. (2020). _Working in Public: The Making and Maintenance of +Open Source Software_ +. Ford, D., et al. (2019). "`Beyond the Code: GitHub’s Open Source +Community Health`" +. Steinmacher, I., et al. (2015). "`Let Me In: Guidelines for the +Successful Onboarding of Newcomers`" + +=== Appendix A: Survey Instrument + +*Contribution Anxiety Scale* (7-point Likert): 1. I feel anxious when +submitting pull requests 2. I worry my contributions will be rejected 3. +I fear making mistakes in my code 4. I feel judged by maintainers 5. I +hesitate to ask questions + +*Governance Clarity Scale* (7-point Likert): 1. I understand how to +progress in this project 2. The contribution process is clear 3. I know +what is expected of me 4. Access rights are well-defined 5. +Decision-making is transparent + +=== Appendix B: Interview Protocol + +*Opening*: - Contribution history and role - Motivation for contributing + +*TPCF Experience*: - Understanding of perimeter model - Progression +experience (if applicable) - Impact on contribution behavior + +*Well-Being*: - Anxiety around contributions - Sense of belonging - +Psychological safety + +*Suggestions*: - Improvements to TPCF - Governance recommendations + +''''' + +*Authors*: vext Team *Contact*: research@vext.dev *Version*: 0.1 (Draft) +*Last Updated*: 2025-01-01 diff --git a/vext/papers/tpcf-graduated-trust.md b/vext/papers/tpcf-graduated-trust.md deleted file mode 100644 index 5c2ea55..0000000 --- a/vext/papers/tpcf-graduated-trust.md +++ /dev/null @@ -1,268 +0,0 @@ - -# Tri-Perimeter Contribution Framework: A Graduated Trust Model for Open Source Governance - -**SPDX-License-Identifier: CC-BY-SA-4.0 - -**Status**: Draft -**Target Venue**: CHI, CSCW, OpenSym -**Category**: Social Computing, Governance, Open Source - -## Abstract - -Open source projects face a fundamental tension: welcoming broad community participation while maintaining security and code quality. Existing governance models often fall into two extremes—fully open (exposing projects to security risks) or tightly controlled (discouraging contribution). - -We present the Tri-Perimeter Contribution Framework (TPCF), a graduated trust model organizing contributors into three concentric perimeters based on expertise, commitment, and trust level. Through a mixed-methods study of TPCF implementation in vext (N=100 developers surveyed, 20 interviewed), we demonstrate that graduated trust models can simultaneously increase community participation (+43% first-time contributors), maintain code quality (zero security incidents), and improve contributor well-being (31% reduction in contribution anxiety). - -TPCF provides a practical, replicable governance pattern for small to medium open source projects seeking sustainable, inclusive growth without sacrificing security or quality. - -## 1. Introduction - -### 1.1 The Governance Dilemma - -Open source software powers critical infrastructure, yet project governance remains an unsolved challenge. Projects must balance: - -- **Openness**: Welcoming diverse contributors -- **Security**: Protecting against malicious or low-quality contributions -- **Sustainability**: Preventing maintainer burnout -- **Quality**: Maintaining high code standards - -### 1.2 Research Questions - -RQ1: Can graduated trust models increase community participation while maintaining security? - -RQ2: How does formalized perimeter progression affect contributor motivation and anxiety? - -RQ3: What organizational patterns support sustainable governance in small/medium projects? - -### 1.3 Contributions - -1. **TPCF Framework**: A formal three-perimeter governance model -2. **Empirical Evaluation**: Mixed-methods study (N=100 survey, N=20 interviews) -3. **Implementation Guide**: Practical patterns for adoption -4. **Tools**: Automated governance enforcement mechanisms - -## 2. Related Work - -### 2.1 Open Source Governance - -- **Benevolent Dictator** (Linux, Python): Centralized decision-making -- **Meritocracy** (Apache): Contribution-based advancement -- **Consensus** (IETF): Group decision processes -- **Corporate** (Android, .NET): Company-controlled projects - -### 2.2 Trust and Security - -- **Commit Access Models**: All-or-nothing vs. graduated -- **Code Review Practices**: Pre-commit vs. post-commit -- **Security Perimeters**: Infrastructure access controls - -### 2.3 Community Health - -- **Contributor Retention**: Onboarding and mentorship -- **Psychological Safety**: Reducing anxiety in contribution -- **Burnout Prevention**: Sustainable maintainer practices - -## 3. The TPCF Model - -### 3.1 Three Perimeters - -``` -┌─────────────────────────────────────┐ -│ Perimeter 3: Community (Open) │ -│ ┌──────────────────────────────┐ │ -│ │ Perimeter 2: Active │ │ -│ │ ┌────────────────────────┐ │ │ -│ │ │ Perimeter 1: Core │ │ │ -│ │ │ • Write access │ │ │ -│ │ │ • Security decisions │ │ │ -│ │ │ • Releases │ │ │ -│ │ └────────────────────────┘ │ │ -│ │ • Code review │ │ -│ │ • Issue triage │ │ -│ │ • Mentoring │ │ -│ └──────────────────────────────┘ │ -│ • Fork & PR │ -│ • Issues & discussions │ -│ • Testing │ -└─────────────────────────────────────┘ -``` - -### 3.2 Formal Access Control Model - -Let C = {c₁, c₂, ..., cₙ} be the set of contributors. -Let P : C → {1, 2, 3} be the perimeter assignment function. -Let A = {read, write, deploy, security} be the set of access rights. - -**Access rules**: -- P(c) = 3 ⟹ rights(c) = {read, fork, issue} -- P(c) = 2 ⟹ rights(c) = {read, fork, issue, triage, review} -- P(c) = 1 ⟹ rights(c) = A (all rights) - -### 3.3 Progression Criteria - -**Perimeter 3 → 2**: -- Contributions: ≥5 merged PRs -- Quality: 0 critical bugs introduced -- Time: ≥3 months active -- Community: 0 CoC violations - -**Perimeter 2 → 1**: -- Contributions: ≥20 merged PRs -- Leadership: Mentored ≥2 P3 contributors -- Time: ≥6 months active -- Endorsement: 2+ P1 maintainers - -## 4. Methodology - -### 4.1 Study Design - -- **Project**: vext (Rhodium Standard Edition of irker) -- **Timeline**: 12 months (Jan 2025 - Dec 2025) -- **Participants**: 100 contributors (survey), 20 (interviews) - -### 4.2 Quantitative Measures - -- Contribution velocity (PRs/month) -- Code quality (bugs introduced, review iterations) -- Security incidents -- Contributor retention (3-month, 6-month, 12-month) -- Time-to-merge for PRs - -### 4.3 Qualitative Measures - -- Semi-structured interviews (N=20) -- Anxiety and emotional safety scales -- Contributor motivation themes -- Governance clarity perceptions - -## 5. Results - -### 5.1 Contribution Metrics (Quantitative) - -| Metric | Before TPCF | After TPCF | Change | -| ------ | ----------- | ---------- | ------ | -| First-time contributors/month | 3.2 | 4.6 | +43% | -| PR acceptance rate | 68% | 71% | +4% | -| Security incidents | 2 | 0 | -100% | -| Median time-to-merge | 6.2 days | 5.1 days | -18% | -| Maintainer hours/week | 12 | 9 | -25% | - -### 5.2 Contributor Well-Being (Qualitative) - -**Anxiety Reduction**: 31% of contributors reported lower contribution anxiety after TPCF implementation - -**Common Themes**: -- "Clear expectations reduced fear of rejection" -- "Progression path made contributions feel meaningful" -- "Perimeter 3 felt safe to experiment" - -### 5.3 Code Quality - -- **Bug Introduction Rate**: No significant change (p=0.23) -- **Review Depth**: Increased for P3 PRs (+2.1 comments/PR) -- **Test Coverage**: Increased from 73% to 81% - -## 6. Discussion - -### 6.1 Effectiveness of Graduated Trust - -TPCF successfully balances openness and security through: - -1. **Low Barrier to Entry**: P3 remains fully open -2. **Earned Privilege**: Clear progression criteria -3. **Distributed Review**: P2 contributors share load -4. **Security Isolation**: Critical access limited to P1 - -### 6.2 Psychological Safety - -The formal perimeter model reduces anxiety by: - -- **Explicit Expectations**: Clear progression criteria -- **Safe Experimentation**: P3 as a "practice space" -- **Recognition**: Formal advancement ceremonies -- **Reversibility**: Ability to step back without shame - -### 6.3 Limitations - -- **Single Project**: Results from one project (vext) -- **Small Sample**: N=100 may not generalize -- **Self-Reported**: Anxiety measures are subjective -- **Timeline**: 12 months may not capture long-term effects - -## 7. Implementation Guidelines - -### 7.1 Adoption Checklist - -- [ ] Document perimeter definitions -- [ ] Define progression criteria -- [ ] Create onboarding guides for each perimeter -- [ ] Implement access controls (GitHub teams, GitLab permissions) -- [ ] Establish review processes -- [ ] Set up mentorship matching - -### 7.2 Tool Support - -- **Automation**: GitHub Actions for access management -- **Dashboards**: Contributor progression tracking -- **Metrics**: Automated contribution counting -- **Governance Bot**: Perimeter assignment suggestions - -## 8. Conclusion - -The Tri-Perimeter Contribution Framework demonstrates that graduated trust models can simultaneously improve community participation, code quality, and contributor well-being. By formalizing progression paths and access controls, TPCF provides a replicable governance pattern for sustainable open source projects. - -Future work should explore TPCF application to larger projects (>1000 contributors), multi-repository organizations, and integration with existing governance frameworks (Apache, CNCF). - -## References - -1. Raymond, E. S. (1999). *The Cathedral and the Bazaar* -2. Fogel, K. (2005). *Producing Open Source Software* -3. Eghbal, N. (2020). *Working in Public: The Making and Maintenance of Open Source Software* -4. Ford, D., et al. (2019). "Beyond the Code: GitHub's Open Source Community Health" -5. Steinmacher, I., et al. (2015). "Let Me In: Guidelines for the Successful Onboarding of Newcomers" - -## Appendix A: Survey Instrument - -**Contribution Anxiety Scale** (7-point Likert): -1. I feel anxious when submitting pull requests -2. I worry my contributions will be rejected -3. I fear making mistakes in my code -4. I feel judged by maintainers -5. I hesitate to ask questions - -**Governance Clarity Scale** (7-point Likert): -1. I understand how to progress in this project -2. The contribution process is clear -3. I know what is expected of me -4. Access rights are well-defined -5. Decision-making is transparent - -## Appendix B: Interview Protocol - -**Opening**: -- Contribution history and role -- Motivation for contributing - -**TPCF Experience**: -- Understanding of perimeter model -- Progression experience (if applicable) -- Impact on contribution behavior - -**Well-Being**: -- Anxiety around contributions -- Sense of belonging -- Psychological safety - -**Suggestions**: -- Improvements to TPCF -- Governance recommendations - ---- - -**Authors**: vext Team -**Contact**: research@vext.dev -**Version**: 0.1 (Draft) -**Last Updated**: 2025-01-01