Skip to main content

Roadmap to 1.0.0

Actionable plan from 0.1.0 (first public PyPI release) to 1.0.0 (stable operator contract). Check items off as you complete them; cut a version when that section's exit criteria are met, not on a calendar.

Current split (recommended): GitLab Pages for public docs; VPS for GitLab Runner + edox-ops testing; move production docs to the VPS before 1.0.0.

Related: release-pipeline.md, release-hygiene.md, vps-docs-hosting.md, TODO.md.

Principles​

LineMeaning
0.1.xFix what breaks after first public use; no new operator contracts
0.2.x–0.3.xLearn from real VPS use; ergonomics and docs, not big new subsystems
0.4.xProduction defaults, supply chain, deferred TODO.md items
1.0.0Stable CLI / state / nginx contract + “we run this in production”

0.1.0 — First public release (done)​

Goal: Package exists; operators can pip install edox-ops; release pipeline works.

  • Apache-2.0, PyPI install docs, bump_release.py, tag pipeline
  • Tag v0.1.0 pushed; release commit and CHANGELOG [0.1.0]
  • Install from PyPI on VPS: pip install edox-ops==0.1.0
  • gitlab-runner prepare-ci-host + register --profile ci on VPS
  • One full pass: bootstrap → doctor → dummy project lifecycle (no public docs on VPS yet)

Exit: PyPI install works on your VPS; runner registered; no show-stopper bugs.

0.1.1–0.1.x — Post-release patches (as needed)​

Goal: Stabilize 0.1.0 from real use; patch releases only.

Triggers: PyPI smoke issues, release-script edge cases, doc link fixes, CI tag job failures.

  • Fix bugs found on VPS PyPI install (permissions, distro detection, doctor false positives)
  • Patch bump_release.py / release commit / changelog edge cases if any
  • README / Installation guide corrections from first operator run
  • Tag pipeline variable or docs fixes (TWINE_*, GitLab registry)
  • Curate [Unreleased]; python scripts/bump_release.py --bump patch

Exit: Comfortable recommending pip install edox-ops without caveats.

Do not: new CLI flags, projects.json schema changes, or breaking nginx template changes.

0.2.0 — VPS proof release​

Goal: Prove edox-ops on a real host end-to-end; document recovery; Pages unchanged.

Operations (maintainer)​

  • VPS: bootstrap → host harden → doctor all green
  • Test project: project add → init → deploy → enable → validate (static tree)
  • TLS: certs install → project certs issue → update --tls → enable → HTTPS curl
  • Recovery drill: deploy twice, project backups list, project restore --yes, validate
  • Runner: CI integration (or subset) runs on VPS runner (docker-privileged)

Repository / docs​

  • Add docs/guides/host-recovery.md: backup targets (/etc/edox-ops/, /etc/gitlab-runner/, nginx vhosts, doc trees); rebuild + re-register runner
  • Link recovery guide from vps-docs-hosting.md, Operations page, Installation guide
  • Optional: doctor informational check — installed version vs PyPI latest (no auto-upgrade)
  • Curate CHANGELOG; release 0.2.0

Exit: One VPS completed project + TLS + restore; recovery runbook exists; no open blocks VPS ops issues.

0.3.0 — Docs-on-VPS migration support​

Goal: Same content as Pages on VPS; repeatable updates; Pages stays mirror/preview.

Operations (maintainer)​

  • Register docs project on VPS (e.g. edox-ops-docs) per vps-docs-hosting.md
  • Deploy full website/build/ (including /api/) with correct DOCS_SITE_URL
  • TLS on production or staging hostname (e.g. docs-staging.example.com first)
  • Compare Pages vs VPS: /, /docs/intro, /api/

Repository / docs​

  • Add docs/guides/ci-deploy-vps.md (or extend VPS runbook): docs:build artifact → rsync/scp → edox-ops project deploy; optional .gitlab-ci.yml SSH job skeleton
  • Document dual hosting: production VPS + Pages on .gitlab.io or pages. subdomain
  • Document DOCS_SITE_URL / canonical URL when primary moves to VPS
  • Optional: scripts/fetch_docs_artifact.sh (glab/API) if manual steps are painful
  • Curate CHANGELOG; release 0.3.0

Exit: VPS serves the real doc build; update path documented; Pages still works as preview/backup.

0.4.0 — Production polish​

Goal: Close deferred backlog; tighten supply chain; draft stability policy.

From TODO.md​

  • docs:smoke → esysdox-ops.org when custom domain is live (or smoke Pages + VPS URL)
  • audit:website → --audit-level=high when npm chain is clean
  • Docusaurus onBrokenMarkdownLinks migration in website/docusaurus.config.ts

Release / security​

  • PyPI trusted publishing (OIDC) from GitLab CI; document in release-hygiene.md
  • Optional: signed release tags
  • Dependabot MRs on develop reviewed on a schedule

Docs / product​

  • Add docs/guides/stability.md (draft): supported distros, JSON fields, CLI stability, nginx layout, semver policy before 1.0
  • Keep Development Status :: 4 - Beta in pyproject.toml until 1.0
  • Document or CI-prove self-hosted runner path (not only SaaS runners)

Exit: TODO.md items done or explicitly deferred past 1.0; OIDC or token rotation documented; stability draft reviewed.

1.0.0 — Stable operator release​

Goal: Public commitment to stable behavior; production docs on VPS; PyPI default install.

Go / no-go (all yes)​

  • Production docs on VPS (or documented primary) for ≥2 weeks without Pages-only rollback
  • Restore drill repeated after real doc deploys
  • PyPI default in operator docs; Git checkout marked contributors-only
  • Changelog 0.1 → 0.4 tells a coherent story
  • Optional: second environment (Pi or second VPS) smoke

Repository / release​

  • Finalize docs/guides/stability.md — what 1.0 guarantees vs may change in 1.x
  • pyproject.toml: Development Status :: 5 - Production/Stable
  • Curate CHANGELOG [1.0.0] (operator-focused summary)
  • bump_release.py → 1.0.0; tag v1.0.0; full tag pipeline green
  • GitLab release notes; PyPI project page verified

In scope for the 1.0 stability promise​

  • CLI commands in instructions.md
  • projects.json shape and on-host paths in config.py
  • nginx vhost behavior (HTTP redirect, TLS, rate limits, backup path rules)

OK to defer past 1.0​

  • DNS-01 / wildcard certs, host uninstall, shell completion, RHEL support, off-site backups (S3, restic)

Exit: You would hand this to another admin with public docs + PyPI only; breaking CLI/path changes after 1.0 → 2.0.0.

Suggested timeline (flexible)​

VersionFocus
0.1.xPatch real-world friction after PyPI
0.2.0VPS proof + recovery docs
0.3.0Docs-on-VPS + deploy automation docs
0.4.0TODO.md, OIDC, stability draft
1.0.0Stable label + production confidence

Update this file as items complete; remove checked bullets from [Unreleased] in CHANGELOG.md when they ship in a tagged release.