Adopt cargo orthohelp release help#288
Open
lodyai[bot] wants to merge 22 commits into
Open
Conversation
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
|
This PR is a planning / pre-implementation change set to adopt cargo-orthohelp as Netsuke’s release-help generator. It adds a living ExecPlan and the configuration, scripts, tests and docs needed to support the migration while deferring actual release-help generation until explicit approval and coordination with pinned shared-actions. Key points
Status
WalkthroughMigrate release help generation from build.rs to a workflow-invoked script using cargo-orthohelp; restructure release-staging.toml and packaging hooks; refactor MiniJinja macro caching; add tests and documentation; update CI/workflow pins and Makefile tooling resolution. ChangesRelease help generation and packaging migration
Sequence Diagram(s)sequenceDiagram
participant ReleaseWorkflow as release.yml
participant BuildAndPackage as build-and-package.yml
participant GenerateHelpScript as scripts/generate-release-help.sh
participant CargoOrthohelp as cargo-orthohelp
participant StagingAction as stage-release-artefacts
ReleaseWorkflow->>BuildAndPackage: trigger with stage-target
BuildAndPackage->>GenerateHelpScript: run for selected target
GenerateHelpScript->>CargoOrthohelp: --format man / --format ps (+ --ps-module-name)
CargoOrthohelp->>StagingAction: write target/orthohelp/{target}/release artefacts
StagingAction->>BuildAndPackage: export man_path, powershell_help_dir
BuildAndPackage->>Packaging: pass staged paths to packaging steps
Possibly related PRs
Poem
Caution Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional.
❌ Failed checks (2 errors, 3 warnings)
✅ Passed checks (13 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
lodyai
Bot
force-pushed
the
cargo-orthohelp-adoption
branch
from
f669b09 to
99e3f3c
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Owner
|
@coderabbitai Please investigate the cause of the following issue using codegraph exploration and research, identify a fix and provide an AI coding agent prompt for the fix: |
lodyai
Bot
force-pushed
the
cargo-orthohelp-adoption
branch
from
7d79b22 to
4335334
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Owner
|
@coderabbitai Please investigate the cause of the following issue using codegraph exploration and research, identify a fix and provide an AI coding agent prompt for the fix: |
Owner
|
@coderabbitai Please investigate the cause of the following issue using codegraph exploration and research, identify a fix and provide an AI coding agent prompt for the fix: |
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
Owner
|
@coderabbitai will the clap_mangen flow still be supported after this change? If not, please ensure that the instructions give the option of using the clap_mangen flow where |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Owner
|
@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response. tests/workflow_build_and_package.rs Comment on lines +41 to +64 fn rust_build_release_step_blocks(contents: &str) -> Vec<String> {
let mut blocks = Vec::new();
let mut current_block = Vec::new();
for line in contents.lines() {
if line.starts_with(" - ") && !current_block.is_empty() {
let block = current_block.join("\n");
if block.contains("rust-build-release@") {
blocks.push(block);
}
current_block.clear();
}
current_block.push(line);
}
if !current_block.is_empty() {
let block = current_block.join("\n");
if block.contains("rust-build-release@") {
blocks.push(block);
}
}
blocks
}❌ New issue: Bumpy Road Ahead |
This comment was marked as resolved.
This comment was marked as resolved.
Owner
|
@coderabbitai are the cargo orthohelp generated manpage and MAML help correctly bundled in the Linux .deb/.rpm packages and Windows .msi respectively? |
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Owner
|
@coderabbitai re:
Is this something we should add to shared-actions? If so, please provide a detailed agent prompt for support of this for an agent working in the |
This comment was marked as resolved.
This comment was marked as resolved.
Expose `make typecheck` as a warning-denying `cargo check` wrapper across all targets and features. This gives the post-rebase validation set a stable Makefile target alongside `check-fmt`, `test`, and `lint`. Record the rebase result and validation-target decision in the cargo-orthohelp ExecPlan.
Update the orthohelp ExecPlan with the latest successful rebase onto `origin/main`, including the absence of conflicts and the new config precedence work now present on the branch. Remove the extra blank line in the users guide so the rebased branch passes Markdown linting.
Call `cargo-orthohelp` from the release-help script instead of using Cargo external subcommand dispatch, which injects an unsupported `orthohelp` positional argument. Update the release-help script tests to fake `cargo-orthohelp` directly and record the invocation decision in the orthohelp ExecPlan.
Use `render_captured` for manifest macro state retention so newer MiniJinja releases compile cleanly with warnings denied.
Keep manifest macro examples and safety notes aligned with `Template::render_captured`, which replaces the deprecated `eval_to_state` API in MiniJinja. Avoid an unfulfilled Clippy expectation on the macro state guard so the strict warning policy remains clean.
Pin Netsuke workflows to the shared-actions commit that adds `skip-man-page-discovery` and pass the opt-out to the `rust-build-release` call. Extend the build-and-package workflow test so every `rust-build-release` step must opt out of embedded man-page discovery while release help remains generated under `target/orthohelp`.
Pin every `leynos/shared-actions` workflow reference to `67025f53e79b821327d2f4d48a2af488cca42803` so CI, packaging, and release jobs use the same shared action revision.
Move the repeated rust-build-release step block flush logic into a small helper so the workflow contract test keeps the same behaviour with less nested conditional logic.
Add the release staging configuration consumed by the shared staging action so Linux and macOS targets publish the generated man page and Windows targets upload PowerShell help sidecars. Teach GoReleaser to gzip the orthohelp man page when a pre-staged copy is not already present, and extend workflow/staging contract tests for the generated help outputs.
Update shared-action pins to the revision that exposes `powershell_help_dir` from `stage-release-artefacts`. Wire Netsuke's Windows staging through `ps-module-name` and stage the PowerShell sidecar module at the module directory root so downstream steps can consume the new output without passing it into `windows-package`.
lodyai
Bot
force-pushed
the
cargo-orthohelp-adoption
branch
from
f79ef8f to
f513162
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Owner
|
@coderabbitai okay, leynos/shared-actions now has the requested change at SHA |
This comment was marked as resolved.
This comment was marked as resolved.
Update the reusable build-and-package workflow for the shared-actions release artefact staging contract at `e4c6b0e200a057edf927c45c298e7ddf229b3934`. Generate release help with the explicit `cargo-orthohelp` script path, pass staged artefact outputs through packaging, and keep every shared-actions workflow call on the same approved pin so the workflow pin contract remains coherent. Clean up Markdown lint defects in the release-help documentation so the required documentation gate passes with the workflow change.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f513162c16
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| set -euo pipefail | ||
| # Accept a pre-staged gzip (legacy) or produce one from the orthohelp output. | ||
| if [ ! -s dist/netsuke.1.gz ]; then | ||
| SRC="target/orthohelp/${GOOS}-${GOARCH}/release/man/man1/netsuke.1" |
There was a problem hiding this comment.
When dist/netsuke.1.gz is absent, this fallback looks under target/orthohelp/${GOOS}-${GOARCH}/..., but the release workflow and scripts/generate-release-help.sh write help files under Rust target-triple directories (for example target/orthohelp/x86_64-unknown-linux-gnu/release/...). In runs that rely on this fallback, GoReleaser will fail with a missing manpage error even though the man page was generated, because it is checking the wrong path shape.
Useful? React with 👍 / 👎.
Owner
There was a problem hiding this comment.
@coderabbitai Has this now been resolved in the latest commit?
Use codegraph analysis to determine your answer.
If this comment is now resolved, please mark it as such using the API. Otherwise, please provide an AI agent prompt for the remaining work to be done to address this comment.
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check the actual path format written by generate-release-help.sh
echo "=== scripts/generate-release-help.sh ==="
cat scripts/generate-release-help.sh
echo ""
echo "=== .goreleaser.yaml before hook ==="
head -25 .goreleaser.yaml
echo ""
echo "=== release.yml matrix target_key values ==="
grep -n "target_key\|stage-target\|GOOS\|GOARCH\|orthohelp" .github/workflows/release.yml
echo ""
echo "=== build-and-package.yml orthohelp paths ==="
grep -n "orthohelp\|target_key\|stage-target\|GOOS\|GOARCH" .github/workflows/build-and-package.yml
Length of output: 4520
@leynos — No, this has not been resolved in the latest commit.
Root cause confirmed: build-and-package.yml (line 98) writes orthohelp output to target/orthohelp/${{ inputs.target }}/release, where inputs.target is the full Rust target triple (e.g. x86_64-unknown-linux-gnu). The GoReleaser hook, however, constructs the fallback path as target/orthohelp/${GOOS}-${GOARCH}/release/..., where GoReleaser expands those variables to its own format (e.g. linux/amd64), yielding target/orthohelp/linux-amd64/release/.... The two path shapes are irreconcilable without an explicit mapping.
AI agent prompt:
Fix the GoReleaser before-hook fallback path in `.goreleaser.yaml` to use the Rust
target-triple directory layout that `scripts/generate-release-help.sh` actually
writes to, rather than the `${GOOS}-${GOARCH}` format that GoReleaser interpolates.
## Problem
The current hook constructs:
SRC="target/orthohelp/${GOOS}-${GOARCH}/release/man/man1/netsuke.1"
GoReleaser expands `${GOOS}` and `${GOARCH}` as its own OS/arch tokens (e.g.
`linux`/`amd64`), producing `target/orthohelp/linux-amd64/release/...`.
`scripts/generate-release-help.sh` writes to the path supplied via `--out-dir`,
which `.github/workflows/build-and-package.yml` sets to:
target/orthohelp/${{ inputs.target }}/release
where `inputs.target` is the full Rust target triple, e.g.
`x86_64-unknown-linux-gnu`.
These two path shapes are incompatible; the fallback will always fail.
## Required change
Replace the single `SRC=` assignment with an explicit GOOS/GOARCH → Rust target
triple lookup table covering every target in the GoReleaser matrix (see the
`goos`/`goarch` and `ignore` stanzas in `.goreleaser.yaml`):
| GOOS | GOARCH | Rust triple |
|---------|--------|--------------------------------|
| linux | amd64 | x86_64-unknown-linux-gnu |
| linux | arm64 | aarch64-unknown-linux-gnu |
| darwin | amd64 | x86_64-apple-darwin |
| darwin | arm64 | aarch64-apple-darwin |
| freebsd | amd64 | x86_64-unknown-freebsd |
The `freebsd`/`arm64` combination is already excluded by the `ignore` stanza, so
no entry is needed for it.
Apply a diff similar to the following to `.goreleaser.yaml`:
```diff
- SRC="target/orthohelp/${GOOS}-${GOARCH}/release/man/man1/netsuke.1"
+ case "${GOOS}-${GOARCH}" in
+ linux-amd64) RUST_TARGET="x86_64-unknown-linux-gnu" ;;
+ linux-arm64) RUST_TARGET="aarch64-unknown-linux-gnu" ;;
+ darwin-amd64) RUST_TARGET="x86_64-apple-darwin" ;;
+ darwin-arm64) RUST_TARGET="aarch64-apple-darwin" ;;
+ freebsd-amd64) RUST_TARGET="x86_64-unknown-freebsd" ;;
+ *)
+ echo "::error title=Manpage missing::No Rust target triple known for ${GOOS}-${GOARCH}."
+ exit 1
+ ;;
+ esac
+ SRC="target/orthohelp/${RUST_TARGET}/release/man/man1/netsuke.1"
```
## Tests to update / add
1. **`tests/workflow_build_and_package.rs`** — add (or extend) an assertion that
the `.goreleaser.yaml` before hook does **not** reference the raw
`${GOOS}-${GOARCH}` pattern in an `orthohelp` path, and does contain at least
one of the expected Rust target triples (e.g. `x86_64-unknown-linux-gnu`).
2. **`tests/release_help_script_tests.rs`** — no changes needed; that suite tests
the shell script, not the GoReleaser hook.
## Validation
After applying the change:
```bash
grep -E '\$\{GOOS\}-\$\{GOARCH\}' .goreleaser.yaml
# Must produce no output (the raw pattern must be gone from orthohelp paths).
grep 'x86_64-unknown-linux-gnu' .goreleaser.yaml
# Must match the lookup table entry.
cargo test --test workflow_build_and_package
```
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.github/workflows/release.yml (1)
116-139:⚠️ Potential issue | 🟠 Major | ⚡ Quick winDeclare explicit least-privilege permissions for reusable build jobs.
Set explicit
permissionsfor this caller job instead of inheriting defaults. Line 116 currently leaves token scopes implicit, which triggers the excessive-permissions warning and broadens risk unnecessarily.🔧 Proposed fix
build-linux: needs: metadata + permissions: + contents: read strategy: matrix: include:Apply the same pattern to
build-windowsandbuild-macosin this workflow.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/release.yml around lines 116 - 139, Add an explicit minimal permissions block to the build-linux job (named build-linux) instead of inheriting defaults: declare only the GitHub token scopes the reusable workflow needs (for example contents: read, packages: write, id-token: write and actions: read) and remove implicit broad scopes; add the same permissions block to the other build jobs (build-windows and build-macos) that call uses: ./.github/workflows/build-and-package.yml so the reusable workflow runs with least privilege.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.goreleaser.yaml:
- Around line 11-18: The current .goreleaser.yaml uses the literal
${GOOS}-${GOARCH} to build SRC which doesn't match the Rust-generated help
directories; update the SRC resolution to map GOOS/GOARCH tuples to the
corresponding Rust target triples produced by scripts/generate-release-help.sh
(e.g., map linux-amd64 -> x86_64-unknown-linux-gnu, linux-arm64 ->
aarch64-unknown-linux-gnu, darwin-amd64 -> x86_64-apple-darwin, darwin-arm64 ->
aarch64-apple-darwin, etc.), and then use that mapped TRIPLE variable when
constructing SRC; keep a fallback that checks both the mapped path and the
original dist/netsuke.1.gz so the script still fails cleanly if neither is
found.
In `@docs/developers-guide.md`:
- Around line 29-31: Update the documentation line that currently references the
tool as `cargo orthohelp` to the correct binary name `cargo-orthohelp`; edit the
text near the header "Release help tooling" (the sentence "Release builds
generate help artefacts explicitly with `cargo orthohelp`,") so it reads
`cargo-orthohelp` to match the PR objectives/execplan and avoid invoking Cargo
subcommand dispatch.
In `@docs/netsuke-cli-design-document.md`:
- Around line 298-300: The CLI help text contains a malformed URL punctuation
sequence "<https://netsuke.dev/docs">) — fix the punctuation in that string by
moving the closing double-quote after the closing angle bracket so it reads
"<https://netsuke.dev/docs>") (or remove the unnecessary quotes if the help text
format prefers bare angle-bracketed links); update the string in the
docs/netsuke-cli-design-document.md occurrence where the CLI help example is
defined to ensure the angle-bracketed URL and surrounding punctuation are
correctly ordered.
- Around line 290-292: Replace the incorrect tool name "cargo orthohelp" with
the correct binary name "cargo-orthohelp" wherever it appears (e.g., the
sentence that currently mentions `cargo orthohelp`), ensuring the documentation
string matches the developers' guide and execplan; search for other occurrences
of the tool name in the same doc and update them for consistency.
In `@docs/netsuke-design.md`:
- Around line 402-418: Remove the duplicated "### 2.7 Table: Netsuke Manifest
vs. Makefile" header and its subsequent Markdown table block (the entire
duplicate showing Makefile vs. Netsukefile examples including the
Variables/Macros/Rule Definition/Target Build/Readability rows), leaving only
the original table that appears later after section 2.6; ensure the duplicate
block beginning with that exact header is deleted so section numbering flows
correctly.
---
Outside diff comments:
In @.github/workflows/release.yml:
- Around line 116-139: Add an explicit minimal permissions block to the
build-linux job (named build-linux) instead of inheriting defaults: declare only
the GitHub token scopes the reusable workflow needs (for example contents: read,
packages: write, id-token: write and actions: read) and remove implicit broad
scopes; add the same permissions block to the other build jobs (build-windows
and build-macos) that call uses: ./.github/workflows/build-and-package.yml so
the reusable workflow runs with least privilege.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 8d3e1b44-d588-48cf-915d-7019fc6a6de9
⛔ Files ignored due to path filters (1)
Cargo.lockis excluded by!**/*.lock
📒 Files selected for processing (27)
.github/release-staging.toml.github/workflows/build-and-package.yml.github/workflows/ci.yml.github/workflows/netsukefile-test.yml.github/workflows/release.yml.goreleaser.yamlCargo.tomlMakefileREADME.mdbuild.rsdocs/developers-guide.mddocs/execplans/cargo-orthohelp-adoption.mddocs/netsuke-cli-design-document.mddocs/netsuke-design.mddocs/users-guide.mdscripts/generate-release-help.shscripts/package-artifact.shsrc/manifest/jinja_macros/cache.rssrc/manifest/jinja_macros/mod.rssrc/manifest/tests/macros.rstests/bdd/steps/mod.rstests/bdd/steps/release_help_generation.rstests/features/release_help_generation.featuretests/release_help_script_tests.rstests/release_staging_tests.rstests/workflow_build_and_package.rstests/workflow_release.rs
Map GoReleaser `GOOS` and `GOARCH` values to the Rust target triples used by `scripts/generate-release-help.sh` before looking up generated manual pages. This keeps the fallback path aligned with the release workflow output when `dist/netsuke.1.gz` has not already been staged.
Owner
|
@coderabbitai re:
Is this something we should raise as an issue against ortho-config? If so, please draft an issue ticket and I will pass it onto the maintainer (me. lol) |
Contributor
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chainYes, this is worth raising as an upstream issue. The netsuke workaround (invoking
Let me find the right repository and file it. 🏁 Script executed: Length of output: 85 🏁 Script executed: Length of output: 77 🏁 Script executed: Length of output: 798
The issue documents:
|
Fix remaining release-help documentation references so they use the cargo-orthohelp binary name and correct the CLI docs URL punctuation. Add explicit least-privilege permissions to reusable release build jobs.
Update the remaining user-facing documentation to refer to `cargo-orthohelp` consistently. The previously reported malformed URL and duplicate-table issues are not present in the current sources, so no further markdown edits were necessary.
Avoid the deprecated Cargo subcommand spelling in the adoption plan while preserving the note about why release automation calls cargo-orthohelp directly.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/release-staging.toml:
- Around line 35-36: Replace hardcoded target triples in manpage source paths
with the {target} placeholder: change occurrences of source =
"target/orthohelp/aarch64-unknown-linux-gnu/release/man/man1/{bin_name}.1",
source = "target/orthohelp/x86_64-apple-darwin/release/man/man1/{bin_name}.1",
and source =
"target/orthohelp/aarch64-apple-darwin/release/man/man1/{bin_name}.1" to source
= "target/orthohelp/{target}/release/man/man1/{bin_name}.1" so all
target-specific manpage sources use the {target} template and stay consistent
with the targets table.
In @.goreleaser.yaml:
- Around line 11-22: The hook uses unset shell variables GOOS and GOARCH
(referenced in the case statement and used to set RUST_TARGET and SRC) which
will fail under set -u when run in the global before.hooks context; either
declare GOOS and GOARCH explicitly in the global env: section of
.goreleaser.yaml so they are always defined, or move this case-to-RUST_TARGET
mapping into the per-build hook (builds[].hooks.pre) where GoReleaser provides
GOOS/GOARCH, ensuring RUST_TARGET and SRC are computed only in that per-build
context.
In `@docs/ortho-config-users-guide.md`:
- Around line 995-996: The sentence "When multiple sources fail, the errors are
collected into the `Aggregate` variant so callers can inspect each individual
failure." is missing a comma before "so"; edit the docs text (the sentence
containing the `Aggregate` variant) to insert a comma before "so" so it reads
"...`Aggregate` variant, so callers can inspect each individual failure." to
conform to en-GB-oxendict grammar.
In `@README.md`:
- Around line 52-53: The sentence in the README contains a hard-coded year
("This is 2025.") which will become stale; replace that fragment with
year-agnostic wording (e.g., change "This is 2025." to "This is the modern era."
or "This is the present day.") so the promotional line (the sentence containing
"Yes, it’s just YAML. ... You deserve better.") remains evergreen.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: cdd375ef-3176-492d-ae58-a22356d6f8d5
📒 Files selected for processing (13)
.github/release-staging.toml.github/workflows/build-and-package.yml.github/workflows/ci.yml.github/workflows/netsukefile-test.yml.github/workflows/release.yml.goreleaser.yamlREADME.mddocs/developers-guide.mddocs/execplans/cargo-orthohelp-adoption.mddocs/netsuke-cli-design-document.mddocs/netsuke-design.mddocs/ortho-config-users-guide.mdtests/release_staging_tests.rs
Comment on lines
+35
to
+36
| source = "target/orthohelp/aarch64-unknown-linux-gnu/release/man/man1/{bin_name}.1" | ||
| destination = "man/man1/{bin_name}.1" |
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial | ⚡ Quick win
Use {target} placeholders for all target-specific manpage sources.
Eliminate hardcoded target triples in source paths. Keep path templating consistent with the target table to prevent drift during future target renames.
Patch
- source = "target/orthohelp/aarch64-unknown-linux-gnu/release/man/man1/{bin_name}.1"
+ source = "target/orthohelp/{target}/release/man/man1/{bin_name}.1"
@@
- source = "target/orthohelp/x86_64-apple-darwin/release/man/man1/{bin_name}.1"
+ source = "target/orthohelp/{target}/release/man/man1/{bin_name}.1"
@@
- source = "target/orthohelp/aarch64-apple-darwin/release/man/man1/{bin_name}.1"
+ source = "target/orthohelp/{target}/release/man/man1/{bin_name}.1"Also applies to: 98-99, 109-110
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/release-staging.toml around lines 35 - 36, Replace hardcoded target
triples in manpage source paths with the {target} placeholder: change
occurrences of source =
"target/orthohelp/aarch64-unknown-linux-gnu/release/man/man1/{bin_name}.1",
source = "target/orthohelp/x86_64-apple-darwin/release/man/man1/{bin_name}.1",
and source =
"target/orthohelp/aarch64-apple-darwin/release/man/man1/{bin_name}.1" to source
= "target/orthohelp/{target}/release/man/man1/{bin_name}.1" so all
target-specific manpage sources use the {target} template and stay consistent
with the targets table.
Comment on lines
+11
to
+22
| case "${GOOS}/${GOARCH}" in | ||
| linux/amd64) RUST_TARGET="x86_64-unknown-linux-gnu" ;; | ||
| linux/arm64) RUST_TARGET="aarch64-unknown-linux-gnu" ;; | ||
| darwin/amd64) RUST_TARGET="x86_64-apple-darwin" ;; | ||
| darwin/arm64) RUST_TARGET="aarch64-apple-darwin" ;; | ||
| freebsd/amd64) RUST_TARGET="x86_64-unknown-freebsd" ;; | ||
| *) | ||
| echo "::error title=Unsupported manpage target::No Rust target mapping for ${GOOS}/${GOARCH}." | ||
| exit 1 | ||
| ;; | ||
| esac | ||
| SRC="target/orthohelp/${RUST_TARGET}/release/man/man1/netsuke.1" |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🔍 Additional research query:
`Search for GoReleaser documentation on before.hooks execution context, specifically regarding:
- What environment variables are available in before.hooks
- Whether GOOS and GOARCH are guaranteed to be set
- What shell options (like set -u) are applied to the hook execution
- Whether these variables are set by GoReleaser automatically or need to be defined by the user
Source: Context7 for GoReleaser library documentation`
💡 Result:
Let me search for more specific documentation about before.hooks environment variables and runtime variables.Let me search for more specific information about GoReleaser's Runtime variables and build hook environment details.Based on my search results, I now have comprehensive information about GoReleaser's before.hooks execution context. Let me provide a detailed answer to your questions.
GoReleaser before.hooks Execution Context Documentation
1. Environment Variables Available in before.hooks
Global environment variables are passed down to all hooks and builds. before.hooks can access environment variables through template syntax like {{ .Env.FILE_TO_TOUCH }} and you can specify extra environment variables at the hook level using an env configuration section.
Template variables are available in hooks, including runtime GOOS and GOARCH accessible using {{ .Runtime.Goos }} and {{ .Runtime.Goarch }}.
2. GOOS and GOARCH Guarantee
For global before.hooks specifically, GOOS and GOARCH are NOT directly set as environment variables because global before hooks execute before any platform-specific build context is established. The Runtime.Goos variable is available in template conditionals like if: '{{ eq .Runtime.Goos "windows" }}', but this refers to the runtime/machine GOOS, not build targets.
For build-specific hooks (pre and post build hooks), there was a feature request to make .Os and .Arch template variables available or to actually set GOOS and GOARCH in the hook execution environments, but this applies to build hooks, not global before hooks.
3. Shell Options (like set -u)
The documentation does not explicitly specify what shell options are applied to before.hook execution. If you need to do anything more complex, it is recommended to create a shell script and call it instead of relying on inline shell commands.
4. Variable Assignment
Environment variables are set through the global env section in your .goreleaser.yaml config and are passed down to all hooks and builds, with both global environment variables and hook-level environment variables available. These are defined by the user in the configuration file, not automatically set by GoReleaser for before.hooks execution.
Important Note
Build-specific environment variables (from the builds.env section) are not available in before hooks, as before hooks execute before any build blocks are evaluated.
[::web_search::]
🌐 Web query:
GoReleaser before.hooks execution context GOOS GOARCH environment variables documentation
💡 Result:
GoReleaser “before” hooks execution context: there are two relevant “before” concepts in GoReleaser docs. 1) Global before hooks (configuration before: hooks:) - before.hooks run “before the release is started”; if any hook fails the release process is aborted. [1] - Global environment variables from the top-level env: are passed down to “all hooks and builds”, including your before hooks. [2] 2) Per-build before hooks (configuration builds[].hooks.pre:) - builds[].hooks.pre (and post) are run “for each build target” (i.e., for each OS/arch combination in a matrix). [3] - Hooks can have env: and dir:; hook env supports templates. [3] - GoReleaser exposes build details to both pre and post hooks, including .Target (example format like darwin_amd64). [3] - Environment variable inheritance/override order for hooks: global (env) -> build (builds[].env) -> hook (builds[].hooks.pre[].env / builds[].hooks.post[].env). [3] GOOS/GOARCH environment variables in that context (what’s documented) - In the sources retrieved here, the hook documentation clearly describes what’s available to hooks (template variables / build details like .Target) and how hook env inheritance works, but it does not explicitly document whether GoReleaser exports standard GOOS and GOARCH environment variables into the hook process. - What we can say with evidence: GoReleaser builds for configured goos: and goarch: combinations (and generates a matrix when multiple values are provided). [4] Best-supported answer for your question (“use GOOS/GOARCH in before.hooks”) - Don’t rely on undeclared GOOS/GOARCH being present in hook environment variables unless you verify in your environment. - Instead, use .Target (available to pre hooks) to determine which OS/arch combination the hook corresponds to. [3] - If you need explicit env vars, set them using GoReleaser’s documented env: mechanism (global env: for all hooks/builds, or builds[].env / builds[].hooks.pre[].env for narrower scope). [2][3] If you want, tell me whether you mean the global before.hooks block or builds[].hooks.pre; I can then do a second targeted search for the exact wording around GOOS/GOARCH being injected into hook commands (and cite the line if it exists).
Citations:
- 1: https://goreleaser.com/customization/general/hooks/
- 2: https://goreleaser.com/customization/general/env/
- 3: https://goreleaser.com/customization/builds/hooks
- 4: https://goreleaser.com/customization/builds/builders/go/
Define GOOS and GOARCH explicitly or move this logic to per-build hooks.
This code executes in a global before.hooks context where GOOS and GOARCH are not set as environment variables by GoReleaser. Under set -u, the hook will fail with an unset variable error. Either define these variables in the global env: section of .goreleaser.yaml, or move this target-mapping logic to per-build hooks (builds[].hooks.pre) where build context is available.
Are you using this in a global before.hooks context, or in per-build hooks (builds[].hooks.pre)? If the former, the issue is confirmed. If the latter, the fix differs.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.goreleaser.yaml around lines 11 - 22, The hook uses unset shell variables
GOOS and GOARCH (referenced in the case statement and used to set RUST_TARGET
and SRC) which will fail under set -u when run in the global before.hooks
context; either declare GOOS and GOARCH explicitly in the global env: section of
.goreleaser.yaml so they are always defined, or move this case-to-RUST_TARGET
mapping into the per-build hook (builds[].hooks.pre) where GoReleaser provides
GOOS/GOARCH, ensuring RUST_TARGET and SRC are computed only in that per-build
context.
Comment on lines
+995
to
+996
| combined data is invalid. When multiple sources fail, the errors are collected | ||
| into the `Aggregate` variant so callers can inspect each individual failure. |
Contributor
There was a problem hiding this comment.
Insert the missing comma in the compound sentence.
Add a comma before “so” at Line 996 to keep the sentence grammatically correct
and easier to scan.
Triage: [type:grammar] [type:docstyle]
As per coding guidelines, "Documentation must use en-GB-oxendict spelling and
grammar."
🧰 Tools
🪛 LanguageTool
[uncategorized] ~996-~996: Use a comma before ‘so’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...e collected into the Aggregate variant so callers can inspect each individual fai...
(COMMA_COMPOUND_SENTENCE_2)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/ortho-config-users-guide.md` around lines 995 - 996, The sentence "When
multiple sources fail, the errors are collected into the `Aggregate` variant so
callers can inspect each individual failure." is missing a comma before "so";
edit the docs text (the sentence containing the `Aggregate` variant) to insert a
comma before "so" so it reads "...`Aggregate` variant, so callers can inspect
each individual failure." to conform to en-GB-oxendict grammar.
Comment on lines
+52
to
+53
| Yes, it’s just YAML. Yes, that’s a Jinja `foreach`. No, you don’t need to define | ||
| `.PHONY` or remember what `$@` means. This is 2025. You deserve better. |
Contributor
There was a problem hiding this comment.
Remove the hard-coded year in the promotional sentence.
Replace “This is 2025.” with year-agnostic wording to prevent immediate
staleness and avoid avoidable drift in user-facing copy.
Triage: [type:docstyle]
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 52 - 53, The sentence in the README contains a
hard-coded year ("This is 2025.") which will become stale; replace that fragment
with year-agnostic wording (e.g., change "This is 2025." to "This is the modern
era." or "This is the present day.") so the promotional line (the sentence
containing "Yes, it’s just YAML. ... You deserve better.") remains evergreen.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This branch carries the pre-implementation plan for adopting
cargo orthohelpas Netsuke's release help generator. It documents how the release workflow should replaceclap_mangenand the currentbuild.rsman-page output with explicit generation of Unix manual pages and Windows PowerShell MAML help.Execplan: docs/execplans/cargo-orthohelp-adoption.md
This branch also updates Makefile so
make markdownlintcan resolve the Bun-installedmarkdownlint-cli2in sparse hook environments where~/.bun/binis not onPATH.This is a pre-implementation planning PR. It does not authorize implementation until the execplan is approved.
Review walkthrough
MDLINTfallback keeps the existing override behaviour while fixing hook environments with a sparsePATH.Validation
make check-fmt: passed.make lint: passed.make test: passed.make markdownlint: passed.PATH=/usr/bin:/bin make markdownlint: passed.mbake validate Makefile: passed.Notes
No roadmap task or issue reference was found in the branch context. The execplan records that implementation must wait for explicit approval.