diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..44059dd0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,91 @@ +# Repository Guidelines + +## Dos and Don’ts + +- Do ensure Lazarus is discoverable: set `LAZARUS_DIR` for `make`, or pass `--lazarusdir` to `lazbuild` as in our scripts. +- Do keep `.pas` and `.lfm` changes synchronized through Lazarus; update `lang/transgui.template` plus locale files together. +- Do run only the CI steps relevant to touched files, mirroring the commands in `.travis.yml`. +- Don’t edit generated artifacts such as `Makefile` or commit outputs under `Release/`. +- Don’t modify third-party sources in `synapse/` or bundled libraries in `setup/win/openssl/` unless you are porting an upstream fix. + +## Project Structure and Module Organization + +Transmission Remote GUI is a Lazarus/Free Pascal desktop client for Transmission’s RPC API. + +- `transgui.lpi`, `transgui.lpr`, and the root `.pas`/`.lfm` pairs implement the application UI and logic. +- `lang/` contains key-value locale files; `transgui.template` is the canonical English resource. +- `synapse/` bundles the Synapse networking library; treat it as vendor code. +- `setup/` hosts packaging assets for Unix, macOS, and Windows builds (e.g., `unix/build.sh`, `macosx/create_app_new.sh`, `win/make_zipdist.bat`). +- `snap/` stores `snapcraft.yaml` and the desktop entry used for Snap builds. +- `.github/workflows/` and `.travis.yml` define automation; `VERSION.txt`, `history.txt`, and the various README files document releases. + +## 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`. + +### Core workflow + +- `cat VERSION.txt` shows the release number consumed by build scripts. +- `./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. + +### Platform packaging + +- `setup/win/make_zipdist.bat ` creates the Windows portable zip and optionally compresses `transgui.exe` with UPX. +- `setup/win/make_setup.bat ""` 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`. + +### 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 . -path ./synapse -prune -o -type f -name "*.sh" -print0 | xargs -0 shellcheck` runs ShellCheck on all non-vendor shell scripts. +- `npx markdown-link-check README.md AGENTS.md` validates links in Markdown files after documentation edits. +- `npx eclint check lang/ setup/ Makefile* *.txt` enforces `.editorconfig` on templated assets. +- `npx doctoc --title "## Table of Contents" --github README.md` refreshes the README ToC; rerun until the diff is clean. + +## Coding Style and Naming Conventions + +- `.editorconfig` enforces UTF-8, LF endings (CRLF for `.txt`/`.bat`), and two-space indentation for Pascal, Lazarus project files, and shell scripts. +- Pascal units stay in `{$mode objfpc}{$H+}`; form classes follow the `TForm` naming pattern and expect matching `.lfm` changes. +- Use English for code comments; multi-line comments typically use `{ ... }` blocks, with `//` for inline notes. +- Locale files keep quoted key/value pairs and placeholder ordering; translate via `lang/transgui.template` to maintain consistency. +- Shell scripts preserve the existing shebang plus `set -ex`; prefer POSIX constructs to keep Travis checks green. +- Do not edit `Makefile`; modify `Makefile.fpc` or Lazarus project settings if build options need to change. + +## Testing Guidelines + +- No automated Pascal tests are present; perform manual regression on features affected (torrent list, dialogs, localization paths). +- For core behavior changes, run the app against a test Transmission daemon (local or remote) and confirm basic flows (add/start/stop torrents, refresh list). +- Record which static checks from `.travis.yml` were run locally; execute only those relevant to the files you touched. +- When packaging scripts change, run the corresponding script in an isolated environment and verify the artifact names (`Release/transgui--*.{zip,txz,dmg}`). +- For locale updates, launch the app with that locale to confirm formatting, placeholders, and traditional Chinese typography where applicable. +- Document manual verification steps in the PR description to aid reviewers. + +## Commit and Pull Request Guidelines + +- Write imperative, capitalized subjects (e.g., `Fix RPC boolean handling`); append issue numbers in parentheses when closing tickets. +- Keep changes focused; separate localization refreshes, packaging tweaks, and code fixes into discrete commits. +- Ensure CI jobs (Travis static checks, GitHub workflows) pass; mention any skipped jobs and why. +- Update `history.txt` and README variants only when user-facing behavior shifts; keep Markdown Table of Contents in sync via `doctoc`. +- Provide screenshots or recordings for UI-affecting changes, especially when adjusting forms or translations. + +## Safety and Permissions + +- Allowed: inspect files, adjust Lazarus form pairs tied to your change, and run targeted lint/build commands with `LAZARUS_DIR` set. +- Ask before adding dependencies, renaming units, deleting locales, or altering packaging pipelines in `setup/` and `snap/`. +- Never commit build artifacts under `Release/`, temporary files produced by `build.sh`, or personal signing material. +- Restore generated backups (`about.lfm.bak`, etc.) and verify `git status` is clean before committing. +- Treat credentials and API tokens referenced in workflows as secrets; do not hardcode or log them. + +## Packaging and Distribution + +- Linux releases rely on `Makefile.fpc` plus `setup/unix/build.sh`; keep widgetset and CPU flags aligned with the existing scripts. +- Windows deliverables use `setup/win/setup.iss` and bundled OpenSSL DLLs (`setup/win/openssl/`); refresh both when upgrading TLS libraries. +- macOS builds depend on `setup/macosx/create_app_new.sh`, `Info.plist`, and `transgui.icns`; verify metadata placeholders resolve correctly. +- Snap packages follow `snap/snapcraft.yaml` and `snap/local/transgui.desktop`; update them whenever assets move or new permissions are needed.