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.
101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
# 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)
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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.
|