docs: Add ADR-0032 documenting guard workflow architecture pattern#307
docs: Add ADR-0032 documenting guard workflow architecture pattern#307EffortlessSteven wants to merge 2 commits intomainfrom
Conversation
- Decision: Maintain Rust-Template (workflow + Rego) and guard repos (Rust CLI) as complementary patterns - Rust-Template: GitHub-native orchestration, governance policies, advisory enforcement - Guard repos (depguard, diffguard, covguard): Portable analysis tools with structured output - Future: Rust-Template workflows will invoke guard CLIs for enforcement - Rationale: Guard repos are agentic-friendly (schema receipts), portable (any CI), publishable to crates.io
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (2)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
- Add ADR-0032 to status section - Add recent ADRs table with ADR-0032 at top
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request adds Architectural Decision Record (ADR) 0032 to the documentation, detailing the architectural approach for implementing guard workflows in the Rust-Template project. It formalizes the decision to use two distinct patterns for guard implementations, and outlines the rationale, consequences, and compliance measures associated with this decision. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces ADR-0032, which documents the architectural decision to maintain two complementary patterns for 'guard' workflows. The ADR is well-structured and clearly articulates the context, decision, and consequences. My review focuses on improving the consistency and accuracy of the code examples within the document to better align with its stated goals of reproducibility and clarity. Specifically, I've suggested changes to the cargo install examples to include version pinning and to ensure consistency across different examples.
| - name: Run depguard check | ||
| if: steps.scope.outputs.declared_type == 'mechanical' | ||
| run: | | ||
| cargo install depguard-cli |
There was a problem hiding this comment.
The 'Migration Path (Future)' section (line 196) and 'Future Work' section in the PR description both mention pinning CLI versions for reproducibility. To align this example with that goal, it would be clearer to demonstrate version pinning here. cargo install uses the --version flag for this. This also helps mitigate the 'Version drift' risk mentioned under 'Consequences'.
| cargo install depguard-cli | |
| cargo install depguard-cli --version 0.3.0 |
| - name: Run diffguard check | ||
| if: steps.scope.outputs.declared_type == 'behavior' | ||
| run: | | ||
| diffguard check --preset strict --output diffguard.json |
There was a problem hiding this comment.
This diffguard example appears to assume the CLI is already installed, which is inconsistent with the depguard example above that includes a cargo install step. For consistency and clarity, I suggest adding an installation step for diffguard as well. Pinning the version would also align with the reproducibility goals mentioned in this ADR.
| diffguard check --preset strict --output diffguard.json | |
| cargo install diffguard-cli --version 0.5.1 | |
| diffguard check --preset strict --output diffguard.json |
|
|
||
| If Rust-Template workflows adopt guard CLIs: | ||
|
|
||
| 1. Pin guard CLI versions in workflows (e.g., `depguard-cli@0.3.0`) |
There was a problem hiding this comment.
The example syntax depguard-cli@0.3.0 is typically used by package managers like npm or yarn. For cargo install, the flag for specifying a version is --version. Using the correct syntax in the example will avoid confusion for developers.
| 1. Pin guard CLI versions in workflows (e.g., `depguard-cli@0.3.0`) | |
| 1. Pin guard CLI versions in workflows (e.g., `cargo install depguard-cli --version 0.3.0`) |
1 participant
Summary
This PR adds ADR-0032 documenting the architectural decision about guard workflow patterns in Rust-Template.
Key Decision
Maintain two complementary guard implementation patterns:
Rust-Template: GitHub Actions workflows + Rego policies (policy-as-code)
ci-scope-guard.yml,policy/scope.regoGuard Repos (depguard, diffguard, covguard): Multi-crate Rust workspaces
Rationale
Future Work
References
EffortlessMetrics/depguard,diffguard,covguard