Normal CI runs Linux checks and the Darwin no-Helix evaluation guard on push,
pull request, and manual dispatch
The Home Manager evaluation guard overrides nixpkgs with the reviewed revision
in checks/newer-nixpkgs.txt on Linux and Darwin, exercising the consumer
follows path with the existing configuration and package-override cases.
Ordinary CI evaluates this override; heavy compatibility builds run in Version Gate.
Publish Nix Cache publishes Linux and Darwin capability variants, the Main and
Edge Linux full-package launcher outputs, and representative Home Manager closures
from main and manual dispatch. Both jobs push the requested output closures
synchronously, including substituted outputs. Missing credentials or failed
uploads fail the job. Version Gate is manual. Its Linux job installs all four
profile shapes, runs release contracts, and builds the complete Home Manager
check with the reviewed nixpkgs override. macos-package-smoke retains the
locked-input Darwin packages, Home Manager, Rio, no-Helix, and host-Yazi checks.
Three dependent Darwin jobs exercise the same reviewed override:
darwin-corebuildsyazelix-no-rio-no-helix-no-yaziand publishes its closure.darwin-editorrestores the core closure, buildsyazelix-no-rio, and publishes it.darwin-integrationrestores both closures and builds the completechecks.aarch64-darwin.home_manager, including Rio and all configuration and installed-command assertions. It does not publish another closure.
Each stage checks out the same candidate SHA and reads checks/newer-nixpkgs.txt.
Prerequisite paths come from successful job outputs. nix-store --realise restores
those exact closures through the configured caches, including Cachix and
cache.nixos.org; Cachix omits paths already available upstream. Local and remote
builds are disabled during restoration. Missing paths or failed restoration,
build, or publication fail the stage. Rerun a failed job after
addressing its failure; completed prerequisites remain in the shared cache.
Cache writes use the existing CACHIX_AUTH_TOKEN only in the two prerequisite
jobs. Stages reject dispatches outside the canonical repository's edge, main,
and stable branches before checkout or credential use. Missing publication
credentials fail explicitly; fork and tag dispatches cannot pass this gate.
There are no compatibility push/PR triggers, store archives, retention pins,
or additional cache services. Only the two requested runtime closures are
published; common store paths are deduplicated under the existing cache policy.
Logs include exact paths, closure sizes, elapsed build time and runner disk use.
Closure size is an upper bound on added cache storage, not measured cache growth.
Version Gate permits one active and one pending run. Five native jobs have
90-minute limits and release-gate has five minutes, bounding configured runner
time at 455 minutes per invocation. Linux keeps two Nix build jobs, Darwin one,
with two cores each. Stage limits retain the existing cap until native timings
support tighter bounds. The aggregate requires all five jobs to succeed, even
after a dependency fails; failed, cancelled, or skipped work cannot satisfy it.
Manual workflow checks do not appear in GitHub's protection status summary.
The aggregate publishes its result as the release-gate commit status for the
exact candidate. Only this canonical-repository job has statuses: write;
failed publication fails the gate. Branch protection keeps requiring that status.
Review the comparison pin deliberately and verify all native stages when
changing it. This proves the reviewed pin, not every future nixpkgs revision.
Retain compatibility failures and measured limits before expanding the CI budget.
Darwin Package Smoke runs the same Darwin verification weekly on Monday when
main has commits in the last 7 days, and on manual dispatch always, while
idle weeks skip the macOS build. Both package-smoke jobs assert that Darwin packages
contain no Linux desktop entry. The flake advertises the optional Yazelix
Cachix cache, while source builds remain valid without it. Use Version Gate
before publishing a release
Linux CI and Darwin Package Smoke build helix_grammar_sources, Nova Helix's
HELIX-GRAMMAR-SOURCES-001 check. It rejects Codeberg network fetches during Nix
evaluation and compiles the pinned Codeberg grammars from bundled, hash-verified
sources. Grammar revisions and snapshot maintenance belong to Nova Helix.
The Linux-only startup_picker_cancellation check reuses Anima's pinned Kinestra
input to exercise the quick-search/Yazi toggle, retained browse location,
successful handoff, exact later-tab cancellation, and sole-tab session exit on a
private X display. Shared acceptance still requires Darwin Package Smoke on the
exact revision; macOS interaction remains unverified.
The Linux-only pane_move_ordering check uses the same private display to verify
circular work-pane movement, rapid opposite moves and fixed UI panes through
packaged Rio and Zellij.
All development commits land on edge, including fixes, reverts,
documentation, and Beads updates. CI runs there, and users who select edge
accept the active experimental dogfood channel.
Keep stable ⊆ main ⊆ edge on one linear history. A promotion includes every
accumulated commit up to the candidate, including changes unrelated to the fix
that motivated it. Review that whole range. If intervening work is unaccepted,
accept it, revert it on edge, or defer promotion. Do not cherry-pick fixes,
commit directly to the promotion channels, or skip a channel.
main is promotion-only accepted development. After an edge revision is
accepted and verified, advance main to that exact revision without merging or
cherry-picking. CI and cache publishing run on main, and users who select it
accept more frequent updates than stable:
git fetch origin edge main
git merge-base --is-ancestor origin/main <sha>
git merge-base --is-ancestor <sha> origin/edge
git log --oneline origin/main..<sha>
git diff origin/main <sha>
git push origin <sha>:mainThe protected stable branch accepts fast-forward promotions from main. Its
required checks are linux, publish_x86_64_linux,
publish_aarch64_darwin, and release-gate, sourced from GitHub Actions.
main requires linux. Both branches enforce checks for administrators,
require linear history, and reject force-pushes and branch deletion.
Before promotion, verify that the candidate descends from the current stable,
belongs to main, passes all required checks on that exact SHA, and has no
known P0 or P1 regression. User-visible runtime interaction changes also need a
fresh-session dogfood pass. Ordinary promotions wait at least seven days after
the last Stable promotion, including an urgent one. Routine documentation and
planning changes wait for that window. Explicitly requested urgent fixes may
skip the wait, with the same verification and acceptance of the whole candidate.
There is no automatic weekly release and no release when the gate fails.
Record the candidate range, exact proof, actual promotion time, and any urgency reason in the owning Bead. Use the actual previous promotion time, not the source commit date. GitHub enforces status and linear-history requirements; checking predecessor membership, cadence, acceptance, and dogfood remains the maintainer's responsibility. Run the push only after all checks pass:
git fetch origin main stable
git merge-base --is-ancestor origin/stable <sha>
git merge-base --is-ancestor <sha> origin/main
git log --oneline origin/stable..<sha>
git diff origin/stable <sha>
git push origin <sha>:stableSkip promotion when no candidate meets the contract. To roll back, commit the
revert on edge, verify it, promote it to main, and then promote it through
the same stable path. Do not move stable backward.
End each GitHub release body with this sponsorship footer, once:
If Yazelix saves you time, you can support continued development on [GitHub Sponsors](https://github.com/sponsors/luccahuguet).For existing releases, save the original body and metadata, append only the footer, and verify the published body, tags, titles, flags and assets through the GitHub API.
Lucca owns a monthly dependency review and may delegate it to an agent. Review
the current Edge pins during the first maintenance session each month; an
available update does not require adoption. Prefer suitable official releases
for third-party tools. Use reviewed commits where the dependency's integration
branch or release model requires them. Versions remain owned by flake.nix,
flake.lock, package definitions and child manifests.
Nova Bar, Anima, Popup and the pane orchestrator share Nova Bar's Fenix input
and its followed root nixpkgs. Review all four consumers when either input
changes, including native WASI builds and Popup interactions. The pane
orchestrator, Popup, Radar and zjstatus share flake-utils. Nova's follows
declarations own this selection; each child retains its build recipe.
Helix keeps its independent overlay so Rio updates do not select its development
tools. Other toolchain alignment requires an explicit maintenance benefit and
compatibility decision. Compare affected derivations across supported systems;
equal repository names or Rust versions alone do not establish equivalent builds.
Review related changes together: Yazi and ya must stay paired with compatible
schemas, presets and plugins. Review nixpkgs deliberately because child inputs
that follow it share the changed package graph. Consume verified first-party
fixes and features, such as a Radar fork revision, when Nova needs them without
waiting for the monthly review. Compare forks with their intended integration
branch; a newer commit elsewhere does not make the accepted pin stale.
Relevant security fixes and serious user regressions receive prompt review. Major or API-breaking updates may wait for dedicated compatibility work. Choose updates for a concrete benefit and keep unrelated changes separable; the review does not authorize a broad lock refresh or automatic merge.
Start with release notes, source comparisons and focused local checks. Selected
updates follow the existing CI, local verification
and platform gates in AGENTS.md: shared package changes need exact-revision
Linux CI, Darwin Package Smoke and installed-artifact proof, plus fresh-session
dogfood for interaction changes. Discovery alone needs no native builds. Keep
existing build limits; diagnose a failed candidate, narrow the update or defer
it with its reason and revisit condition in the owning maintenance Bead. One
review may record several deferrals without creating an issue for each version.
Record the review date, inspected revision and outcome even when no update is
selected. Schedule material implementation work separately under the issue rules.
Monthly review balances staleness against maintainer effort and native build cost. Weekly broad updates spend that budget too often; release-only review can leave dependencies unattended. Adoption on Edge and channel promotion remain separate decisions; the Stable interval does not schedule dependency bumps.
The Dependency Updates workflow reports available changes in its Actions run summary on the first of each month at 12:23 UTC and on manual dispatch. It checks out Edge once and identifies that inventory's exact revision. Open Dependency Updates, select a run and read its summary. To request a report:
gh workflow run dependency_updates.yml --repo Yazelix/nova --ref edgeGitHub runs schedules from the default branch, Main. Scheduling becomes active when the workflow reaches Main through normal promotion; an Edge-only workflow does not establish an active schedule. GitHub may delay scheduled runs, so a missing report does not replace the maintainer's monthly review.
The report groups Yazi/ya integration pins and covers direct flake inputs plus
Nova's explicit Yazi and tokenusage packages. GitHub supplies full releases and
exact branch comparisons; crates.io supplies tokenusage's stable release.
Comparison branches absent from commit-pinned URLs live in
.github/scripts/dependency_report.py; current versions stay in their manifests.
New pinned sources without comparison policy require review. The two explicit
package readers accept their existing literal Nix declarations and report an
incomplete inventory if those declarations become computed or change shape.
Nixpkgs tool versions and child internals remain with their owners.
Available updates, pins ahead of branches and divergent history are review findings. Missing policy, malformed data and failed API requests mark the report incomplete and fail the run. Nothing updates pins, builds packages or decides compatibility. One canonical-repository Linux job has a ten-minute limit, read-only access and one active run. API requests have eight-second socket timeouts, a 4 MiB response limit and no retries. There are no custom secrets, cache writes, uploaded artifacts or issue notifications. Expand the budget only when measured coverage or failures justify it; simplify or remove the checker if its reports do not assist review.
Run the offline report contract without credentials or network access:
python3 -B -m unittest discover -s .github/scripts -p 'test_dependency_report.py'Use local sibling repositories while hacking runtime inputs:
nix run --override-input rio ../nova-rio
nix run --override-input yazelixZellij ../nova-zellij
nix run --override-input yazelixHelix ../nova-helix
nix run --override-input yazelixForest ../yazelix-forest
nix run --override-input zjRadar ../zj-radar
nix run --override-input yazelixZellijPopup ../zellij-popup
nix run --override-input novaBar ../nova-bar
nix run --override-input yazelixZellijPaneOrchestrator ../zellij-pane-orchestrator
nix run --override-input yaziBistro ../yazi-bistroFor coupled child changes, use the same complete override set for builds, checks, and every dogfood profile refresh. The profile does not retain overrides. Publish matching child revisions and lock them before verifying without overrides. Check popup open/hide and sidebar toggle together in a fresh installed session.
Useful local checks:
nix flake check
nix flake show --all-systems
nix build .#yazelix --no-link --print-build-logs
nix build .#yazelix-no-helix --no-link --print-build-logs
nix build .#yazelix-no-helix-no-yazi --no-link --print-build-logs
nix build .#checks.x86_64-linux.rio_contracts --no-link
nix build .#checks.x86_64-linux.host_yazi_contracts --no-link
nix build .#checks.x86_64-linux.no_helix_contracts --no-link
nix build .#checks.x86_64-linux.yzx_yazi_materialization --no-linkRun the release compatibility check locally on the matching native platform
(replace x86_64-linux with aarch64-darwin on Apple Silicon):
nix build --no-link --no-write-lock-file --print-out-paths --print-build-logs --override-input nixpkgs (open --raw checks/newer-nixpkgs.txt | str trim) .#checks.x86_64-linux.home_managerRuntime package changes should also pass a temporary profile install:
nix profile add --refresh /absolute/path/to/yazelix --profile /tmp/yzx-profileDetailed launch, config, editor, and shell contracts live in Runtime Notes
The Rio configuration contract can be exercised against a candidate native binary
with YZX_TEST_RIO set to its absolute path: run the yzx-config crate test
rio_native_controls_preserve_validate_reset_and_respect_ownership with
--include-ignored. It covers real native validation, preserved comments, reset,
invalid-document fallback, Home Manager protection, and Rio-free models. Ordinary
crate checks omit this external-tool test; the packaged rio_contracts check also
validates the seeded config through the exact pinned Rio executable.
Counts raw physical lines in tracked project files. Code and configuration
includes every counted file except Markdown, plain-text inventories, and the
license; those form documentation and text. Beads state (.beads/),
lockfiles (*.lock), and binary assets are excluded. New owned files count
automatically once committed. The pre-Rio baseline is 446d2e25.
git ls-files | grep -Ev '^\.beads/|\.lock$|^assets/' | grep -Ev '\.(md|txt)$|^LICENSE$' | xargs wc -l | tail -n 1
git ls-files | grep -Ev '^\.beads/|\.lock$|^assets/' | grep -E '\.(md|txt)$|^LICENSE$' | xargs wc -l | tail -n 1| Category | Current | Pre-Rio | Difference |
|---|---|---|---|
| Code and configuration | 25,790 | 23,575 | +2,215 |
| Documentation and text | 5,200 | 3,930 | +1,270 |
| Total | 30,990 | 27,505 | +3,485 |