Skip to content

docs(#3508): add hack/ directory conventions to AGENTS.md #3509

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fullsend-ai-coder wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(#3508): add hack/ directory conventions to AGENTS.md #3509

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,35 @@ Tests use build tags with different timeouts:
compatibility (e.g., `quay.io/enterprise-contract/ec-cli`, Tekton parameter names) must be
preserved as-is.

## hack/ Directory Conventions

Scripts in `hack/` are **attended developer utilities** intended for the development team, not
production runtime code. They automate tasks like dependency bumps, release branch management,
environment setup, and demo workflows. Developers run them interactively at a terminal.

**Target environment:** RHEL 8+ / Fedora workstations (Bash 4.4+ guaranteed). Backward
compatibility with older Bash versions (e.g., Bash 3.x on macOS default shell) is explicitly
not required.

**Accepted trade-offs for attended usage:**

- Unescaped dots in sed/grep patterns operating on controlled, predictable inputs
- Hardcoded branch lists that change infrequently and are updated manually
- `git add -A` or broad staging when the script controls the entire working tree context

@fullsend-ai-review fullsend-ai-review Bot Aug 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[low] technical accuracy

The bullet 'Reliance on modern Bash features (associative arrays, readarray, ${var,,}, etc.)' lists readarray and ${var,,} as examples of features relied upon, but no hack/ script currently uses them — only declare -A (associative arrays) is used in go-mod-upgrade-prs.sh. The wording implies current usage that does not exist.

Suggested fix: Reword to clarify these are permitted features rather than currently-used ones (e.g., 'Reliance on modern Bash features (associative arrays, readarray, ${var,,}, etc.) is permitted').

- Reliance on modern Bash features (associative arrays, `readarray`, `${var,,}`, etc.)

**Reviewer guidance:** Robustness and portability findings at Low severity should be suppressed
for `hack/` scripts unless they affect correctness in the target environment (RHEL 8+ / Fedora).
Focus review on:

- **Logic errors** that produce wrong results
- **Data loss risks** (e.g., unsafe `rm -rf`, force-pushing to protected branches)
- **Git safety issues** (e.g., destructive operations without confirmation)
- **Security concerns** (e.g., credential handling, injection vulnerabilities)

Do not flag: Bash <4.4 compatibility, regex dot escaping on controlled inputs, broad `git add`
in scripts that manage their own working tree, or hardcoded values that are intentionally static.

## CGO and DNS Resolution

Binaries are built with `CGO_ENABLED=0` for portability. This uses Go's native DNS resolver,
Expand Down
Loading