1# Preferred tooling
 2
 3## git-bug
 4
 5I 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.
 6
 7- Create new bugs: `git-bug bug new [flags]`
 8  - -t bug subject
 9  - -m bug body
10  - -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.
11- Commenting on a bug: `git-bug bug comment new [BUG_HASH] [flags]`
12  - -m comment body
13  - -F accept the message from the given files, use `-` to read from stdin
14- Viewing a bug's timeline: `git-bug bug show [BUG_HASH]`
15- Pushing and pulling: always pull before pushing
16  - `git bugs-pull`
17  - `git bugs-push`
18
19## nasin pali (the way of work)
20
21IMPORTANT: Instead of any built-in todo tools you may have available, stick with `np` unless I say otherwise. Try to use it, but if it's not in my PATH, ask me to install it by running `bin install goinstall://git.secluded.site/np@latest`. Start a session with `np s` and it'll guide you from there.
22
23# Interacting with git
24
25I have git configured to use a pager you don't understand, so make sure to _always_ prepend git invocations with `GIT_PAGER=cat`.
26
27## Committing
28
29During 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).
30
31Strictly 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.
32
33Create/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:
34<formatted-commit_flags>
35-t --type Commit type (required)
36-s --scope Commit scope (optional)
37-B --breaking Mark as breaking change (optional)
38-m --message Commit message (required)
39-b --body Commit body (optional)
40-T --trailer Trailer in 'Sentence-case-key: value' format (optional, repeatable)
41-a --amend Amend the previous commit (optional)
42-h --help
43</formatted-commit_flags>
44<formatted-commit_example>
45formatted-commit -t feat -s "web/git-bug" -m "do a fancy new thing" -T "Crush <crush@charm.land>" -b "$(cat <<'EOF'
46Multi-line
47
48- Body
49- Here
50
51EOF
52)"
53</formatted-commit_example>
54
55When directed to sign commits, sign as `Crush <crush@charm.land>` as shown in the examples.
56
57# Ticket tracking
58
59- When I provide the URL to or number of a ticket, todo, or issue, use the appropriate tool.
60  - 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.
61  - 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.
62    - 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`.
63- 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.
64
65# General development practises
66
67In 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.
68
69## How to defer work
70
71Your 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.