AGENTS.md

General development practises

In my opinion, JSON should never need to be written or read by humans, unless the project already requires that. When introducing configuration formats, prefer human-readable formats like TOML or INI. JSON is exclusively for transmitting data over the wire and should be immediately turned into language-native types when not user-facing or turned into a human-readable configuration language when user-facing.

How to defer work

Your suggestions are valuable and our findings while working are important. When we identify an issue, or you suggest improvements, fixes, etc., but I say we'll tackle them later, suggest creating a bug with git-bug so we don't lose that information. Any time we find a bug resulting from a commit, include the trailer References: {SHORT_COMMIT_HASH}. When we're working on a bug and realise we'll need to fix something later about our implementation of that bug resolution, include References: bug-{SHORT_BUG_HASH} trailer. For all bugs, issues, todos, tickets, and comments you create, include yourself in the Co-authored-by: trailer at the bottom.

Preferred tooling

git-bug

I like using a bug tracker that embeds bugs and identities and conversations directly in the repo we're working in. These can be private bugs just for me, or public bugs I push to the remote repo to collaborate on with other contributors. It's called git-bug and you interact with it like so.

  • Create new bugs: git-bug bug new [flags]
    • -t bug subject
    • -m bug body
    • -F accept the subject and from the given files, use - to read from stdin. The first line is the subject, then include a blank line, then the body, then a blank line, then any trailers.
  • Commenting on a bug: git-bug bug comment new [BUG_HASH] [flags]
    • -m comment body
    • -F accept the message from the given files, use - to read from stdin
  • Viewing a bug's timeline: git-bug bug show [BUG_HASH]
  • Pushing and pulling: always pull before pushing
    • git bugs-pull
    • git bugs-push

nasin pali (the way of work)

IMPORTANT: If I ask you to use np or use nasin pali or some variation, you must completely ignore your built-in TODO tools and exclusively use what np provides. Try to use it directly, but if it's reported unavailable or not in my PATH, ask me to install it with bin install goinstall://git.secluded.site/np@latest. If I've ask you to use it, start a session with np s. If I haven't asked you to use it, proceed normally.

Workflows

Ticket tracking

  • When I provide the URL to or number of a ticket, todo, or issue, use the appropriate tool.
    • github.com or "issue": gh issue view https://github.com/USER/REPO/issues/XXX where XXX is the issue number. USER and REPO are required, so if you can't determine this from branch/remotes, ask me before running the gh command.
    • todo.sr.ht, "todo", or "ticket: hut todo ticket show -t '~USER/TRACKER' XXX where XXX is the ticket number. I'll refer to these as todos or tickets. USER and TRACKER are required, so if you can't determine this from branch/remotes, ask me before running the hut command.
      • Run git remote -v and notice whether any of the remotes include 'soprani.ca', 'sopranica', 'singpolyma', variations of 'cheogram', or 'sgx-XXX' where XXX is an arbitrary string (for example, sgx-jmp, sgx-bwmsgsv2, sgx-endstream, etc.). If any of those keywords are found, the relevant tracker is ~singpolyma/soprani.ca.
  • When I specifically reference a "bug" and provide a hash instead of a number, I'm referring to a bug created with git-bug. Use git-bug bug show HASH to read the bug and discussion. You may use git-bug bug status (close|open) to modify the bug's status ONLY if I give explicit permission.

Interacting with git

I have git configured to use a pager you don't understand, so make sure to always prepend git invocations with GIT_PAGER=cat.

Committing

During the course of our conversation, we may implement not only the thing we set out to implement, we might also introduce some bugs and fix them before making the commit. When creating commits, only reference bugs/issues/tickets/problems that have existed since the last commit; don't mention issues introduced and fixed during this session, just the pre-existing one(s).

Strictly follow Conventional Commits. For AUR packages, the prefix will usually be chore: with no scope. For most source code repositories, we'll usually require both an appropriate prefix and scope. Necessity of scope increases with repository size; the smaller the repo, the less necessary the scope.

Valid trailers for ticket tracking integration depend on the platform we're currently using:

  • GitHub
    • Closes:
    • Fixes:
    • Resolves:
    • References:
  • SourceHut
    • Closes:
    • Fixes:
    • Implements:
    • References:
  • git-bug
    • Closes:
    • References:
    • Implements:

Create/amend commits exclusively using formatted-commit. Try to use it normally, but if it's not in my PATH, ask me to go install git.secluded.site/formatted-commit@latest. It has no sub-commands and the following options: <formatted-commit_flags> -t --type Commit type (required) -s --scope Commit scope (optional) -B --breaking Mark as breaking change (optional) -m --message Commit message (required) -b --body Commit body (optional) -T --trailer Trailer in 'Sentence-case-key: value' format (optional, repeatable) -a --amend Amend the previous commit (optional) -h --help </formatted-commit_flags> <formatted-commit_example> formatted-commit -t feat -s "web/git-bug" -m "do a fancy new thing" -T "Crush crush@charm.land" -b "$(cat <<'EOF' Multi-line

  • Body
  • Here

EOF )" </formatted-commit_example>

When directed to sign commits, sign as Crush <crush@charm.land> as shown in the examples.