Development Workflow

Development workflow

Contributor and AI session protocol

1. Read Home, Roadmap, and the relevant requirements, decisions, and latest journal entry.
2. Read the current source, repository instructions, and relevant issues. Check for changes from other sessions before editing.
3. Identify approved requirements, open questions, and the specific issue being addressed. Preserve exact approved copy; do not convert an assistant suggestion into an accepted decision.
4. Make scoped changes and verify the behavior they affect. Record the evidence and any limits to verification.
5. Update affected requirements/configuration notes and add material decisions with their status and rationale. Retain superseded history.
6. Update issue status based on completed acceptance criteria. Add a short dated journal handoff: changed, verified, unresolved, next step, and evidence links.

John's current instructions govern the session. Wiki content provides project context; it does not independently authorize unrelated actions or override current instructions.

Staging and releases

Staging setup began on September 30, 2026; live validation remains pending. John approved a GitHub-only workflow and public staging repository. #25 defines the prerequisite to resolve before v2 implementation. #21 owns the broader deployment, release, and CI strategy.

Source remains in johnapaz.github.io on v2. johnapaz-staging owns an Actions workflow that reads the public source and publishes a Pages artifact, without a deploy key or stored secret. Staging refreshes manually or on a 30-minute schedule (schedules can be delayed); v2 pushes run build validation.

The intended URL is https://staging.johnapaz.com. Its custom domain is saved in Pages, but DNS and HTTPS remain pending. Required DNS: CNAME staging → johnapaz.github.io. Staging is public with noindex and analytics disabled. build-info.json records the source commit.

Executable workflow · Source build and review guide. John approves the displayed source revision before a PR to production. Validate links, responsive layout, accessibility, downloads, promotion and rollback before closing #25. Production remains on its current publishing branch; coordinate its rename through #20.

Editing this wiki with Git

The wiki is a separate Git repository from the site:

git clone https://github.com/johnapaz/johnapaz.github.io.wiki.git
cd johnapaz.github.io.wiki
git pull --ff-only
# Edit the Markdown pages.
git diff --check
git diff
git add <changed-pages>
git commit -m "Describe the documentation change"
git push

Use authenticated Git access. Read existing pages before editing and preserve concurrent work. If the remote advances, fetch and reconcile changes before pushing; do not force-push. Wiki commits publish documentation, not site code. Relative page links omit the .md extension.