11 KiB
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
setreplaces a field,appendadds to a section. The verb carries the meaning, so no flag needs a replace-or-append prefix, andappendonly offers the sections that hold multiple lines- One field, one writer.
sethas no--owner(that ischown's) and no--status(that ismv's), and neitheradd,set,appendnorchowncan reach the three status stamps, whichmvwrites as a side effect of the move. Do not add any of them chowntakes the user first and the ticket second, after Unixchown, 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 toresolve_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 usernamecmd_chownisset_metadata_fieldplussave_ticket, with the same whole-file no-op comparisonsetuses and the samereport()output, so nothing about writing a field lives twiceapply()is the one place an edit is taken or dropped, shared byset'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 placeholderaddwrites when empty, aSectionKindand the--clearvalue 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
## Notessection 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_emptyandclearableincommand.rs. Neither spells clearing, and both errors name the flag that does - A call whose values are every one blank is refused, by
replaced_itemsforsetandappended_itemsforappend. The check is the section's rather than the object's, socampaign set --descriptionshares it. What differs is the way out, which is whyreplaced_itemstakes 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 likesClearableis aValueEnuminutil.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,TagsandPriorityclear to a sentinel,Description,AcceptanceandPlanto their section's placeholder.Titleis absent because it addresses the ticket and names its file, so there is no state to go back to;Owner,Status,Campaignand the stamps because clearing them throughsetis exactly the second writer the missingset --ownerexists to prevent- What is written is
NOT_SETandNONE, the constantsaddwrites. 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_fieldscompares 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_bodyruns its items throughSection::render, which would write- [ ] _No acceptance criteria provided._. Both arereplace_section_bodyunderneath, so the line surgery and the trailing blank line live once - The pairing between a section and its
--clearvalue is stored on both,Clearable::unsetone way andSection::clearthe 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_itkeeps the two directions from drifting.RELATIONS.clearisNone, the same rule that keeps it out ofsection_args - Cleared fields are reported apart from replaced ones, as
Cleared due on '...'besideUpdated priority on '...'. One list would sayUpdatedof a field that was emptied, which is the opposite of what a caller needs to read back. The labels are the onessetalready 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--clearcarries the ticket. Owner has one writer and clearing it cannot introduce a second, so it lives onchown; but the ticket ischown'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::targetreturns 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.addfalls 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 titlewrite_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
checkanduncheckare separate commands, not one verb with a flag. They shareCheckArgsandcmd_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 numberset_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
allfirst, an index second, a substring third. So a criterion whose text is literally2is reachable only by substring, and one whose text merely contains "all" only by its number or a longer substring.is_all_criteria()andis_index()sit beside each other inutil.rsfor that reason - The keyword wins over the text on purpose. Ticking every box is the reason the word is typed, and a board where
allsometimes 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_textpins 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_ticketmakes 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--acceptancedoes. 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 bothalland 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 readsAlready checked 2: textand 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 againstshow shownumbers the criteria as1. [x] text, so the index is visible where the ticket is read. The number replaces the list marker rather than joining it