Slipstream/auto_review
1
0
Fork 0
Code Issues 2 Pull requests Projects Releases 27 Packages Activity Actions

docs: document single-binary rollout #133

Merged
jwilger merged 3 commits from issue-120-single-binary-docs-tests into main 2026-05-07 11:51:55 -07:00
Conversation 3 Commits 3 Files changed 9 +81 -24
jwilger commented 2026-05-07 11:04:41 -07:00
Owner
Copy link

Summary

  • Update operator, systemd, quickstart, threat-model, and release announcement docs for container-first production deployment, embedded OCI default startup, and explicit bare opt-out language.
  • Clarify direct binary/systemd use as a custom VM/container-image path, document existing Nix flake package/image outputs, and track first-class NixOS support in #135.
  • Remove the docs wording contract test, tighten TDD guidance against deterministic docs-only wording tests, and track repository-wide cleanup in #134.
  • Clarify binary release assets/provenance as future #121 scope without claiming they are already published.

Verification

  • nix develop -c cargo nextest run -p ar-gateway --no-tests=pass
  • nix develop -c cargo fmt --all -- --check
  • git diff --check

Closes #120

## Summary - Update operator, systemd, quickstart, threat-model, and release announcement docs for container-first production deployment, embedded OCI default startup, and explicit bare opt-out language. - Clarify direct binary/systemd use as a custom VM/container-image path, document existing Nix flake package/image outputs, and track first-class NixOS support in #135. - Remove the docs wording contract test, tighten TDD guidance against deterministic docs-only wording tests, and track repository-wide cleanup in #134. - Clarify binary release assets/provenance as future #121 scope without claiming they are already published. ## Verification - nix develop -c cargo nextest run -p ar-gateway --no-tests=pass - nix develop -c cargo fmt --all -- --check - git diff --check Closes #120
docs: document single-binary rollout
Some checks failed
CI / Nix flake check (pull_request) Failing after 1m32s
Details
CI / auto_review semantic review (pull_request) Has been skipped
Details
68376772ea
fix(ci): include rollout docs in Nix source
All checks were successful
CI / Nix flake check (pull_request) Successful in 3m23s
Details
CI / auto_review semantic review (pull_request) Successful in 1s
Details
auto_review auto_review: no findings
88f0c0dac2
auto-review approved these changes 2026-05-07 11:15:47 -07:00
Dismissed
auto-review left a comment
Copy link

The PR introduces documentation updates and a new test to ensure the single-binary OCI rollout is accurately described. The changes appear safe to merge, with minor notes on improving clarity and error diagnostics.

The PR introduces documentation updates and a new test to ensure the single-binary OCI rollout is accurately described. The changes appear safe to merge, with minor notes on improving clarity and error diagnostics.
jwilger reviewed 2026-05-07 11:33:40 -07:00
crates/ar-gateway/tests/single_binary_rollout_docs_contract.rs Outdated
@ -0,0 +1,130 @@
const OPERATIONS: &str = include_str!("../../../docs/OPERATIONS.md");
jwilger commented 2026-05-07 11:28:09 -07:00
Author
Owner
Copy link

These kinds of tests with deterministic checks for language in documentation are completely worthless. Remove this and create a follow-up issue to remove all such tests from the repository and add the necessary guardrails and review guidance to prevent this in the future. We write tests to cover production code and sometimes to cover developer utility scripts if they are essential to have correct. Otherwise...use better judgement.

These kinds of tests with deterministic checks for language in documentation are completely worthless. Remove this and create a follow-up issue to remove *all* such tests from the repository and add the necessary guardrails and review guidance to prevent this in the future. We write tests to cover production code and sometimes to cover developer utility scripts if they are essential to have correct. Otherwise...use better judgement.
jwilger commented 2026-05-07 11:45:23 -07:00
Author
Owner
Copy link

Reflection: I treated documentation wording as something that needed deterministic test pressure instead of recognizing this was docs-only prose that should be reviewed directly. Classification: guardrail-gap; the existing TDD guidance exempted docs-only work but did not explicitly forbid docs wording tests.

Remediation: removed single_binary_rollout_docs_contract.rs, removed its now-unneeded flake source inclusions, tightened the TDD guidance to say docs-only wording should not get deterministic tests, and opened follow-up #134 to inventory/remove any remaining docs wording tests.

Reflection: I treated documentation wording as something that needed deterministic test pressure instead of recognizing this was docs-only prose that should be reviewed directly. Classification: guardrail-gap; the existing TDD guidance exempted docs-only work but did not explicitly forbid docs wording tests. Remediation: removed `single_binary_rollout_docs_contract.rs`, removed its now-unneeded flake source inclusions, tightened the TDD guidance to say docs-only wording should not get deterministic tests, and opened follow-up #134 to inventory/remove any remaining docs wording tests.
jwilger marked this conversation as resolved
deploy/systemd/README.md Outdated
@ -5,12 +5,19 @@ For self-hosters who run the gateway directly on a Linux host
[`docker-compose.yml`](../docker-compose.yml) as the third
deploy option.
The Docker/OCI image is still the recommended production deployment because it
jwilger commented 2026-05-07 11:29:53 -07:00
Author
Owner
Copy link

For both this and the bare command without systemd, it would be worth noting that the reason these are provided is for people who want to build the program into their own, custom container images or VMs.

Also, we should provide capability and instructions for using this program in Nix/NixOS via our flake.nix if we don't already. It should support deploying containerized, deploying via systemd, or just installing the program.

For both this and the bare command without systemd, it would be worth noting that the *reason* these are provided is for people who want to build the program into their own, custom container images or VMs. Also, we should provide capability and instructions for using this program in Nix/NixOS via our flake.nix if we don't already. It should support deploying containerized, deploying via systemd, or just installing the program.
jwilger commented 2026-05-07 11:45:23 -07:00
Author
Owner
Copy link

Reflection: I documented bare/systemd mechanics without explaining the intended operator use case for those paths, and I did not separate existing flake capabilities from missing NixOS deployment support. Classification: one-off for the wording gap; the NixOS module support is new scope tracked separately.

Remediation: clarified that bare/systemd direct-binary paths exist for operators building custom VM/container images, added the same context to the bare quickstart path, documented the existing flake package/image outputs, and opened follow-up #135 for first-class NixOS module/deployment support.

Reflection: I documented bare/systemd mechanics without explaining the intended operator use case for those paths, and I did not separate existing flake capabilities from missing NixOS deployment support. Classification: one-off for the wording gap; the NixOS module support is new scope tracked separately. Remediation: clarified that bare/systemd direct-binary paths exist for operators building custom VM/container images, added the same context to the bare quickstart path, documented the existing flake package/image outputs, and opened follow-up #135 for first-class NixOS module/deployment support.
jwilger marked this conversation as resolved
docs: address rollout review feedback
All checks were successful
CI / Nix flake check (pull_request) Successful in 3m20s
Details
CI / auto_review semantic review (pull_request) Successful in 2s
Details
auto_review auto_review: no findings
Publish release / release-publish (pull_request) Has been skipped
Details
d87378d6f2
jwilger dismissed auto-review's review 2026-05-07 11:47:14 -07:00
Reason:

New commits pushed, approval review dismissed automatically according to repository settings

auto-review approved these changes 2026-05-07 11:51:35 -07:00
auto-review left a comment
Copy link

This PR updates documentation to clarify deployment options and testing guidance, particularly around the use of deterministic tests for documentation wording. The changes align with the project's focus on container-first deployment and human review for docs-only changes.

Walkthrough

Δ since 88f0c0d:

  • Documentation Updates:
    • Clarified the use of bare mode for local evaluation and custom VM/container images in QUICKSTART.md and OPERATIONS.md.
    • Updated systemd/README.md to specify its use for custom deployments.
    • Removed deterministic tests for documentation wording, aligning with new TDD guidance.
  • Nix Flake:
    • Documented the Nix flake outputs for building binaries and OCI images, aiding Nix users in deployment.
This PR updates documentation to clarify deployment options and testing guidance, particularly around the use of deterministic tests for documentation wording. The changes align with the project's focus on container-first deployment and human review for docs-only changes. ## Walkthrough ### Δ since 88f0c0d: - **Documentation Updates**: - Clarified the use of bare mode for local evaluation and custom VM/container images in `QUICKSTART.md` and `OPERATIONS.md`. - Updated `systemd/README.md` to specify its use for custom deployments. - Removed deterministic tests for documentation wording, aligning with new TDD guidance. - **Nix Flake**: - Documented the Nix flake outputs for building binaries and OCI images, aiding Nix users in deployment.
Sign in to join this conversation.
Reviewers
No reviewers
auto-review
Labels
Clear labels   
bug

   
discussion

   
enhancement
  
bug
Something is not working

  
duplicate
This issue or pull request already exists

  
enhancement
New feature

  
help wanted
Need some help

  
invalid
Something is wrong

  
question
More information is needed

  
wontfix
This won't be fixed

No labels
bug
discussion
enhancement
bug
duplicate
enhancement
help wanted
invalid
question
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Slipstream/auto_review!133
No description provided.