torrust

Guide for releasing a new version of the deployer using the standard branch/tag workflow. Covers version bump, signed release commit, pushing main, creating signed tag, creating release branch, and verifying Docker + crate publication workflows. Use when asked to "release", "cut a version", "publish a new version", or "create release vX.Y.Z".

Run a complete local end-to-end test using the LXD provider to verify a feature, fix, or change works as expected from the user's perspective. Covers creating an environment config, provisioning a VM, deploying the tracker, verifying it works, and cleaning up. Use when manually testing changes, validating a new feature locally, running a full deployment smoke test, or checking that the deployer works end-to-end. Triggers on "local e2e", "manual e2e test", "test my changes locally", "run deployer end-to-end", "smoke test", "test on LXD", "verify feature works", or "full deployment test".

Check whether the system has all dependencies required by the deployer (OpenTofu, Ansible, LXD, cargo-machete). Use before running provisioning, E2E tests, or any infrastructure command. Triggers on "check dependencies", "check system dependencies", "are dependencies installed", "verify dependencies", "dependency check", or "missing tools".

Install the system dependencies required by the deployer (OpenTofu, Ansible, LXD, cargo-machete) using the built-in dependency-installer. This is the setup/installer step before using the deployer for the first time. Triggers on "install dependencies", "install system dependencies", "setup deployer", "first time setup", "missing dependency", "install opentofu", "install ansible", "install lxd", or "deployer setup".

Open a pull request from a feature branch using GitHub CLI (preferred) or GitHub MCP tools. Covers pre-flight checks, correct base/head configuration for fork workflows, title/body conventions, and post-creation validation. Use when asked to "open PR", "create pull request", or "submit branch for review".

Guide for updating project dependencies using the update-dependencies.sh automation script. Automates the cargo update workflow including branch creation, commit, push, and optional PR creation. Use when updating dependencies, running cargo update, or automating the dependency lifecycle. Triggers on "update dependencies", "cargo update", "update deps", "bump dependencies", or "run dependency update".

Guide for committing changes in the torrust-tracker-deployer project. Covers conventional commit format, pre-commit verification checks, issue number conventions, and commit quality guidelines. Use when committing code, running pre-commit checks, or following project commit standards. Triggers on "commit", "commit changes", "how to commit", "pre-commit", "commit message", "commit format", or "conventional commits".

Guide for debugging and troubleshooting local LXD VM instances created by the deployer. Covers SSH connectivity failures (too many authentication failures, key issues, connection refused), bypassing SSH with lxc exec, cloud-init problems, networking issues, and general LXD instance inspection. Use when a developer cannot access a deployed LXD VM, encounters SSH errors, or needs to inspect VM state without SSH. Triggers on "lxd troubleshoot", "ssh failed lxd", "can't ssh into vm", "lxd debug", "too many authentication failures", "lxc exec", "vm not reachable", "lxd instance problem", "debug lxd instance", or "lxd networking issue".

Guide for pushing commits in the torrust-tracker project. Covers the push workflow, pre-push hook setup, and the SSH idle-timeout problem that can interrupt pushes when the pre-push hook runs long. Triggers on "push changes", "git push", "how to push", "push branch", "SSH timeout on push", or "Connection closed by remote host".

Run all mandatory pre-push verification steps for the torrust-tracker project. Covers the pre-push script (automated checks), output modes, and log-directory configuration. Use before pushing or when running the nightly toolchain checks and the full stable test suite. Triggers on "pre-push checks", "run pre-push", "verify before push", or "push checks".

Guide for error handling in this Rust project. Covers the four principles (clarity, context, actionability, explicit enums over anyhow), the thiserror pattern for structured errors, including what/where/when/why context, writing actionable help text, and avoiding vague errors. Also covers the located-error package for errors with source location. Use when writing error types, handling Results, adding error variants, or reviewing error messages. Triggers on "error handling", "error type", "Result", "thiserror", "anyhow", "error enum", "error message", "handle error", "add error variant", or "located-error".

Guide for releasing a new version of the Torrust Tracker using the standard staging branch, tag, and crate publication workflow. Covers version bump, release commit, staging branch promotion, PR to main, release branch/tag creation, crate publication, and merge-back to develop. Use when asked to "release", "cut a version", "publish a new version", or "create release vX.Y.Z".

Fetch unresolved GitHub pull request review thread IDs for the torrust-tracker project. Use when asked to find open PR review threads, list unresolved review comments, collect thread IDs before resolving suggestions, or inspect Copilot review feedback. Triggers on "fetch review threads", "list unresolved PR comments", "get review thread IDs", or "find open review suggestions".

Resolve addressed GitHub pull request review threads for the torrust-tracker project. Use when asked to mark PR suggestions as resolved, resolve review comments, close addressed review threads, or clear Copilot review feedback after fixes are pushed. Triggers on "resolve PR threads", "mark suggestions as resolved", "resolve review comments", or "close addressed review threads".

Guide for writing unit tests following project conventions including behavior-driven naming (it*should*\*), AAA pattern, MockClock for deterministic time testing, and parameterized tests with rstest. Use when adding tests for domain entities, value objects, utilities, or tracker logic. Triggers on "write unit test", "add test", "test coverage", "unit testing", or "add unit tests".

End-to-end workflow for processing and resolving all Copilot code review suggestions on a pull request in torrust-tracker. Use when asked to handle PR review feedback, process all copilot suggestions, audit and resolve review comments, or manage copilot-generated review threads. Triggers on "process copilot suggestions", "handle all PR feedback", "resolve copilot review", "audit PR suggestions", or "close all copilot comments".

Workflow for checking whether UDP packet loss or uptime degradation may be caused by conntrack saturation on the torrust-tracker-demo server. Use when diagnosing UDP timeouts, low newTrackon uptime, packet drops, conntrack pressure, UDP receive-buffer errors, or when validating whether conntrack tuning is still healthy.

Step-by-step process for creating and opening a GitHub issue in the torrust-tracker-demo repository. Use when asked to open, create, or file an issue. Covers writing the draft file, human review, opening on GitHub, renaming the file, and committing. Triggers on "open issue", "create issue", "new issue", "file issue", "draft issue".

Step-by-step workflow for resizing (scaling up) the Hetzner server in the torrust-tracker-demo stack. Use when asked to resize, scale up, or upgrade the server plan. Covers pre-resize preparation, graceful shutdown, provider panel action, post-resize recovery, and evidence capture. Triggers on "resize server", "scale up", "upgrade server plan", "Hetzner resize", "change server type".

Workflow for investigating server and service performance bottlenecks in the torrust-tracker-demo repository. Use when debugging uptime degradation, high load, latency spikes, dropped packets, or suspected capacity limits. Triggers on "performance issue", "high load", "uptime drop", "bottleneck", "capacity", "scaling", "degraded service", "newTrackon uptime".

Create and open a pull request in the torrust-tracker-demo repository. Use when asked to open a PR, create a pull request, submit a PR, or push changes and create a PR. Triggers on "open PR", "create PR", "submit PR", "push and open PR", "open pull request".

Guide for committing changes in the torrust-tracker-demo repository. Covers running all linters locally before committing to ensure CI passes. Triggers on "commit", "how to commit", "before committing", "pre-commit checks", "run linters", "check before commit".

Create a git branch to start working on a GitHub issue in the torrust-tracker-demo repository. Use when asked to start working on an issue, create a branch for an issue, or check out a new branch. Triggers on "create branch", "new branch", "start working on issue", "branch for issue", "checkout branch".

Run linters for the torrust-tracker-demo repository. Covers running the canonical lint script, installing the lint wrapper and prerequisites, and troubleshooting markdown, YAML, spelling, shellcheck, npm permission, and Node/cspell compatibility issues. Triggers on "run linters", "lint", "check lint", "run lint", "linting", "spell check", "check markdown", "check yaml", "lint script", "install linter", "lint troubleshooting".

Creates a new blog post for the Torrust website. Use when asked to write, add, create, or publish a new blog post or article.

Opens a GitHub Pull Request from the current branch, linking it to the related issue when the branch name starts with an issue number.

Creates a new git branch for a GitHub issue following naming conventions with issue number as prefix.

Creates a new Svelte UI component for the Torrust website. Use when asked to add, create, or build a new reusable UI component, widget, or UI element.

Deploys the Torrust website to GitHub Pages. Use when asked to deploy, publish, or release the site, or to set up the deployment workflow.

Runs the full quality check suite for the Torrust website. Use before committing or opening a PR to verify types, linting, and that the build succeeds.

Updates the contributors list on the Torrust website homepage. Use when asked to refresh, update, or sync the contributors list from the Torrust GitHub org.