48 lines
11 KiB
Markdown
48 lines
11 KiB
Markdown
# Writing to a Ticket
|
|
|
|
The writers of a field, the one way to take a value away, and ticking a criterion.
|
|
|
|
## Editing a Ticket
|
|
- `set` replaces a field, `append` adds to a section. The verb carries the meaning, so no flag needs a replace-or-append prefix, and `append` only offers the sections that hold multiple lines
|
|
- **One field, one writer.** `set` has no `--owner` (that is `chown`'s) and no `--status` (that is `mv`'s), and neither `add`, `set`, `append` nor `chown` can reach the three status stamps, which `mv` writes as a side effect of the move. Do not add any of them
|
|
- `chown` takes the **user first and the ticket second**, after Unix `chown`, and is the only command that does not start with the ticket. Deliberate: the name borrows the Unix association, so the order borrows it too. A swap is left to `resolve_ticket`, which refuses a bare username as a ticket. No argument is inspected to see whether it *also* names a ticket, since such a check would only fire where resolution already fails and would stay silent on the one case it cannot catch, a ticket whose title is the username
|
|
- `cmd_chown` is `set_metadata_field` plus `save_ticket`, with the same whole-file no-op comparison `set` uses and the same `report()` output, so nothing about writing a field lives twice
|
|
- `apply()` is the one place an edit is taken or dropped, shared by `set`'s replaced list and its cleared one. It was a closure over the single list until there were two, and two closures carrying one rule is how a later edit changes it for one and not the other
|
|
- Sections are a table in `util.rs`: `DESCRIPTION`, `ACCEPTANCE`, `PLAN`, each with a heading, a label, the placeholder `add` writes when empty, a `SectionKind` and the `--clear` value that empties it. Adding a section later is one entry, not edits in both commands
|
|
- Everything is targeted line surgery, never a regenerated file. That is what keeps a ticked criterion ticked and a handwritten `## Notes` section intact when an unrelated field changes. `section_body()` finds the lines to touch, `set_metadata_line()` does the metadata, and every other byte is copied through
|
|
- Appending to a numbered section continues from the count of steps already there and does not renumber what is above it, so a handwritten line in the section survives exactly as written
|
|
- Appending to an empty section replaces the placeholder rather than following it, or the ticket would read `_No description provided._` above its description
|
|
- An empty value is a paragraph break for the three sections and a usage error for the scalars, via `non_empty` and `clearable` in `command.rs`. Neither spells clearing, and both errors name the flag that does
|
|
- **A call whose values are *every one* blank is refused, by `replaced_items` for `set` and `appended_items` for `append`.** The check is the section's rather than the object's, so `campaign set --description` shares it. What differs is the way out, which is why `replaced_items` takes it as an argument: a ticket's section is emptied with `--clear <field>` and a campaign's description cannot be emptied at all, so a single hard-coded tail would name a flag that does not exist on one of the two
|
|
|
|
## Clearing a Field
|
|
- **`set --clear <field>` is the one way to take a value away, and it is a flag with the field as its value.** Not a per-field `--clear-due`, which is a flag per field to keep in step with the field it undoes, and not an empty value, which is already a paragraph break for a section and would make an accidentally empty variable a silent delete. Repeatable, so one call empties as many fields as it likes
|
|
- **`Clearable` is a `ValueEnum` in `util.rs`**, so an unknown field is a usage error at the door listing the six that are not, and the shells complete them for free. It is also the whole table of what can be cleared: `Due`, `Tags` and `Priority` clear to a sentinel, `Description`, `Acceptance` and `Plan` to their section's placeholder. `Title` is absent because it addresses the ticket and names its file, so there is no state to go back to; `Owner`, `Status`, `Campaign` and the stamps because clearing them through `set` is exactly the second writer the missing `set --owner` exists to prevent
|
|
- **What is written is `NOT_SET` and `NONE`, the constants `add` writes.** A cleared ticket and one that was never given the field have to read the same, or clearing would be a third state that every parser then has to know about. `a_cleared_ticket_reads_like_one_filed_without_the_fields` compares the two files byte for byte, which is what keeps a new field honest
|
|
- **The placeholder goes into a section bare, via `clear_section_body`.** `set_section_body` runs its items through `Section::render`, which would write `- [ ] _No acceptance criteria provided._`. Both are `replace_section_body` underneath, so the line surgery and the trailing blank line live once
|
|
- **The pairing between a section and its `--clear` value is stored on both**, `Clearable::unset` one way and `Section::clear` the other, because the error for an empty value has to name the flag for *that* section and the section's label ("acceptance criteria") is not the flag's value ("acceptance"). `every_clearable_section_points_back_at_the_field_that_clears_it` keeps the two directions from drifting. `RELATIONS.clear` is `None`, the same rule that keeps it out of `section_args`
|
|
- **Cleared fields are reported apart from replaced ones**, as `Cleared due on '...'` beside `Updated priority on '...'`. One list would say `Updated` of a field that was emptied, which is the opposite of what a caller needs to read back. The labels are the ones `set` already prints when it *writes* the field, so the two lines name a field the same way
|
|
- **Replacing and clearing one field in a single call is refused**, by `SetArgs::contested`. clap cannot express it, because the field arrives as `--clear`'s value rather than in its name, and answering by whichever was applied last is a silent answer to a contradictory call
|
|
- **Clearing the owner is `chown --clear <ticket>`, and `--clear` carries the ticket.** Owner has one writer and clearing it cannot introduce a second, so it lives on `chown`; but the ticket is `chown`'s *second* positional, and a bare flag would land it in the user's slot for the handler to read back out, which is hand-parsing what clap can state. The typed call is identical either way. `ChownArgs::target` returns the one shape the constraints allow, and an error rather than a panic for the combination they already refuse
|
|
- **Clearing the owner writes `NOT_SET`, not the git user.** `add` falls back to the git user because it is filing something new; an owner taken away says nobody owns this, and putting the person running the command there instead hands them a ticket they were giving up
|
|
- Clearing a field that is already unset writes the sentinel that is already there, so the whole-file comparison below reports no change and nothing is written. That is not a special case, and must not become one
|
|
- No-op detection compares the whole file before and after each edit, so a field set to the value it already holds is reported unchanged and nothing is written
|
|
- `find_ticket_file()` matches on the uuid, never the title. Duplicate titles are allowed, so a title scan can land on a different ticket than the one resolved: `mv <uuid-of-second>` used to move the first ticket sharing its title
|
|
- `write_then_replace()` is the only way a ticket file is written. Content first, rename second, so a failure leaves a correct ticket under a stale name rather than a half-written one
|
|
|
|
## Checking Off a Criterion
|
|
- `check` and `uncheck` are separate commands, not one verb with a flag. They share `CheckArgs` and `cmd_check(args, checked)`
|
|
- `criteria()` is scoped to the Acceptance Criteria section and counts only checkbox lines, so a checkbox written into a description is not a criterion and a handwritten line inside the section takes no number
|
|
- `set_criteria()` splices only the character between the brackets, and takes every line in one pass. Rebuilding the line would normalise its indentation and whatever spacing followed the checkbox
|
|
- Each criterion term is the keyword `all` first, an index second, a substring third. So a criterion whose text is literally `2` is reachable only by substring, and one whose text merely contains "all" only by its number or a longer substring. `is_all_criteria()` and `is_index()` sit beside each other in `util.rs` for that reason
|
|
- **The keyword wins over the text on purpose.** Ticking every box is the reason the word is typed, and a board where `all` sometimes means one criterion and sometimes means the lot would be worse than one that can be addressed another way. `all_is_the_keyword_and_not_a_substring_of_the_text` pins it against its own fixture, so the shared one keeps its three criteria and its numbering
|
|
- **A number out of range is a bad index, not a failed substring search**, and says so. `is_index()` makes that distinction
|
|
- Any listing of a subset must keep the real numbers, via `numbered_criteria()`. Renumbering the matches from one contradicts the advice to use the number and points at the wrong criterion
|
|
- With the criterion omitted: prompt when stdin is a terminal, otherwise return the numbered list as an error. Never prompt unconditionally, the opencode wrapper has no tty and would block on a stdin that never closes. This is the same choice `resolve_ticket` makes for an ambiguous match, and for the same reason
|
|
- **The criterion positional is variadic**, so `check <ticket> 1 3 "the footer"` is one call and one write. Variadic rather than a repeated flag: the terms address criteria that are already there, the way the ticket positional does, instead of carrying content the way `--acceptance` does. The prompt path is unchanged and fires on an empty list
|
|
- **`resolve_criteria()` resolves every term before a byte is written, and one bad term refuses the whole batch.** A call that ticked the terms it understood and then failed would leave the ticket half-marked with nothing in the file to say which half was meant. It names the offending term alone rather than every failure at once, since each message carries the criteria listing and a batch of them would repeat the list per bad term
|
|
- The chosen offsets are sorted and deduped, so the report reads in `show`'s order whatever order the terms arrived in, and a criterion named twice, or by both `all` and its own number, is marked and reported once
|
|
- **Every named criterion gets a line, in `show`'s order, printed after the write.** A criterion already in the target state reads `Already checked 2: text` and does not count towards the write, so a batch where every box is already ticked writes nothing, which is the whole-file no-op rule the editing commands keep. The number is on the unchanged line too: without it a batch cannot be read back against `show`
|
|
- `show` numbers the criteria as `1. [x] text`, so the index is visible where the ticket is read. The number replaces the list marker rather than joining it
|
|
|