1# General development practises
 2
 3In 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.
 4
 5## How to defer work
 6
 7Your 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.
 8
 9# Preferred tooling
10
11## git-bug
12
13I 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.
14
15- Create new bugs: `git-bug bug new [flags]`
16  - -t bug subject
17  - -m bug body
18  - -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.
19- Commenting on a bug: `git-bug bug comment new [BUG_HASH] [flags]`
20  - -m comment body
21  - -F accept the message from the given files, use `-` to read from stdin
22- Viewing a bug's timeline: `git-bug bug show [BUG_HASH]`
23- Pushing and pulling: always pull before pushing
24  - `git bugs-pull`
25  - `git bugs-push`
26
27## nasin pali (the way of work)
28
29IMPORTANT: 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.
30
31# Workflows
32
33## Ticket tracking
34
35- When I provide the URL to or number of a ticket, todo, or issue, use the appropriate tool.
36  - 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.
37  - 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.
38    - 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`.
39- 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.
40
41## Interacting with git
42
43I have git configured to use a pager you don't understand, so make sure to _always_ prepend git invocations with `GIT_PAGER=cat`.
44
45## Committing
46
47During 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).
48
49Strictly 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.
50
51Valid trailers for ticket tracking integration depend on the platform we're currently using:
52
53- GitHub
54  - Closes:
55  - Fixes:
56  - Resolves:
57  - References:
58- SourceHut
59  - Closes:
60  - Fixes:
61  - Implements:
62  - References:
63- git-bug
64  - Closes:
65  - References:
66  - Implements:
67
68Create/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:
69<formatted-commit_flags>
70-t --type Commit type (required)
71-s --scope Commit scope (optional)
72-B --breaking Mark as breaking change (optional)
73-m --message Commit message (required)
74-b --body Commit body (optional)
75-T --trailer Trailer in 'Sentence-case-key: value' format (optional, repeatable)
76-a --amend Amend the previous commit (optional)
77-h --help
78</formatted-commit_flags>
79<formatted-commit_example>
80formatted-commit -t feat -s "web/git-bug" -m "do a fancy new thing" -T "Crush <crush@charm.land>" -b "$(cat <<'EOF'
81Multi-line
82
83- Body
84- Here
85
86EOF
87)"
88</formatted-commit_example>
89
90When directed to sign commits, sign as `Crush <crush@charm.land>` as shown in the examples.