From 40be6076110d45f27e53dbbf34028e0b38f19b90 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 27 May 2026 19:43:41 +0100 Subject: [PATCH 1/2] docs: bring repo to estate documentation + contributor convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 1 — top-level docs: + CHANGELOG.md (Keep-a-Changelog format, points at standards changelog-reusable.yml) + ROADMAP.adoc (vision, near/medium/long term, non-goals, tracking) + MAINTAINERS.adoc (lead, responsibilities, becoming-a-maintainer hook) + GOVERNANCE.adoc (BDFL model, decisions, roles, transition clause) - CONTRIBUTING.adoc (was duplicate of .md in two formats) ~ CONTRIBUTING.md (corrected nix -> guix per standards#101; added Registering a Package section) Phase 2 — .github template fleet: + .github/CODEOWNERS (default + per-area ownership) + .github/FUNDING.yml (github: hyperpolymath) + .github/pull_request_template.md (RSR checklist, registry-specific section) + .github/copilot-instructions.md (estate banned-languages + registry shape) + .github/ISSUE_TEMPLATE/bug_report.md (registry-tailored, Pkg-aware repro) + .github/ISSUE_TEMPLATE/feature_request.md (with estate-alignment field) + .github/ISSUE_TEMPLATE/package_registration.md (new — registration is the most common kind of issue here; quality-bar checklist mirrors GOVERNANCE.adoc) All new files carry SPDX PMPL-1.0-or-later headers consistent with existing repo content. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/CODEOWNERS | 25 ++++ .github/FUNDING.yml | 1 + .github/ISSUE_TEMPLATE/bug_report.md | 38 ++++++ .github/ISSUE_TEMPLATE/feature_request.md | 22 ++++ .../ISSUE_TEMPLATE/package_registration.md | 32 +++++ .github/copilot-instructions.md | 49 +++++++ .github/pull_request_template.md | 41 ++++++ CHANGELOG.md | 52 ++++++++ CONTRIBUTING.adoc | 26 ---- CONTRIBUTING.md | 13 +- GOVERNANCE.adoc | 122 ++++++++++++++++++ MAINTAINERS.adoc | 42 ++++++ ROADMAP.adoc | 75 +++++++++++ 13 files changed, 510 insertions(+), 28 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 .github/FUNDING.yml create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/package_registration.md create mode 100644 .github/copilot-instructions.md create mode 100644 .github/pull_request_template.md create mode 100644 CHANGELOG.md delete mode 100644 CONTRIBUTING.adoc create mode 100644 GOVERNANCE.adoc create mode 100644 MAINTAINERS.adoc create mode 100644 ROADMAP.adoc diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..c5d861c --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,25 @@ +# SPDX-License-Identifier: PMPL-1.0-or-later +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# CODEOWNERS — julia-professional-registry + +# Default owner for all files +* @hyperpolymath + +# Registry index — the canonical surface +/Registry.toml @hyperpolymath + +# Workflows + dependency policy +/.github/ @hyperpolymath + +# Machine-readable metadata +/.machine_readable/ @hyperpolymath + +# Security-sensitive +/SECURITY.md @hyperpolymath +/.well-known/ @hyperpolymath + +# Governance docs +/GOVERNANCE.adoc @hyperpolymath +/MAINTAINERS.adoc @hyperpolymath +/CODE_OF_CONDUCT.md @hyperpolymath diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..7937a0a --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1 @@ +github: [hyperpolymath] diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..4feb831 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,38 @@ +--- +name: Bug report +about: Report a problem with the registry or a registered package's metadata +title: '' +labels: bug +assignees: '' +--- + +**What went wrong?** +A clear, concise description of what the bug is. + +**To reproduce** +Steps to reproduce the behaviour. For registry-installation issues, include the exact `Pkg` commands you ran: + +```julia +using Pkg +Pkg.Registry.add(...) +Pkg.add("...") +``` + +**Expected behaviour** +What you expected to happen. + +**Actual behaviour** +What actually happened. Paste the Julia error output verbatim if there was one. + +**Environment** + - Julia version (`versioninfo()` output): + - OS: + - Registry version / commit: + +**Affected package (if applicable)** + - Package name: + - Version: + - Upstream repository: + +**Additional context** +Anything else that might help diagnose the problem. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..8e402f6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,22 @@ +--- +name: Feature request +about: Suggest an improvement to the registry's tooling, policies, or scope +title: '' +labels: enhancement +assignees: '' +--- + +**Problem this would solve** +A clear, concise description of the problem. e.g. "It is currently difficult to ..." + +**Proposed solution** +What you would like to happen. Include a sketch of the change if it touches Registry.toml, workflows, or directory layout. + +**Alternatives considered** +Other approaches you thought about and why this one is preferable. + +**Estate alignment** +Does this change touch estate conventions that live in [hyperpolymath/standards](https://github.com/hyperpolymath/standards)? If so, link the relevant standards issue or PR. Avoid drifting away from estate conventions silently. + +**Additional context** +Any other context, links, or screenshots. diff --git a/.github/ISSUE_TEMPLATE/package_registration.md b/.github/ISSUE_TEMPLATE/package_registration.md new file mode 100644 index 0000000..e47dafd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/package_registration.md @@ -0,0 +1,32 @@ +--- +name: Package registration request +about: Propose a new package, or a new version of an existing package, for registration +title: 'register: v' +labels: registration +assignees: '' +--- + +**Package** + - Name: + - Version being registered: + - Upstream repository URL: + - Maintainer (GitHub handle): + +**New registration or update?** + - [ ] Brand-new package (not previously in this registry) + - [ ] New version of an already-registered package + +**Quality bar checklist** (see [GOVERNANCE.adoc](../../GOVERNANCE.adoc)) + +- [ ] SPDX license headers on all source files +- [ ] REUSE-compliant `LICENSES/` directory +- [ ] OpenSSF Scorecard >= 7 (link the scorecard run if available) +- [ ] No banned-language files in the package +- [ ] `Project.toml` carries semver-compatible `compat` ranges for all dependencies +- [ ] A tag exists on the upstream repo matching the version being registered + +**Dependencies on other hyperpolymath registry packages?** +List any deps already in this registry that this package or version requires. + +**Additional context** +Anything else the BDFL should know before reviewing the registration. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..96a028e --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,49 @@ + + + +# Copilot Instructions + +## Before Writing Code + +- Read `0-AI-MANIFEST.a2ml` in the repo root for canonical file locations. +- State files (`*.a2ml`) live in `.machine_readable/6a2/` ONLY, never the root. +- Registry data is structured per the Julia package registry format: `Registry.toml` at the root, per-letter directories (`A/`, `B/`, ...) each containing per-package subdirs with `Package.toml` / `Versions.toml` / `Deps.toml` / `Compat.toml`. + +## License + +- SPDX: `PMPL-1.0-or-later` on all new files. +- Never use AGPL-3.0. +- Copyright: `Jonathan D.A. Jewell (hyperpolymath) `. + +## Code Style + +- Annotate and document all files. +- Add SPDX header to every source file (Julia, AsciiDoc, Markdown, TOML where comments are supported). +- Use `just` for build/test/lint commands. + +## Banned Languages (estate-wide) + +- No TypeScript (use AffineScript). +- No Node.js / npm / bun (use Deno). +- No Go (use Rust). +- No Python (use Julia or Rust). + +## Containers + +- Use Podman, never Docker. +- Name the file `Containerfile`, never `Dockerfile`. +- Base image: `cgr.dev/chainguard/wolfi-base:latest`. + +## State Files + +Never create these in the repo root: +`STATE.a2ml`, `META.a2ml`, `ECOSYSTEM.a2ml`, `AGENTIC.a2ml`, `NEUROSYM.a2ml`, `PLAYBOOK.a2ml`. +They belong in `.machine_readable/6a2/` only. + +## Workflow Pins + +All wrapper workflows in `.github/workflows/` must pin the upstream standards reusable to a SHA (40-hex), never `@main` or `@v1`. Use the standards repo's current `main` HEAD SHA for new wrappers; let dependabot or rhodibot update the pin afterwards. + +## Registration PRs + +A package registration PR title follows: `feat(registry): register v` (or `add ` for first registration). It updates `Registry.toml` plus the relevant per-package directory atomically. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..418392b --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,41 @@ + +## Summary + + + +## Changes + + + +- + +## RSR Quality Checklist + + + +### Required + +- [ ] No banned language patterns (no TypeScript, no npm/bun, no Go, no Python) +- [ ] SPDX license headers present on all new/modified source files +- [ ] No secrets, credentials, or `.env` files included +- [ ] CI is green (governance, hypatia-scan, codeql, scorecard, secret-scanner) + +### As Applicable — Registry Changes + +- [ ] `Registry.toml` index updated when a package or version was added +- [ ] Per-package `Package.toml` / `Versions.toml` / `Deps.toml` / `Compat.toml` consistent +- [ ] Upstream package meets the quality bar in [GOVERNANCE.adoc](../GOVERNANCE.adoc) +- [ ] Upstream tag exists and matches the registered version + +### As Applicable — Documentation / Infra Changes + +- [ ] `.machine_readable/6a2/STATE.a2ml` updated (if project state changed) +- [ ] `.machine_readable/6a2/ECOSYSTEM.a2ml` updated (if integrations changed) +- [ ] `.machine_readable/6a2/META.a2ml` updated (if architectural decisions changed) +- [ ] `TOPOLOGY.md` updated (if architecture changed) +- [ ] `CHANGELOG.md` updated (or pending auto-generation from conventional commits) +- [ ] Wiki updated for user-facing changes + +## Testing + + diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..480c95e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,52 @@ + + +# Changelog + +All notable changes to `julia-professional-registry` 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](https://github.com/hyperpolymath/standards/pull/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 + +- `CHANGELOG.md`, `ROADMAP.adoc`, `MAINTAINERS.adoc`, `GOVERNANCE.adoc` — bring repo to estate documentation convention. +- `.github/ISSUE_TEMPLATE/{bug_report,feature_request,custom}.md`, `.github/pull_request_template.md`, `.github/CODEOWNERS`, `.github/FUNDING.yml`, `.github/copilot-instructions.md` — estate-standard contributor onboarding fleet. +- `.github/workflows/{scorecard,mirror,secret-scanner,codeql}.yml` — wire the four missing standards reusables (PR #17). +- Wiki: structured pages mirroring repo documentation (Home, Registry-Usage, Packages, Architecture, Testing, Governance, Roadmap). + +### Changed + +- `.github/workflows/governance.yml` — SHA-pin the standards governance reusable (was floating `@main`) (PR #17). +- Consolidate `CONTRIBUTING.md` and `CONTRIBUTING.adoc` into a single canonical Markdown file. + +### Removed + +- `.machine_readable/STATE.a2ml` (root) — moved to canonical `.machine_readable/6a2/STATE.a2ml` per estate structural-drift policy (PR #17). + +### Security + +- Dismissed 17 self-referential `hypatia/code_scanning_alerts/CSA00x` alerts as `won't fix`; root cause fixed at SARIF render layer in [hyperpolymath/hypatia#368](https://github.com/hyperpolymath/hypatia/pull/368). +- Closed seven real open code-scanning alerts via the four reusable wrappers, `codeql.yml@language=actions`, and the STATE.a2ml move (PR #17). + +## [1.0.0] — 2026-04-04 + +### Added + +- CRG Grade C test suite (see `TEST-NEEDS.md`). +- 34 hyperpolymath Julia packages registered via standard Julia Registry layout (Registry.toml + per-letter directories). +- AsciiDoc top-level documentation: `README.adoc`, `EXPLAINME.adoc`, `TOPOLOGY.md`, three `QUICKSTART-*.adoc` files. +- `.machine_readable/` dual-track scaffolding: `0-AI-MANIFEST.a2ml`, `6a2/{STATE,ECOSYSTEM,META}.a2ml`, contractiles, integrations, anchors. +- `flake.nix`, `guix.scm`, `Justfile` — reproducible development environment. +- Idris2 test harness scaffold (`julia-professional-registry-tests.ipkg`, `tests/`). +- Initial workflow fleet: `boj-build.yml`, `casket-pages.yml`, `governance.yml`, `hypatia-scan.yml`. diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index d8ee9d8..0000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,26 +0,0 @@ -= Contributing to HyperpolymathRegistry -:toc: preamble -:icons: font - -This document explains how to contribute to the project. We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -== How to Contribute - -We welcome contributions in many forms: -* **Code:** Improving the core verified stack or extensions. -* **Documentation:** Enhancing AsciiDoc manuals or AI manifests. -* **Testing:** Adding property-based tests or formal proofs. - -== Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` to understand the repository structure. -2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools (Idris2, Zig, Rust). -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -== Contribution Policies - -For detailed rules on branch naming, commit messages, and the PR process, please refer to the machine-readable manual at link:.github/CONTRIBUTING.md[CONTRIBUTING.adoc]. - -== Code of Conduct - -All contributors are expected to adhere to our ethical standards. See link:.github/CODE_OF_CONDUCT.md[CODE_OF_CONDUCT.adoc] for details. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 37747fa..3c12eeb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,10 +14,19 @@ We welcome contributions in many forms: ## Getting Started -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools. +1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` to understand the repository structure. +2. **Environment:** Use `guix shell -D -f guix.scm` (or `direnv allow` if the `.envrc` is honoured) to set up your tools. Guix is the canonical packager per [standards#101](https://github.com/hyperpolymath/standards/issues/101); the prior `nix develop` fallback was retired estate-wide. 3. **Task Runner:** Use `just` to see available commands (`just --list`). +## Registering a Package + +This repo is a Julia package registry. To register a new package or a new version: + +1. Confirm the upstream package meets the registry's quality bar (see [GOVERNANCE.adoc](GOVERNANCE.adoc) — SPDX headers, REUSE-compliant `LICENSES/`, OpenSSF Scorecard baseline, no banned-language files). +2. Add or update the relevant per-letter directory (e.g. a new package `Foo` lives under `F/Foo/`). Each version directory contains the standard Julia registry files: `Package.toml`, `Versions.toml`, `Deps.toml`, `Compat.toml`, `WeakCompat.toml`. +3. Update the top-level `Registry.toml` index. +4. Open a PR titled `feat(registry): register v` (or `feat(registry): add v`). + ## Development Workflow ### Branch Naming diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..00d71e9 --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,122 @@ +// SPDX-License-Identifier: PMPL-1.0-or-later +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) += Project Governance +:toc: +:toc-placement!: + +toc::[] + +== Governance Model + +`julia-professional-registry` follows a *Benevolent Dictator For Life (BDFL)* governance model. This model suits solo maintainers and small teams where rapid, consistent decision-making is more valuable than formal consensus processes. + +The BDFL has final authority on all project decisions, including which packages are accepted into the registry, technical direction, release schedules, contributor access, and community standards. + +[NOTE] +==== +*Transition clause:* When the core team exceeds three active maintainers, this project should transition to a consensus-based governance model with documented voting procedures. That transition should be recorded as an Architecture Decision Record (ADR) under `docs/decisions/`. +==== + +== Decision Making + +=== Day-to-day decisions + +* The BDFL makes final decisions on all matters. +* Routine decisions (registry version bumps, dependency updates, documentation fixes) may be made by any maintainer with commit access. +* Maintainers are expected to use good judgement and seek input on non-trivial changes — particularly any change to the Registry.toml format or to the criteria for package acceptance. + +=== Package registration decisions + +Registry-specific decisions follow this hierarchy: + +* *Trivial registrations* (a new version of an already-registered package) may be made by any maintainer once CI is green. +* *New package registrations* require the BDFL's review. The package must meet the registry's quality bar (SPDX headers, REUSE-compliant `LICENSES/`, OpenSSF Scorecard baseline, no banned-language files). +* *Removals or renames* require BDFL approval and an ADR. + +=== Proposing changes + +* Contributors can propose changes by opening issues or pull requests. +* Significant changes (new acceptance criteria, breaking changes to Registry.toml schema) should be discussed in an issue before implementation begins. +* The BDFL will provide a clear accept/reject decision with reasoning. + +=== Architecture Decision Records (ADRs) + +* Significant technical decisions are documented as ADRs under `docs/decisions/` (created on demand). +* ADR statuses: `proposed`, `accepted`, `deprecated`, `superseded`, `rejected`. +* ADRs provide a historical record of why decisions were made and what alternatives were considered. + +== Roles + +=== BDFL (Benevolent Dictator For Life) + +* The project creator and ultimate decision-maker. +* Sets the project's technical direction and long-term vision (see link:ROADMAP.adoc[ROADMAP.adoc]). +* Has final say on all matters, including maintainer appointments and removals. +* Responsible for ensuring the project adheres to estate-wide RSR standards. + +=== Maintainer + +* Has commit access to the repository. +* Reviews and merges pull requests. +* Triages issues and manages registry releases. +* Upholds code quality, security standards, and the link:CODE_OF_CONDUCT.md[Code of Conduct]. +* Listed in link:MAINTAINERS.adoc[MAINTAINERS.adoc]. + +=== Contributor + +* Anyone who submits pull requests, opens issues, or participates in discussions. +* Does not have direct commit access. +* Contributions are reviewed by maintainers before merging. +* All contributors must follow the link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== Bot + +* Automated agents managed via the hyperpolymath/gitbot-fleet orchestration (rhodibot, sustainabot, finishingbot, etc.). +* Perform automated code review, security scanning, dependency updates, and standards enforcement. +* Bot actions are subject to the same quality and review standards as human contributions. + +== Becoming a Maintainer + +A contributor may be nominated to become a maintainer when they demonstrate: + +1. *Sustained quality contributions* — a track record of well-crafted pull requests that follow project conventions and require minimal revision. +2. *Understanding of estate standards* — familiarity with the Repository Structure Requirements (RSR), security policies, and CI/CD workflows used across the hyperpolymath estate. +3. *Constructive participation* — helpful issue triage, thoughtful code review comments, and mentoring of other contributors. +4. *Reliability* — consistent engagement over a meaningful period (typically 3+ months of active contribution). + +=== Process + +1. An existing maintainer nominates the candidate by opening a private discussion with the BDFL. +2. The BDFL reviews the candidate's contribution history and community interactions. +3. The BDFL approves or declines the nomination, with reasoning provided to the nominator. +4. If approved, the new maintainer is added to link:MAINTAINERS.adoc[MAINTAINERS.adoc] and granted appropriate repository access. + +== Removing a Maintainer + +A maintainer may be removed under the following circumstances: + +* *Inactivity*: No meaningful contributions or reviews for 12 or more consecutive months. The maintainer will be contacted before removal and offered the option to move to emeritus status voluntarily. +* *Code of Conduct violation*: Behaviour that violates the link:CODE_OF_CONDUCT.md[Code of Conduct], as determined through the enforcement process described therein. +* *BDFL discretion*: The BDFL may remove a maintainer for other reasons (e.g., repeated disregard for project standards, loss of trust). Reasoning will be documented privately. + +Removed maintainers are moved to an Emeritus section of link:MAINTAINERS.adoc[MAINTAINERS.adoc] unless removal was due to a serious Code of Conduct violation. + +== Code of Conduct + +All participants in this project are expected to follow the link:CODE_OF_CONDUCT.md[Code of Conduct]. The Code of Conduct applies to all project spaces, including issues, pull requests, discussions, and any forum where the project is represented. + +Enforcement of the Code of Conduct is described in that document. The BDFL serves as the final arbiter in conduct disputes. + +== Amendments + +This governance document may be amended by the BDFL at any time. All amendments will be: + +1. Documented as an ADR under `docs/decisions/` explaining the rationale for the change. +2. Committed to the repository with a clear commit message. +3. Communicated to existing maintainers and contributors via the project's usual channels. + +Substantive changes (e.g., changing the governance model itself) should be discussed with the community before adoption, even though the BDFL retains final authority. + +''' + +Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath). Licensed under PMPL-1.0-or-later. diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc new file mode 100644 index 0000000..4374ce9 --- /dev/null +++ b/MAINTAINERS.adoc @@ -0,0 +1,42 @@ +// SPDX-License-Identifier: PMPL-1.0-or-later +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) += Maintainers +:toc: preamble + +This document lists the maintainers of `julia-professional-registry` and their responsibilities. + +== Current Maintainers + +[cols="2,3,2",options="header"] +|=== +| Name | Role | Contact + +| Jonathan D.A. Jewell +| Lead Maintainer +| https://github.com/hyperpolymath[@hyperpolymath] +|=== + +== Responsibilities + +Maintainers are responsible for: + +* Reviewing and merging pull requests +* Triaging issues and feature requests +* Ensuring registered packages meet the registry's quality bar (SPDX, REUSE, OpenSSF baseline) +* Coordinating package registrations with upstream package maintainers +* Managing registry releases and the `Registry.toml` history +* Responding to security reports (see link:SECURITY.md[SECURITY.md]) + +== Contact + +For maintainer-only matters, contact the lead maintainer directly. For general project questions, open an issue. + +== Becoming a Maintainer + +The project follows the BDFL governance model documented in link:GOVERNANCE.adoc[GOVERNANCE.adoc]. New maintainers are invited by the lead maintainer based on sustained contributions to: + +* Registry quality (registrations, version bumps, compat ranges) +* Tooling (workflows, validators, CI) +* Documentation (wiki, READMEs, architectural notes) + +Once the core team exceeds three active maintainers, link:GOVERNANCE.adoc[the governance model] transitions to consensus-based per the documented transition clause. diff --git a/ROADMAP.adoc b/ROADMAP.adoc new file mode 100644 index 0000000..ddc6b73 --- /dev/null +++ b/ROADMAP.adoc @@ -0,0 +1,75 @@ +// SPDX-License-Identifier: PMPL-1.0-or-later +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + += julia-professional-registry: Roadmap +Jonathan D.A. Jewell +:toc: left +:toclevels: 3 +:sectnums: +:icons: font + +== Vision + +A curated, formally-grounded Julia package registry that aggregates the hyperpolymath ecosystem's Julia packages behind a single `Pkg.Registry.add` entry. The registry is the canonical index; the packages themselves live in their own repositories. + +The registry exists to make the hyperpolymath Julia surface installable without ad-hoc URL juggling, while keeping each package independently versioned and reviewable. + +== Current State (v1.0.0) + +* 34 packages registered (see link:README.adoc[README] for the full table). +* CRG Grade C test coverage achieved 2026-04-04 (see link:TEST-NEEDS.md[TEST-NEEDS]). +* `.machine_readable/` dual-track scaffolding complete with canonical `6a2/` layout. +* OpenSSF Scorecard + CodeQL + Hypatia scan workflows wired via shared reusables. +* Zero open code-scanning alerts post-PR #17 (modulo the in-flight `feat/register-echotypes-krladapter` branch policy artefact). + +== Near Term (3–6 months) + +=== Registry growth + +* Register the remaining hyperpolymath Julia packages as they reach a published 0.1.0 tag. +* Backfill semver compat ranges (`compat` blocks in each package's `Project.toml`) as upstream packages stabilise. + +=== Tooling + +* Adopt the standards link:https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`changelog-reusable.yml`] workflow so `CHANGELOG.md` is generated from conventional commits. +* Move the existing Idris2 test harness from ad-hoc to a reusable contract-testing pattern that consumes each package's `Project.toml` and validates Registry.toml correctness automatically. + +=== Documentation + +* Wiki pages for: registry usage, package authorship, governance, release process. +* Inline cross-links between README package table, individual package READMEs, and Registry.toml `repo` URLs. + +== Medium Term (6–12 months) + +=== Mirror surface + +* Activate the mirror workflow to push to GitLab, Codeberg, Sourcehut, Disroot, Gitea, and Radicle (already wired via standards `mirror-reusable.yml`; toggled via per-repo `vars._MIRROR_ENABLED` Actions variables). + +=== Quality gates + +* Verify every registered package carries: SPDX header, REUSE-compliant `LICENSES/`, OpenSSF Scorecard >= 7, no banned-language files. +* Add a registry-level CI job that fails Registry.toml additions whose upstream repo fails the above checks. + +=== Federation + +* Publish the registry as a JuliaHub-compatible mirror so packages can be discovered via standard Julia tooling without bypassing the registry. + +== Long Term (12+ months) + +=== Verified registry + +* Each package entry carries an attestation of its build provenance (SLSA Level 3+). +* Registry.toml entries are append-only with cryptographic signing of the registry head, allowing offline verification of "this version was in the registry at this time." + +=== Cross-language indexing + +* The hyperpolymath ecosystem spans Idris2, Rust, OCaml, Coq, Lean, Agda, Haskell, Zig, Elixir, and Julia. A future iteration aggregates the per-language registries behind a single discovery surface (probably driven by the `.machine_readable/` ECOSYSTEM.a2ml graph). + +== Non-goals + +* This registry is *not* a fork of the general-purpose JuliaRegistries/General. Packages should be registered in General when they are mature and externally relevant; this registry is the proving ground. +* The registry does not host package source — packages live in their own repos. Registry.toml `repo` URLs are the source of truth. + +== Tracking + +Filed issues and PRs against link:https://github.com/hyperpolymath/julia-professional-registry/issues[the issue tracker] drive the work; this roadmap is the high-level narrative the issues hang off. From 38764e318119b19bbfdd11b0b086cba3527e9adf Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 27 May 2026 20:15:26 +0100 Subject: [PATCH 2/2] fix(ci): scorecard.yml caller permissions match reusable's canonical block PR #17 added scorecard.yml using `permissions: read-all` at workflow level only. The reusable's docstring explicitly states that called-workflow permissions are CAPPED by the caller's block, and that the analysis job needs `security-events: write` + `id-token: write`. Run 26531477593 on main confirms: startup_failure on every push. The same template is in absolute-zero's scorecard.yml and is also startup_failure (3 runs in a row at 12:16, 11:31, 10:47 UTC today), so the bug is estate-wide and should also be fixed at source in standards/scorecard.yml + the canonical caller example. This commit fixes jpr only. Estate-wide fan-out is a follow-up. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/scorecard.yml | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index e40bd25..49310c9 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -8,9 +8,19 @@ on: push: branches: [main] -permissions: read-all +# Workflow-level permissions are read-only. The job that calls the +# reusable upgrades to the writes required by ossf/scorecard-action. +# See the canonical caller block in +# hyperpolymath/standards/.github/workflows/scorecard-reusable.yml -- +# called-workflow permissions are CAPPED by the caller's block, so +# the job-level overrides below are necessary, not redundant. +permissions: + contents: read jobs: analysis: + permissions: + security-events: write + id-token: write uses: hyperpolymath/standards/.github/workflows/scorecard-reusable.yml@42857410898a9f0e3ecae8778cb2c65f7975a260 secrets: inherit