Public repository migration: draft

Public repository migration: draft#

Status: discussion draft, updated 2026-09-23. The project owner reports the transfer to primo-solver/primo complete. The repository is intended to remain private during preparation; visibility, access settings, and plan-dependent features still need verification. The project owner decided on 2026-09-23 to retain the existing MIT license for Primo. University authorization, documentation restructuring, and publication remain pending work.

Purpose#

Make Primo a community research project that people outside the founding group can build, understand, evaluate, and contribute to. Documentation, original paper-grounded implementation, and reproducible correctness evidence are part of the project’s contribution standard.

The first public release should describe the supported solver accurately and provide a reproducible starting point. New theory support and performance improvements are separate development work, not prerequisites invented for the migration.

Substantial documentation restructuring is a prerequisite for public release. A private transfer into primo-solver can precede it. Merge the intended code, then complete Documentation restructuring before public release against that revision before making the repository public. The three status entry points are a starting point; the underlying reference material, active plans, and historical evidence still need to be separated and rewritten for outside readers.

Decisions and remaining work#

Decision	Agreed direction or working proposal	What remains open
License for Primo-owned code, documentation, and examples	Retain MIT; decided 2026-09-23	Verify publication rights and distribution notices; license selection is settled.
Institutional rights	Resolve with the university before release	Employment, funding, contributor rights, and authority to publish the included material.
Destination	Transfer to primo-solver/primo reported complete on 2026-09-23	Verify private visibility, owners, access configuration, and plan-dependent features.
Public history	Preserve history if the publication audit permits; private transfer is complete as reported	Audit the history before publication; a curated public starting revision remains an alternative if needed.
Contributions	Contributors retain their rights and contribute under MIT	DCO sign-off is proposed; no copyright assignment or separate CLA is proposed at this stage.
Documentation	Restructure against merged code before public release; a private transfer can happen first	Complete Documentation restructuring before public release, then public hosting, release-version URLs, and CI configuration.
Experiment records	Git is authoritative in `primo-solver/results`; SQLite is a generated local query index	Agreed direction; repository setup, schema/tools, artifact retention, lossless legacy import, and coordinated writer cutover remain pending; see Benchmark records in Git with a generated SQLite index.
Governance	Public technical decisions and an explicit route to maintainership	Initial maintainers, organization owners, review authority, and dispute resolution.

Keep the existing standard MIT text in the root LICENSE. The decision retains the current license for Primo-owned code, original documentation, and examples. Publication-rights checks and the contribution sign-off decision remain open.

Inventory third-party code, patches, dependencies, documentation, and benchmark data separately; the choice for Primo-owned material does not replace their terms. Check source and binary distributions separately, including linked dependencies and notices.

Relevant references are the MIT license and the Developer Certificate of Origin. The license choice is settled; the DCO remains a proposed contribution process.

Contribution model#

The proposed contributor-facing guide is Contributing to Primo: draft. It makes documentation part of the pull request, scales validation to the change, and keeps solver correctness and clean-room requirements explicit. It is a draft, not an additional contribution agreement.

Before opening contributions publicly:

Document contributions under MIT and decide any sign-off requirement. Explain what a sign-off certifies and how to provide one; distinguish it from a cryptographic commit signature.
Publish a short root CONTRIBUTING.md that points to the maintained guide, rather than duplicating its requirements.
Publish conduct and security-reporting policies and identify working contact channels. Define how wrong answers, invalid models, and confidential inputs are reported.
Define who reviews soundness-sensitive changes, how reviewers resolve disagreement, and how regular contributors become maintainers.
Keep expensive cluster qualification accessible through maintainers. External contributors should be able to submit a useful change without an account on the founding group’s infrastructure.

Documentation as code#

Documentation as code is an existing project requirement. Source, tests, and affected documentation are maintained and reviewed together. Public hosting and contribution-policy decisions do not defer that requirement.

Documentation has three status entry points, visible in the book navigation:

State	Entry point	Required distinction
What has been done	Current implementation and qualification and component reference pages	Implemented and qualified scope, accepted revisions, evidence, and limitations.
What is being worked on	Active work	Owner, last review date, branch/PR or design, next step, blockers, and acceptance criteria still outstanding.
Open leads	Open leads register	Ideas and follow-ups with evidence, prerequisites, and a next investigation or falsifier; no implied commitment to implementation.

Update these indexes in the same change that advances or closes the work. Partial implementations stay explicit, and completed experiments record whether their changes were accepted or rejected. Historical design and evidence pages retain their dated outcomes and stable links. Their existence is not evidence of current activity or qualification of a later revision.

Primo already authors documentation in docs/ using MyST Markdown, builds it with Jupyter Book, and stores experiment metadata in docs/run-log.json. scripts/build_docs.sh, invoked by make docs, rebuilds all pages and treats Sphinx warnings as errors by default. These are existing mechanisms.

The public workflow should extend them as follows:

Source, tests, and affected documentation are reviewed in the same pull request and merged together. Separate commits within that request are fine.
Reviewers check factual accuracy, examples, limitations, and algorithmic justification as well as whether the documentation builds.
Required CI builds the book. Executable examples get explicit test coverage where they assert solver behavior; a successful book build alone does not check them. Notebook execution is currently disabled in docs/_config.yml.
Publish documentation for released versions and identify development documentation clearly. Include the source revision so claims can be traced to the code being described.
Keep user guides, reference material, design explanations, and dated experimental evidence distinguishable. Historical results remain attached to their measured revisions.

CI, hosting, versioned publication, and additional example checks are proposed work. Writing this plan does not establish that they are configured. Keep the existing MyST/Jupyter Book tooling unless a concrete limitation warrants a change.

Migration milestones#

Each milestone needs a named owner, evidence links, and a recorded outcome before it is marked complete. Owners and dates are not yet assigned.

A private ownership transfer is preparatory work and can precede these release milestones. It does not satisfy the publication audit or change the release gate. Verify destination permissions and feature availability, retain private visibility, and update remotes after confirming the transfer. Local unpushed commits remain in their local clones and need a later push to reach GitHub.

1. Restructure and qualify the documentation#

Execute Documentation restructuring before public release: account for every page, establish reader paths, rewrite current references, separate active work and open leads, and preserve dated evidence and stable links.
Verify examples against the documented source revision, review the rendered book, and include editable documentation in the release archive.
Record the closing review and commits. Do not make the repository public before this gate passes. A private transfer, rights review, and infrastructure planning may proceed before or alongside the documentation work.

2. Establish publication rights and inspect the material#

Resolve university and contributor publication authorization under the retained MIT license, and verify the included notices.
Inventory dependency and data provenance and required notices.
Audit all history, branches, tags, attachments, and hosted artifacts intended for publication for secrets and material without redistribution permission. Ignore rules do not remove previously tracked material.
Review private infrastructure details in scripts and experiment records. Preserve scientifically useful provenance while documenting any redaction; do not rewrite historical evidence to imply that a public rerun occurred.
Record the history decision. If publishing a new starting revision, retain a private archive and a public provenance mapping sufficient to identify the qualified source snapshot, without exposing material removed by the audit.

3. Make the repository usable by an outside contributor#

Reconcile the README, current-status page, and theory documentation on the exact release candidate. Remove obsolete branch language and describe quantified UF and incremental-mode limitations consistently.
Review the three status indexes against the release candidate. Close completed active entries, identify owners and blockers for ongoing work, and separate remaining leads from implemented claims and dated experimental history.
Verify a clean build without local caches or private infrastructure. Document supported platforms, prerequisites, dependency versions, and download checks.
Provide small examples for solving, models, sessions, and quantified input, with expected outcomes and explicit unsupported boundaries.
Adopt the contribution guide and add issue and pull-request templates, citation metadata, and release notes.
Review the source archive contents. The current make archive workflow omits Markdown/MyST sources; decide the public release packaging explicitly so documentation sources remain available and editable alongside each release.
Replace the shared experimental ledger with separate run directories in the planned primo-solver/results repository, as described in Benchmark records in Git with a generated SQLite index. Preserve historical IDs, provenance, and evidence limitations. Generate an untracked SQLite query index from a pinned results commit; publish versioned snapshots and retain large artifacts separately.

4. Configure the organization and verification workflow#

Review primo-solver/primo after transfer: verify private visibility, owners, recovery arrangements, least-privilege access, and available plan features. Set required reviews and status checks where supported.
Run build/tests and the documentation gate in public CI. Provide scheduled or maintainer-run sanitizer, static-analysis, fuzzing, and benchmark jobs as appropriate; record which checks are required for each change category.
Keep execution of untrusted contributions separate from privileged runners, publication credentials, and cluster access.
Assign maintainers to run expensive qualification and attach evidence to the exact candidate being reviewed. Existing correctness gates remain in force.
Configure documentation previews and publication. The book’s repository link now uses the reported destination. Configure and verify edit links and revision-pinned code links as part of the documentation restructuring.
Set up results-repository review and CI, and assign artifact-retention and restoration ownership. Pilot independent contributor submissions, offline collection, index rebuilds, and snapshots before retiring the existing ledger. No database server is required; source/docs builds must not need a results clone.

5. Qualify and publish the first release#

Verify the exact candidate using the applicable existing checks and gates. Do not describe old measurements as fresh qualification of changed behavior.
Publish selected reproducibility artifacts with stable locations, input and executable hashes, commands, limits, and separate correctness/timing results. Record inaccessible datasets or incomplete validation as limitations.
Tag the source and publish release notes, documentation, archives, checksums, and the required license notices.
Update clone URLs, badges, documentation links, automation, and package references; verify the public path with a fresh checkout.
Audit remaining jobs/processes and record the release revision and remaining known issues before the announcement.

The transfer mechanics should be checked against GitHub’s transfer documentation and visibility-change documentation at execution time. Review settings, integrations, retained credentials, and historical logs as part of the migration.

Completion boundary#

This draft is complete when the plan and proposed contribution guide are reviewable and build with the documentation. The migration itself is complete only when rights and policy decisions are recorded, publication checks pass, the documentation-restructuring gate has passed, and an outside user can access and reproduce the released project. Pending publication-rights, sign-off, and governance decisions remain visible until settled.