#Development workflow

#Editable installs

rlsbl dev install installs a project locally for development using the target's native editable install mechanism. It detects project targets, calls each target's dev_install_command() to get the install spec, and runs it.

#Per-target install commands

#Modes

When neither --global nor --venv is passed, --global is the default. The two flags are mutually exclusive.

#Uninstall

rlsbl dev install --uninstall reverses a previous install by invoking each target's native removal command. The uninstall mechanism is stateless -- rlsbl does not track which packages were installed, so it relies entirely on the ecosystem's own uninstall tooling to determine what to remove:

#Monorepo mode

In a monorepo workspace with multiple independently-versioned projects, rlsbl dev install requires an explicit filter flag to specify which projects to install. Without a filter, the command errors with guidance rather than installing everything by default, preventing accidental system-wide installation of dozens of packages:

Without a filter flag, the command errors with guidance. Install and uninstall operations apply recursively to matching projects.

#Watch and CI monitoring

rlsbl watch [<sha>] polls GitHub Actions for a commit's CI runs and reports pass/fail results in real time, with automatic retry on transient failures. It discovers runs by commit SHA (defaulting to HEAD), watches them concurrently, and sends desktop notifications on completion with links to the relevant GitHub page.

#Behavior

1. Discovery -- polls gh run list --commit <sha> until at least one run appears (up to 30 seconds)
2. Parallel watching -- all discovered runs are watched concurrently via gh run watch
3. Auto-retry -- if a workflow fails, it is automatically re-triggered once via gh workflow run (unconditional -- does not distinguish failure types). The retry run is then watched to completion.
4. Late-starting workflow detection -- after initial runs complete, polls once more for workflows that started late (e.g., publish/deploy workflows triggered by a GitHub Release created during CI). Late runs are watched with the same parallel/retry logic.
5. Workflow audit -- prints a summary table of all workflows that ran. Warns if a publish workflow exists on disk but did not trigger for this commit.
6. Desktop notifications -- sends a notification on completion:

- On failure: opens the Actions page for the failed run - On success: opens the GitHub Release page (if a tag exists for this commit)

#Flags

#Pre-push hook

The .git/hooks/pre-push hook captures git's stdin into the RLSBL_PUSH_STDIN environment variable and runs rlsbl check --tag prepush, enforcing changelog coverage, gitignore safety, and test suite execution before any commits reach the remote. This hook is installed by rlsbl scaffold and uses the V5 template format. It runs all prepush-tagged checks in dependency order:

1. **prepush-changelog-coverage** (error) -- verifies every pushed commit has a JSONL changelog entry. Commits that only touch .rlsbl/changes/ or CHANGELOG.md, and commits with an Autogenerated: true trailer, are automatically exempted.
2. **prepush-gitignore-guard** (error) -- blocks the push if rlsbl-managed files (e.g., .rlsbl/changes/unreleased.jsonl, CHANGELOG.md) are gitignored.
3. **prepush-manual-warning** (warn) -- warns when a push targets a release branch (configured via release_branches in .rlsbl/config.json) and did not originate from rlsbl release run or rlsbl release undo. Non-blocking.
4. **test-suite** (error) -- runs the project's test suite (pytest / go test / npm test). Depends on prepush-changelog-coverage -- if changelog coverage fails, the test suite is skipped (fast checks fail first).

#Key differences from the old system

• Version-tag pushes are no longer exempt. All checks always run, regardless of whether the push contains a version bump commit.
• Fast-fail ordering. Dependency ordering ensures cheap checks run before expensive ones. If prepush-changelog-coverage fails, test-suite is skipped entirely.
• Unified check system. The pre-push hook uses the same rlsbl check infrastructure as release validation, with consistent reporting and severity handling.

#Monorepo behavior

In monorepos, the pre-push hook runs from the repo root. The test-suite check hard-errors at workspace root because it needs a specific project directory. The test-suite-workspace check handles this: it automatically detects affected projects from push refs, runs tests for each, and skips dev_node projects. If changelog coverage fails, test-suite-workspace is skipped (it depends on prepush-changelog-coverage).

#Standalone usage

rlsbl check --tag prepush can be run outside of a git push context. Push-specific checks (prepush-changelog-coverage, prepush-gitignore-guard, prepush-manual-warning) skip gracefully when RLSBL_PUSH_STDIN is not set. test-suite always runs regardless of push context.

#Deprecated command

The old rlsbl pre-push-check command is deprecated. Update your hooks to the current version by running rlsbl scaffold, which installs the V5 hook template that calls rlsbl check --tag prepush instead.