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