Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
Versioning & Release Process
Version Format
PortOS uses semantic versioning: Major.Minor.Patch
| Component | Description | When Incremented |
|---|---|---|
| Major | Breaking changes | Via /do:release slash command |
| Minor | New features | Via /do:release slash command |
| Patch | Bug fixes, refactors | Via /do:release slash command |
Example progression: 0.22.0 → 0.22.1 (fix) → 0.23.0 (feature) → 1.0.0 (breaking)
Branches
| Branch | Purpose |
|---|---|
main |
Active development |
codex/release-* |
A candidate pinned to the development commit captured at kickoff |
release |
Merge the validated candidate here to trigger publication |
Workflow
Version Bumping
Version is managed by the /do:release Claude Code slash command (provided by the slashdo skill). Do not bump package.json version manually during development.
CI Validation
The CI workflow runs on pull requests targeting
main or release, a nightly schedule that checks main, manual dispatch
(workflow_dispatch), and reusable-workflow calls (workflow_call). It plans
the required tests and linting for each run; CI does not change the version.
Direct pushes to main do not start this workflow. Run npm run pregate
before every push and again after rebasing onto a moved base, as required by
AGENTS.md.
On candidate promotion to release
- Release workflow triggers
- Creates git tag with current version (e.g.,
v1.31.0) - Generates GitHub release with changelog (priority: exact
.changelog/v{version}.md→ pattern.changelog/v{major}.{minor}.x.md→ fallback commit log) and uses the changelog's named first heading as the release title - If a pattern changelog file (
.changelog/v{major}.{minor}.x.md) was used, archives it by renaming to the exact version file onmain - If the archive step ran, only
mainadvances;releasestays on the CI-verified commit until the next promotion
Regular Development
# Work on main or feature branches
git checkout main
git pull
# Make changes, commit with a human-readable message (this becomes the
# release-note source — no changelog file or fragment to write)
git add [changed files]
git commit -m "fix: daily log no longer double-saves on blur"
git fetch origin main
# Rebase only for conflicts, enforced branch policy, or evidenced integration risk
# git rebase origin/main
npm run pregate
git push
The default pregate is lint/formatting, structural guards and focused tests.
Hosted CI owns broad validation; use npm run pregate -- --full only when
explicitly needed locally. Focused receipts never attest unrun CI suites.
A conflict-free feature branch may merge behind main once its current-head
required checks and configured reviews pass. Do not restart validation solely
because another agent merged; follow the merge policy.
See .changelog/README.md — release notes are
synthesized from commit history by /do:release, not staged during development.
Creating a Release
Use /do:release with this documented project procedure, which takes
precedence over slashdo's generic live-source promotion recipe. Release preparation
and the release PR use a dedicated candidate branch; never use live main as the
PR head. There is no requirement to empty the issue or PR queue.
1. Capture once at kickoff, or recover the existing candidate
Before version selection, backlog work, or validation, inspect existing release
PRs/candidate branches. Resume an interrupted candidate with its original cutoff,
release base, previous published tag, and version. Do not recut it from today's
main, bump its version again, or take over a live owner's release. If a legacy
open release PR uses main as its head, move the promotion to a dedicated branch
at its recorded validated SHA and close the superseded PR with a link. If no such
SHA was recorded, explicitly record a new cutoff and validate it from scratch;
never treat old checks as proof of the new tree.
For a new candidate, the first fetch of main is the cutoff. If the launcher
supplied a verified exact kickoff SHA, use that instead. A timestamp cannot recover
an earlier trigger-time commit. Capture before any potentially lengthy work. Use a
unique candidate name and an unused worktree path; never reset an existing branch:
set -e
# PRIMARY is the existing primary checkout; WORKTREE is a new isolated path.
# Keep these values in the run's record, not only in transient shell variables.
CANDIDATE_BRANCH="codex/release-$(node -e 'console.log(crypto.randomUUID())')"
git fetch origin "refs/heads/main:refs/heads/$CANDIDATE_BRANCH"
RELEASE_CUT_SHA=$(git rev-parse "$CANDIDATE_BRANCH^{commit}")
git fetch origin refs/heads/release
RELEASE_BASE_SHA=$(git rev-parse 'FETCH_HEAD^{commit}')
git worktree add "$WORKTREE" "$CANDIDATE_BRANCH"
git worktree lock --reason "Active release candidate $CANDIDATE_BRANCH" "$WORKTREE"
node scripts/link-worktree-deps.js "$PRIMARY" "$WORKTREE"
Resolve the previous published version tag and its peeled commit from the
captured release history (not the latest tag on moving main). Verify the GitHub
Release, notes and tag agree. Reconcile an interrupted publication at its original
commit before attempting a new version; never move an existing tag. A concurrent
release owner or conflicting version requires reconciliation, not another release.
Before changing files or starting validation, create a metadata-only commit in the
candidate worktree with commit trailers Release-Cut, Release-Base,
Release-Previous-Tag, and Release-Previous-Commit, each carrying the exact
resolved value. For example, use git commit --allow-empty with subject
chore: pin release candidate and those trailers in its body. The parent of that
commit must equal RELEASE_CUT_SHA. This persists the cutoff in the candidate's
history, including after a push, interruption, or a different agent resuming.
Copy those identities, the branch and chosen version into the release PR body.
The candidate must contain the captured release-base history. Normally the previous
release has already been synchronized into main. For a legacy release merge not
in main, merge only the captured RELEASE_BASE_SHA into the candidate and verify
that the tree is unchanged; an unexpected content change is a reconciliation
blocker. Do not merge the latest main to fix ancestry. Record any such ancestry
merge in the candidate ledger.
2. Prepare and validate only this candidate
Choose the version and synthesize .changelog/v{version}.md from the previous
published tag through the pinned candidate. Count only substantive changes in
that range for readiness (at least two); exclude metadata-only commits. Update
all version-bearing package/lock files according to their existing conventions.
Keep the named first heading described in the changelog guide.
Commit preparation on the candidate, not on main first.
Open issues, open PRs, dependency-bot updates, and commits merged after
RELEASE_CUT_SHA belong to the next release. Do not sweep them in, wait for their
CI, trigger branch reconciliation, rebase on main, or merge main into the
candidate. The scheduled task's in-flight/dependency options apply only to
candidate-gating fixes. A quality snapshot already present at the cutoff is
included; a newly published snapshot goes to the next release and does not move
or delay this cutoff.
Run the documented release checks from the candidate worktree: provision
portos_test with npm run setup:db:test, run npm run test:db, and run
npm run pregate -- --full before pushing. Never use the production database.
Report any locally unavailable stage and require its CI result. Review the full
previous-published-commit-to-candidate diff, not just the preparation commit.
3. Admit only evidenced release-gating fixes
A failing candidate test/build/CI check or an accepted review finding that applies
to its tree can gate the release regardless of severity. An issue's existence,
an unrelated PR, or a defect only in later main does not. Preserve the evidence
and fix the root cause; do not weaken tests or declare an unexplained rerun clean.
For each exception, record the failure/finding, why it applies to this candidate,
the exact fix commit(s), and validation in the PR's Candidate amendments
ledger. Implement the smallest fix directly on the candidate, or cherry-pick the
specific reviewed fix commit from main (including only necessary, separately
justified prerequisites). Never merge all of updated main. Preserve active
owners and normal trusted-review/admission boundaries. A broad fix that cannot be
safely isolated remains an explicit blocker; do not silently expand the release.
An amendment changes the candidate head: update the notes if needed and rerun
affected local checks, pregate, required review and full promotion CI for that
head. Merely advancing main changes none of these inputs and does not invalidate
candidate validation. Record candidate-only fixes for forward-porting to main.
4. Promote the exact validated candidate
Push the candidate after pregate and run node scripts/pregate-attest.js; an
attestation refusal leaves full CI in charge. Create the PR with
--head "$CANDIDATE_BRANCH" --base release, including the cutoff identities,
previous-tag comparison, chosen version/name and amendment ledger. A PR targeting
release forces full CI regardless of its head branch; require both CI Gate
and Full CI Gate on the current candidate head.
For the repository's pre-merge structural guard, compare the candidate against
origin/release, its actual PR base, not origin/main. Before merging, verify
the PR head still equals the validated candidate SHA and the target still equals
RELEASE_BASE_SHA. Hold merge admission only for the final live-state check,
merge attempt and readback. Use a merge commit and --match-head-commit with the
validated head; never squash/rebase away the candidate ancestry, bypass required
checks, or use a moving main PR. If the target changed, release admission and
reconcile the competing release/version and resulting tree outside the lease.
It is not permission to recut from main or reuse checks on a different tree.
5. Verify publication
Read back MERGED, the merge commit and the remote release ref. Confirm the
promoted tree equals the validated candidate tree. Watch the Release workflow
for that merge SHA. The workflow creates the tag at its triggering SHA and
checks its tree before and after publication; never create the version tag by
hand. Verify the tag tree, version, named notes and published, non-draft,
non-prerelease GitHub Release. A merged PR alone is not completion.
6. Synchronize back without changing the published release
After publication, open a normal release → main synchronization PR and
merge it with a merge commit after its own required checks/reviews/admission.
This carries version metadata, notes and candidate-only fixes back to development
and preserves the release merge ancestry for the next candidate. Run the
repository-required quality snapshot after publication as a development update;
it never changes this release. If conflicts require edits, use a temporary sync branch containing the published release commit
and the current main, resolve them there, and merge that branch into main.
Preserve newer development work. Never retarget the candidate, tag, or release
ref to main, and never back-merge development commits into the published tree.
Keep synchronization failures tracked with the exact PR, owner and next step; they do not invalidate an already verified publication or require revalidating it. Before a subsequent release, verify the prior published release is reconciled into development, so its version/fixes are not lost or released twice. Clean up only owned temporary branches/worktrees after preservation and ancestry verification, releasing only this run's worktree lock.
The final report identifies cutoff SHA, candidate SHA, amendments, promotion PR,
published tag/release URL, and the synchronization outcome. Later main commits
remain unreleased until the next candidate is captured.
CI Skip
Use [skip ci] in commit messages to prevent CI from running (used by automation for changelog archives).