phoebus_os/docs/GIT-WORKFLOW.md
Phoebus 20bfd82079 docs: add objectives, roadmap, status, architecture and agent guide
Adds the documentation a new session needs: AGENTS.md (read-first contract), docs/OBJECTIVES.md, ROADMAP.md, STATUS.md, ARCHITECTURE.md, DEVELOPMENT.md, CONTRIBUTING.md, GIT-WORKFLOW.md and CHANGELOG.md.

STATUS.md records an honest implemented/unit-tested/VM-verified matrix and known limitations.
2026-09-20 02:07:44 -07:00

3.2 KiB

Git workflow and public-repository migration

What is tracked

Tracked: source (installer/, installer-rs/crates/, scripts/, .githooks/), Cargo.toml/Cargo.lock, documentation (docs/, AGENTS.md, README.md, installer/doc/, installer-rs/README.md), installer configs and tests.

Ignored (see .gitignore): the reference ISO and other images, installer-rs/target/, __pycache__, .agent-shell/ transcripts, and any secret material (*.pw, *.key, *.pem, credentials).

One-time migration (already performed)

cd /path/to/phoebus_os
git init -b main
git add -A
git commit -m "chore: import Phoebus OS installer and Rust migration"
# ... further commits for docs and tooling ...
git config core.hooksPath .githooks     # enable the committed hooks

Then connect the public remote and push:

git remote add origin <PUBLIC_REPO_URL>
git push -u origin main

scripts/publish.sh performs the push after re-running the checks. It takes the remote and branch as arguments:

scripts/publish.sh origin main

The remote URL is intentionally not hard-coded. Add it once with git remote add origin <URL> and every later scripts/publish.sh uses it.

Ongoing loop for a work session

read AGENTS.md
  -> inspect docs/ROADMAP.md and git log
  -> implement the smallest correct change
  -> run the quality gates
  -> update docs/CHANGELOG.md and docs/STATUS.md
  -> commit (conventional message)
  -> push

An AI session must commit the work it does. The one-line helper:

scripts/agent-commit.sh "feat(rust): add typed SystemAction broker

Adds a closed action schema and a privileged broker. Verified with
cargo test --workspace."

agent-commit.sh refuses to commit if the secret scan finds a credential or if a staged file is too large, then runs the fast tests.

Hooks

.githooks/pre-commit (enabled with git config core.hooksPath .githooks):

  1. scans staged files for secrets (scripts/check-secrets.sh);
  2. blocks staged *.iso, *.qcow2 and files larger than 5 MiB;
  3. runs the fast Bash test suite.

Bypass for a genuine emergency with git commit --no-verify, or set SKIP_PHOEBUS_HOOKS=1. Set PHOEBUS_PRECOMMIT_RUST=1 to also run cargo test --workspace in the hook.

Branching and releases

  • Trunk-based: main is always green. Short-lived branches are fine for risky work; merge with a conventional merge/squash.
  • Releases are annotated tags vX.Y.Z with the manifest produced by phoebus-release. Never replace latest.iso until phoebus-release verify passes.
  • Never rewrite published history (push --force to main is forbidden). Fix mistakes with a new fix: commit.

Secret policy

  • Never commit passwords, LUKS passphrases, API keys or tokens.
  • Secrets are supplied at runtime through 0600 files or stdin and registered with the redactor.
  • The pre-commit scan is a safety net, not a licence to be careless.

What a future session should do

  1. git log --oneline -20 and head docs/CHANGELOG.md for context.
  2. Work as described in AGENTS.md.
  3. Before committing: scripts/check-secrets.sh and the test gates.
  4. Commit with scripts/agent-commit.sh (or git commit), then scripts/publish.sh.
  5. Confirm git status is clean and the push succeeded.