Files
worklane/docs/editing-tickets.md

11 KiB

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