Add AGENTS.md (comprehensive agent guide) #1490
Conversation
Mainly generated by codex-cli v0.39.0 with GPT-5(high) and this prompt: - https://gist.github.com/PeterDaveHello/f30c38a156982a35683edfd5ece2d474 Reference: - https://agents.md/
|
Note PR Review SkippedPR review skipped as no relevant changes found due to large diff hunk OR part of a non-reviewable file. 📄Files skipped in review
💡Tips to use MatterAICommand List
|
|
Warning Rate limit exceeded@PeterDaveHello has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 13 minutes and 15 seconds before requesting another review. ⌛ 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. 📒 Files selected for processing (1)
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughAdds a new AGENTS.md file documenting repository guidelines for Transmission GUI: environment setup, project structure, build/test commands, static checks, coding standards, testing procedures, commit/PR rules, safety/permissions, and packaging/distribution workflows across platforms with specified tooling and versioning practices. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
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 |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Summary of ChangesHello @PeterDaveHello, 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 introduces a foundational 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. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
PR Reviewer Guide 🔍Here are some key observations to aid the review process:
|
PR Summary
|
PR Code Suggestions ✨Explore these optional code suggestions:
|
|||||||||||||||||
![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 AGENTS.md, a comprehensive guide for repository development. The document is well-structured and covers essential topics from project setup to contribution guidelines. I've provided a few suggestions to improve the clarity and utility of the commands listed in the guide, such as using placeholders for environment-specific paths and expanding the scope of static analysis checks to include all relevant files.
| - `LAZARUS_DIR=/usr/lib/lazarus/default/ lazbuild -B transgui.lpi` regenerates Lazarus resources before compiling. | ||
| - `LAZARUS_DIR=/usr/lib/lazarus/default/ make -j$(nproc) all` builds the desktop binary without packaging; expect `transgui` (or `transgui.exe`) in the repository root. | ||
| - `LAZARUS_DIR=/usr/lib/lazarus/default/ make -j$(nproc) zipdist` builds the Linux zip bundle into `Release/`. |
There was a problem hiding this comment.
The example path /usr/lib/lazarus/default/ for LAZARUS_DIR is specific to a particular Linux distribution and setup. To make these examples more generic and to reinforce the instruction from the "Dos and Don'ts" section, consider using a placeholder path. This will make it clearer to users that they need to provide their own path to the Lazarus installation.
| - `LAZARUS_DIR=/usr/lib/lazarus/default/ lazbuild -B transgui.lpi` regenerates Lazarus resources before compiling. | |
| - `LAZARUS_DIR=/usr/lib/lazarus/default/ make -j$(nproc) all` builds the desktop binary without packaging; expect `transgui` (or `transgui.exe`) in the repository root. | |
| - `LAZARUS_DIR=/usr/lib/lazarus/default/ make -j$(nproc) zipdist` builds the Linux zip bundle into `Release/`. | |
| - `LAZARUS_DIR=/path/to/your/lazarus/installation lazbuild -B transgui.lpi` regenerates Lazarus resources before compiling. | |
| - `LAZARUS_DIR=/path/to/your/lazarus/installation make -j$(nproc) all` builds the desktop binary without packaging; expect `transgui` (or `transgui.exe`) in the repository root. | |
| - `LAZARUS_DIR=/path/to/your/lazarus/installation make -j$(nproc) zipdist` builds the Linux zip bundle into `Release/`. |
|
|
||
| ### Static checks | ||
|
|
||
| - `docker run -it --rm -v "$(pwd)":/sh -w /sh peterdavehello/shfmt:3.4.0 shfmt -sr -i 2 -l -w -ci .` formats shell scripts like the Travis job. |
There was a problem hiding this comment.
The use of -it in the docker run command is for interactive sessions. For automation and CI/CD pipelines, it's generally better to run containers in a non-interactive mode. Using -it can sometimes cause issues or hang a script if it's expecting input. I suggest removing it to make the command more robust for automation.
| - `docker run -it --rm -v "$(pwd)":/sh -w /sh peterdavehello/shfmt:3.4.0 shfmt -sr -i 2 -l -w -ci .` formats shell scripts like the Travis job. | |
| - `docker run --rm -v "$(pwd)":/sh -w /sh peterdavehello/shfmt:3.4.0 shfmt -sr -i 2 -l -w -ci .` formats shell scripts like the Travis job. |
AGENTS.md
Outdated
| - `find . -type f -name "*.sh" -print0 | xargs -0 shellcheck` runs ShellCheck on all shell scripts. | ||
| - `npx markdown-link-check README.md` validates README links after documentation edits. | ||
| - `npx eclint check lang/ setup/ Makefile* *.txt` enforces `.editorconfig` on templated assets. | ||
| - `doctoc --title "## Table of Contents" --github README.md` refreshes the README ToC; rerun until the diff is clean. |
There was a problem hiding this comment.
This document is quite comprehensive and would benefit from a Table of Contents for easier navigation. You could extend the doctoc command to generate a ToC for AGENTS.md as well, similar to how it's done for README.md.
| - `doctoc --title "## Table of Contents" --github README.md` refreshes the README ToC; rerun until the diff is clean. | |
| - `doctoc --title "## Table of Contents" --github README.md AGENTS.md` refreshes the ToC in Markdown files; rerun until the diff is clean. |
There was a problem hiding this comment.
Pull Request Overview
Adds a new AGENTS.md document containing repository build, packaging, style, and contribution guidelines for Transmission Remote GUI.
- Introduces project structure overview and environment setup requirements
- Documents build/packaging commands across platforms, static checks, and testing/PR practices
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
|
|
||
| ## Build, Test, and Development Commands | ||
|
|
||
| Install Lazarus (≥2.2.6) and FPC (≥3.2.2); most scripts assume `lazbuild` is on PATH or pointed to by `LAZARUS_DIR`. |
There was a problem hiding this comment.
These 'Core workflow' commands are Linux-specific (hard-coded /usr/lib/lazarus path and use of nproc) but are presented as generic. Please label them as Linux-only or provide macOS/Windows equivalents (e.g., avoid hard-coding LAZARUS_DIR, and replace -j$(nproc) with platform-appropriate alternatives or omit -j).
Copilot uses AI. Check for mistakes.
| - `./setup/unix/debian-ubuntu-install_deps.sh` installs Debian/Ubuntu prerequisites (requires sudo and network access). | ||
| - `LAZARUS_DIR=/usr/lib/lazarus/default/ lazbuild -B transgui.lpi` regenerates Lazarus resources before compiling. | ||
| - `LAZARUS_DIR=/usr/lib/lazarus/default/ make -j$(nproc) all` builds the desktop binary without packaging; expect `transgui` (or `transgui.exe`) in the repository root. | ||
| - `LAZARUS_DIR=/usr/lib/lazarus/default/ make -j$(nproc) zipdist` builds the Linux zip bundle into `Release/`. | ||
| - `./setup/unix/build.sh` produces compressed txz releases and temporarily rewrites `about.lfm`; the script restores the backup at the end. | ||
| - `make clean` (with `LAZARUS_DIR` set) removes generated objects after a build. | ||
|
|
There was a problem hiding this comment.
These 'Core workflow' commands are Linux-specific (hard-coded /usr/lib/lazarus path and use of nproc) but are presented as generic. Please label them as Linux-only or provide macOS/Windows equivalents (e.g., avoid hard-coding LAZARUS_DIR, and replace -j$(nproc) with platform-appropriate alternatives or omit -j).
| - `./setup/unix/debian-ubuntu-install_deps.sh` installs Debian/Ubuntu prerequisites (requires sudo and network access). | |
| - `LAZARUS_DIR=/usr/lib/lazarus/default/ lazbuild -B transgui.lpi` regenerates Lazarus resources before compiling. | |
| - `LAZARUS_DIR=/usr/lib/lazarus/default/ make -j$(nproc) all` builds the desktop binary without packaging; expect `transgui` (or `transgui.exe`) in the repository root. | |
| - `LAZARUS_DIR=/usr/lib/lazarus/default/ make -j$(nproc) zipdist` builds the Linux zip bundle into `Release/`. | |
| - `./setup/unix/build.sh` produces compressed txz releases and temporarily rewrites `about.lfm`; the script restores the backup at the end. | |
| - `make clean` (with `LAZARUS_DIR` set) removes generated objects after a build. | |
| #### Linux | |
| - `./setup/unix/debian-ubuntu-install_deps.sh` installs Debian/Ubuntu prerequisites (requires sudo and network access). | |
| - `export LAZARUS_DIR=/usr/lib/lazarus/default/` (or set to your Lazarus installation path). | |
| - `lazbuild -B transgui.lpi` regenerates Lazarus resources before compiling. | |
| - `make -j$(nproc) all` builds the desktop binary without packaging; expect `transgui` in the repository root. | |
| - `make -j$(nproc) zipdist` builds the Linux zip bundle into `Release/`. | |
| - `./setup/unix/build.sh` produces compressed txz releases and temporarily rewrites `about.lfm`; the script restores the backup at the end. | |
| - `make clean` removes generated objects after a build. | |
| #### macOS | |
| - `export LAZARUS_DIR=/Library/Lazarus/` (or set to your Lazarus installation path). | |
| - `lazbuild -B transgui.lpi` regenerates Lazarus resources before compiling. | |
| - `make all` builds the desktop binary; expect `transgui` in the repository root. | |
| - `setup/macosx/create_app_new.sh [/Library/Lazarus/]` emits a signed DMG and resets `about.lfm` afterward. | |
| - `make clean` removes generated objects after a build. | |
| #### Windows | |
| - Set `LAZARUS_DIR` to your Lazarus installation path. | |
| - Use `lazbuild -B transgui.lpi` to regenerate Lazarus resources before compiling. | |
| - Use `make all` to build the desktop binary; expect `transgui.exe` in the repository root. | |
| - `setup/win/make_zipdist.bat <lazarus_dir>` creates the Windows portable zip and optionally compresses `transgui.exe` with UPX. | |
| - `setup/win/make_setup.bat <lazarus_dir> "<Inno Setup dir>"` builds the Windows installer, honoring an optional `CODECERT` for signing. | |
| - `setup/win/install_deps.bat` bootstraps Chocolatey-based dependencies (run in an elevated Windows shell). | |
| - `make clean` removes generated objects after a build. |
Copilot uses AI. Check for mistakes.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
AGENTS.md (1)
5-5: Clarify LAZARUS_DIR guidance in AGENTS.md
- Makefiles already try to auto-detect LAZARUS_DIR and will fail with a clear error prompting "Use LAZARUS_DIR= switch." (See Makefile.fpc LAZARUS_DIR checks ~lines 13–32 and Makefile ~lines 293–307; LAZARUS_DIR is used throughout for LAZRES/unitdirs).
- Build scripts frequently pass the path explicitly: setup/unix/build.sh calls lazbuild with --lazarusdir=/usr/lib/lazarus/default/ (setup/unix/build.sh lines ~14–16); macOS scripts call lazbuild with --lazarusdir=/Library/Lazarus/ and convert a local lazdir to a make-arg like LAZARUS_DIR=/path (setup/macosx/create_app*.sh: lazbuild invocation ~line 27 and lazdir assignment ~lines 11–21).
- Recommendation: change AGENTS.md from "export LAZARUS_DIR before running make or lazbuild" to a short note that Makefiles will auto-detect, and that if detection fails you can either export LAZARUS_DIR, pass LAZARUS_DIR= to make, or use --lazarusdir with lazbuild (link the example scripts above). Minor doc tweak only — no code change required.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
AGENTS.md(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: cubic · AI code reviewer
- GitHub Check: MatterAI Code Review
🔇 Additional comments (4)
AGENTS.md (4)
1-92: Comprehensive documentation enhances maintainability and contributor onboarding.This documentation file provides valuable guidance for developers working on the Transmission GUI project. The structure is logical, covering all essential aspects from environment setup to distribution workflows. The content appears accurate based on the project structure described and follows good documentation practices.
46-50: Verify/update external tooling references in AGENTS.md (lines 46–50)
- shfmt:3.4.0 Docker tag exists — last_updated 2021-10-12.
- .editorconfig is missing; the eclint step will fail unless .editorconfig is added or the step is removed/changed.
- .travis.yml is missing; the "Travis job" reference appears stale — update to the current CI or remove the reference.
- package.json is missing; npx commands require a local package.json (devDependencies/scripts) or global installs — add package.json or clarify installation instructions.
88-91: Referenced packaging files exist at the expected paths. All files listed in the comment (Makefile.fpc; setup/unix/build.sh; setup/win/setup.iss and setup/win/openssl/*; setup/win/make_setup.bat; setup/win/make_zipdist.bat; setup/macosx/create_app_new.sh, Info.plist, transgui.icns; snap/snapcraft.yaml; snap/local/transgui.desktop; VERSION.txt; history.txt; README.md) are present in the repository.
24-24: Confirm/update minimum Lazarus & FPC versions in AGENTS.md (line 24). Lazarus stable is 4.2 (released July 22, 2025) while AGENTS.md lists ≥2.2.6; FPC stable is 3.2.2 (matches ≥3.2.2). If the project requires 4.x-only features, bump Lazarus to ≥4.2; otherwise keep ≥2.2.6 but add a note about the newer stable.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
4 issues found across 1 file
Prompt for AI agents (all 4 issues)
Understand the root cause of the following 4 issues and fix them.
<file name="AGENTS.md">
<violation number="1" location="AGENTS.md:5">
Exporting LAZARUS_DIR is not required for lazbuild; scripts pass --lazarusdir explicitly. Suggest clarifying to avoid implying it’s mandatory.</violation>
<violation number="2" location="AGENTS.md:40">
</violation>
<violation number="3" location="AGENTS.md:47">
ShellCheck command doesn’t match CI. Align doc with .travis.yml to avoid confusion.</violation>
<violation number="4" location="AGENTS.md:48">
markdown-link-check scope differs from CI. Update to reflect actual CI behavior.</violation>
</file>
Since this is your first cubic review, here's how it works:
- cubic automatically reviews your code and comments on bugs and improvements
- Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
- Ask questions if you need clarification on any suggestion
React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.
|
|
||
| - `setup/win/make_zipdist.bat <lazarus_dir>` creates the Windows portable zip and optionally compresses `transgui.exe` with UPX. | ||
| - `setup/win/make_setup.bat <lazarus_dir> "<Inno Setup dir>"` builds the Windows installer, honoring an optional `CODECERT` for signing. | ||
| - `setup/win/install_deps.bat` bootstraps Chocolatey-based dependencies (run in an elevated Windows shell). |
There was a problem hiding this comment.
Prompt for AI agents
Address the following comment on AGENTS.md at line 40:
<comment></comment>
<file context>
@@ -0,0 +1,91 @@
+
+- `setup/win/make_zipdist.bat <lazarus_dir>` creates the Windows portable zip and optionally compresses `transgui.exe` with UPX.
+- `setup/win/make_setup.bat <lazarus_dir> "<Inno Setup dir>"` builds the Windows installer, honoring an optional `CODECERT` for signing.
+- `setup/win/install_deps.bat` bootstraps Chocolatey-based dependencies (run in an elevated Windows shell).
+- `setup/macosx/create_app_new.sh [/Library/Lazarus/]` emits a signed DMG and resets `about.lfm` afterward.
+- `snapcraft` (run from the repository root) packages the app using `snap/snapcraft.yaml`.
</file context>
✅ Addressed in 2d710e6
AGENTS.md
Outdated
|
|
||
| - `docker run -it --rm -v "$(pwd)":/sh -w /sh peterdavehello/shfmt:3.4.0 shfmt -sr -i 2 -l -w -ci .` formats shell scripts like the Travis job. | ||
| - `find . -type f -name "*.sh" -print0 | xargs -0 shellcheck` runs ShellCheck on all shell scripts. | ||
| - `npx markdown-link-check README.md` validates README links after documentation edits. |
There was a problem hiding this comment.
markdown-link-check scope differs from CI. Update to reflect actual CI behavior.
Prompt for AI agents
Address the following comment on AGENTS.md at line 48:
<comment>markdown-link-check scope differs from CI. Update to reflect actual CI behavior.</comment>
<file context>
@@ -0,0 +1,91 @@
+
+- `docker run -it --rm -v "$(pwd)":/sh -w /sh peterdavehello/shfmt:3.4.0 shfmt -sr -i 2 -l -w -ci .` formats shell scripts like the Travis job.
+- `find . -type f -name "*.sh" -print0 | xargs -0 shellcheck` runs ShellCheck on all shell scripts.
+- `npx markdown-link-check README.md` validates README links after documentation edits.
+- `npx eclint check lang/ setup/ Makefile* *.txt` enforces `.editorconfig` on templated assets.
+- `doctoc --title "## Table of Contents" --github README.md` refreshes the README ToC; rerun until the diff is clean.
</file context>
| - `npx markdown-link-check README.md` validates README links after documentation edits. | |
| - `find . -type f -name "*.md" | xargs -n 1 npx markdown-link-check` validates links in all Markdown files. |
✅ Addressed in 39562b2
AGENTS.md
Outdated
| ### Static checks | ||
|
|
||
| - `docker run -it --rm -v "$(pwd)":/sh -w /sh peterdavehello/shfmt:3.4.0 shfmt -sr -i 2 -l -w -ci .` formats shell scripts like the Travis job. | ||
| - `find . -type f -name "*.sh" -print0 | xargs -0 shellcheck` runs ShellCheck on all shell scripts. |
There was a problem hiding this comment.
ShellCheck command doesn’t match CI. Align doc with .travis.yml to avoid confusion.
Prompt for AI agents
Address the following comment on AGENTS.md at line 47:
<comment>ShellCheck command doesn’t match CI. Align doc with .travis.yml to avoid confusion.</comment>
<file context>
@@ -0,0 +1,91 @@
+### Static checks
+
+- `docker run -it --rm -v "$(pwd)":/sh -w /sh peterdavehello/shfmt:3.4.0 shfmt -sr -i 2 -l -w -ci .` formats shell scripts like the Travis job.
+- `find . -type f -name "*.sh" -print0 | xargs -0 shellcheck` runs ShellCheck on all shell scripts.
+- `npx markdown-link-check README.md` validates README links after documentation edits.
+- `npx eclint check lang/ setup/ Makefile* *.txt` enforces `.editorconfig` on templated assets.
</file context>
✅ Addressed in 7102c1e
![qodo-merge-pro[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
|
Note PR Review SkippedPR review skipped as no relevant changes found due to large diff hunk OR part of a non-reviewable file. 📄Files skipped in review
💡Tips to use MatterAICommand List
|
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
|
Note PR Review SkippedPR review skipped as no relevant changes found due to large diff hunk OR part of a non-reviewable file. 📄Files skipped in review
💡Tips to use MatterAICommand List
|
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
|
Note PR Review SkippedPR review skipped as no relevant changes found due to large diff hunk OR part of a non-reviewable file. 📄Files skipped in review
💡Tips to use MatterAICommand List
|
Co-authored-by: qodo-merge-pro[bot] <151058649+qodo-merge-pro[bot]@users.noreply.github.com>
|
Note PR Review SkippedPR review skipped as no relevant changes found due to large diff hunk OR part of a non-reviewable file. 📄Files skipped in review
💡Tips to use MatterAICommand List
|
There was a problem hiding this comment.
Pull Request Overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
|
|
||
| ## Testing Guidelines | ||
|
|
||
| - No automated Pascal tests are present; perform manual regression on features affected (torrent list, dialogs, localization paths). |
There was a problem hiding this comment.
[nitpick] This statement about "No automated Pascal tests are present" could become outdated if tests are added in the future. Consider rephrasing to "Currently no automated Pascal tests are present" or similar to indicate this is the current state.
| - No automated Pascal tests are present; perform manual regression on features affected (torrent list, dialogs, localization paths). | |
| - Currently, no automated Pascal tests are present; perform manual regression on features affected (torrent list, dialogs, localization paths). |
Copilot uses AI. Check for mistakes.
1 participant
Mainly generated by codex-cli v0.39.0 with GPT-5(high) and this prompt:
Reference:
Summary by cubic
Add AGENTS.md: a practical contributor guide for building, packaging, linting, testing, and submitting PRs for Transmission Remote GUI. It documents Lazarus/FPC setup, required env vars (LAZARUS_DIR), platform packaging scripts, CI-aligned static checks, coding/localization conventions, and safety rules to reduce CI failures and keep releases consistent.
Summary by CodeRabbit