Skip to content

AGENTS.md

Latest commit

 

History

History
67 lines (50 loc) · 5.09 KB

AGENTS.md

File metadata and controls

67 lines (50 loc) · 5.09 KB
Raw

AGENTS.md - Coding Agent Guidelines for LNVPS

This file is an index. Load only the specific doc(s) relevant to your task to minimize context usage.

Always load docs/agents-common/common.md first — it contains essential guidelines for task sizing, git commits, and git push that apply to all tasks.

Git push — Always push using the HTTPS URL directly: git push https://github.com/LNVPS/api.git

File Description
work/agent-rules-compliance.md Bringing codebase into full compliance with all agent rules

Generic Docs

These docs apply to all projects using this agent structure:

Doc When to load
docs/agents-common/bug-fixes.md Resolving bugs (includes regression test requirement)
docs/agents-common/coverage.md Any edit that adds or modifies functions (100% function coverage required)
docs/agents-common/incremental-work.md Managing a work file for a multi-increment task

Project-Specific Docs

Doc When to load
docs/agents/project-overview.md Understanding workspace crates, feature flags, module structure
docs/agents/build-and-test.md Running builds, tests, clippy, or formatting
docs/agents/code-style.md Writing or reviewing Rust code (imports, errors, naming, async, derives, serde, tests)
docs/agents/api-guidelines.md Modifying any user-facing or admin API endpoint
docs/agents/migrations.md Adding or modifying database migrations
docs/agents/currency.md Working with money amounts, pricing, or payments
docs/agents/bug-fixes.md Resolving bugs — LNVPS-specific additions
docs/agents/coverage.md Function coverage — LNVPS-specific additions
docs/agents/e2e-tests.md Writing or running E2E integration tests (lnvps_e2e crate)
docs/agents/testing-db-backups.md Testing branch changes (migrations, startup) against a restored production DB backup safely (mock hosts, no user notifications)
docs/agents/fw-testing.md Running or extending the firewall XDP netns test harness (lnvps_fw)

Pull Request Procedure

When creating a PR that closes a GitHub issue:

  1. Label the issue — Before opening the PR, apply appropriate labels to the linked issue using gh issue edit <number> --add-label "<label>". Choose from existing repo labels; create a new one with gh label create only if no existing label fits. Typical labels:
    • bug — something is broken
    • enhancement — new feature or improvement
    • host:proxmox / host:libvirt — host-specific changes
    • api — user-facing or admin API changes
    • database — migration or schema changes
    • payments — payment/invoice logic
    • refactor — internal restructuring without behaviour change
    • documentation — docs-only change
  2. Open the PR — Reference the issue in the PR body (Fixes #N).

Release Procedure

When the user asks to create a release:

  1. Update API_CHANGELOG.md — Change ## [Unreleased] to ## [vX.Y.Z] - YYYY-MM-DD with the current date
  2. Update Cargo.toml versions — Bump the version in the root Cargo.toml under [workspace.package] (all crates inherit via version.workspace = true)
  3. Bump the lnvps_fw version — lnvps_fw is a separate workspace (excluded from the root one) with its own [workspace.package] version in lnvps_fw/Cargo.toml. Bump it to the same X.Y.Z as the main workspace so the two stay in lockstep. This matters: the firewall daemon's self-upgrade (lnvps_fw_service/src/upgrade.rs) compares its compiled CARGO_PKG_VERSION against the newest vX.Y.Z GitHub release tag — if lnvps_fw/Cargo.toml lags behind the tag, every running daemon will report an upgrade is available on startup and every 6h.
  4. Commit the changes — git commit -m "chore: release vX.Y.Z"
  5. Create an annotated tag — git tag -a vX.Y.Z -m "Release vX.Y.Z"
  6. Push commit and tag — git push https://github.com/LNVPS/api.git && git push https://github.com/LNVPS/api.git vX.Y.Z

lnvps_fw release artifact

The vX.Y.Z tag is what drives the firewall release. Pushing it triggers the .github/workflows/lnvps_fw-deb.yml workflow, which builds the lnvps_fw_service daemon (including the eBPF datapath, via a nightly rust-src + bpf-linker toolchain) into a Debian package with cargo deb and attaches the .deb to the GitHub release. Running daemons then discover and install that .deb through the self-upgrade endpoint (GET/POST /api/v1/upgrade). There is no separate fw tag — the fw workspace shares the single vX.Y.Z tag, which is exactly why step 3's version bump must happen before tagging.