Skip to content

docs: bring repo to estate documentation + contributor convention + substantial wiki - #19

Merged
hyperpolymath merged 2 commits into
mainfrom
docs/complete-estate-conventions
May 27, 2026
Merged

docs: bring repo to estate documentation + contributor convention + substantial wiki#19
hyperpolymath merged 2 commits into
mainfrom
docs/complete-estate-conventions

Conversation

@hyperpolymath

Copy link
Copy Markdown
Owner

Summary

Brings julia-professional-registry to the same documentation completeness as hyperpolymath/hypatia, hyperpolymath/standards, and the rest of the well-organised estate. Pairs with PR #17 (the CI hygiene canary) to leave the repo in a "ready to merge to main, single-main reconciled" state.

What changed

Top-level docs (Phase 1)

  • + CHANGELOG.md — Keep-a-Changelog format with [Unreleased] capturing the work of PR fix(ci): close 7 real code-scanning alerts (canary for estate sweep) #17 and this PR + a backfilled [1.0.0] for the 2026-04-04 CRG-C release; points at the standards changelog-reusable.yml for future auto-generation.
  • + ROADMAP.adoc — vision, near/medium/long-term sections, non-goals, tracking.
  • + MAINTAINERS.adoc — current maintainer table + responsibilities + nomination hook.
  • + GOVERNANCE.adoc — BDFL model adapted to registry context (package-registration decision hierarchy added on top of the hypatia template).
  • - CONTRIBUTING.adoc — removed; was duplicate of CONTRIBUTING.md in a second format.
  • **~ CONTRIBUTING.md** — corrected the dev-env line from nix develop to guix shell -D -f guix.scm per standards#101; added a "Registering a Package" section.

.github/ template fleet (Phase 2)

  • + .github/CODEOWNERS — default @hyperpolymath + per-area assignments for Registry.toml, workflows, machine-readable, security.
  • + .github/FUNDING.yml — sponsor button.
  • + .github/pull_request_template.md — RSR checklist + registry-specific subsection (Registry.toml + per-package TOML consistency + upstream quality bar).
  • + .github/copilot-instructions.md — estate banned-languages + registry directory shape + SHA-pin requirement for wrapper workflows.
  • + .github/ISSUE_TEMPLATE/bug_report.md — registry-tailored (Pkg-aware repro, package-row reference).
  • + .github/ISSUE_TEMPLATE/feature_request.md — with an estate-alignment field so drift away from standards is surfaced.
  • + .github/ISSUE_TEMPLATE/package_registration.md — new template; registration is the most common kind of issue this repo sees, and a structured template enforces the quality-bar checklist from GOVERNANCE.adoc.

Wiki (Phase 3, pushed to julia-professional-registry.wiki)

Replaced the placeholder "Welcome to the wiki" with nine substantive pages plus a sidebar:

  • Home — landing page with quick links and at-a-glance table
  • Registry-UsagePkg.Registry.add, install, update, remove, troubleshooting
  • Packages — full table of 34 registered packages with descriptions + on-disk layout + cross-references
  • Registering-a-Package — quality bar + step-by-step (directory structure → Registry.toml → PR title convention → review flow), plus yank/update guidance
  • Architecture — full repo module map, component roles, workflow table, "what this is not"
  • Testing — CRG-C grade context, what is/isn't tested at the registry level, local-run instructions, CI gates, path toward Grade B
  • Governance — BDFL summary, role table, decision flow, becoming-a-maintainer
  • Roadmap — near/medium/long-term + non-goals + how to influence
  • Security — reporting, response timeline, safe harbour, code-scanning posture, self-echo note pointing at hypatia#368
  • _Sidebar — wiki nav grouped by Getting-Started / Maintainers / Project / External

Every wiki page links back to the canonical file in main and is explicit that the file wins on disagreement.

Why now

You asked: "is everything fully documented for humans and machines, everything cleaned up and organised, with the wiki complete and substantial, and is there anything that needs updating in the dot files or elsewhere before it can be merged to the main branch, and the other branches reconciled similarly to leave that single main?"

This PR + PR #17 are the answer for the docs/dotfiles/wiki axes. PR #16 reconciliation is the remaining piece; tracked separately.

Test plan

🤖 Generated with Claude Code

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) <noreply@anthropic.com>
@hyperpolymath
hyperpolymath enabled auto-merge (squash) May 27, 2026 19:06
…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) <noreply@anthropic.com>
@hyperpolymath
hyperpolymath merged commit 6818380 into main May 27, 2026
5 of 14 checks passed
@hyperpolymath
hyperpolymath deleted the docs/complete-estate-conventions branch May 27, 2026 19:20
hyperpolymath added a commit that referenced this pull request May 27, 2026
)

After today's wave (#16 EchoTypes + KRLAdapter, #18 ViperPkg, #20
EchoTypes v0.2.0) Registry.toml carries 37 packages, but README's
table and the [Unreleased] CHANGELOG section both reflected the
pre-wave 34-package snapshot. Catch up the human-facing listings:

  README.adoc: add EchoTypes, KRLAdapter, ViperPkg rows
               (alphabetical insertion; EchoTypes pinned at v0.2.0
                per the registered head, the other two at v0.1.0).

  CHANGELOG.md [Unreleased]:
    Added       — registry entries for the 3 packages
    Changed     — the scorecard.yml regression fix from PR #19
    Wiki line   — actual page count (9 + _Sidebar) and missing
                  Registering-a-Package + Security pages noted
    ISSUE_TEMPLATE list now matches what was actually added
                  (package_registration replaces "custom")

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant