(74904dc) Let a ticket field be cleared back to unset, and bump to 0.18.0
`set --clear <field>` is the one way to take a value away, repeatable, with the field as a `ValueEnum` value: an unknown one is a usage error listing the six that are not, and the shells complete them for free. Not a per-field `--clear-due`, which is a flag per field to keep in step with the one 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. What goes back is what `add` writes for a field it was never given, through the new `NOT_SET` and `NONE` constants and each section's placeholder, so a cleared ticket and one filed without the field read the same. Sections are in scope and go back through `clear_section_body` rather than `set_section_body`: the latter runs its items through `Section::render`, which would have written `- [ ] _No acceptance criteria provided._`. Owner is `chown --clear <ticket>`, so the field keeps its one writer. The flag carries the ticket because 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. It writes `_Not set_` rather than the git user: `add` falls back to the git user because it is filing something new, and an owner taken away says nobody owns this. The empty-value error split in two rather than being reworded. `non_empty` says only that the value cannot be empty, for the arguments with no empty form; `clearable` names `--clear`, for the arguments whose field has one. One message for both would have lied about `ls --tag`. Replacing and clearing one field in a single call is refused rather than resolved by whichever was applied last, and cleared fields are reported as `Cleared due on '...'` beside `Updated priority on '...'`, since one list would say `Updated` of a field that was emptied. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5
parent
175c1d016d
commit
cc5f9b8a46
@@ -59,7 +59,8 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **`--due` is validated at parse time by `iso_date`, the way `--priority` is by `priority_level`.** A date that is not real is a usage error, exit 2, with nothing written, which is the whole point of leaving the scalars without `PROSE`. One parser serves `add` and `set`: the field has one definition of what it accepts, and validating only `add` would leave `set` open, which is the command a grooming sweep actually uses
|
||||
- **The shape is checked before chrono is asked.** `%Y-%m-%d` accepts an unpadded `2026-8-9`, which would be stored exactly as typed and sort before `2026-10-01` in any string comparison. Checking the length and the two dashes first is what lets a valid date be stored unchanged instead of normalised on the way in, which is the difference between validating and rewriting
|
||||
- **Strict on the way in, tolerant on the way out.** `util::due_date` still cuts `2026-12-31T09:30:00Z` down to its date. A file written before the parser existed, or by hand, can hold one and still has to render; refusing to display what is already stored would punish the reader for the writer's mistake
|
||||
- An empty `--due` keeps `non_empty`'s message about clearing rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is that clearing is not supported yet
|
||||
- An empty `--due` keeps the clearing message rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is the flag that does it
|
||||
- **There are two empty-value parsers, and which one an argument takes is the point.** `non_empty` says only that the value cannot be empty, for the arguments with no empty form: the `ls` filters, `relate`'s targets, and `set --title`, which addresses the ticket and names its file. `clearable` names `--clear`, for the arguments whose field does have one: `set --tags`, `--due` through `iso_date`, and the `chown` user. One message for both would either lie about `ls --tag` or leave the useful half unsaid. `add --due` takes the second one because `iso_date` is shared, and the answer it points at is a command later rather than the omission that would do it now, which is close enough to be worth the shared parser
|
||||
- **A status is a `util::Status`, not a string.** `mv --status` and the `ls` positional take the value enum, so an unknown status is a usage error at parse time naming the four, exit 2, and no handler checks. That is the same bargain `--due` and `--priority` take, and it is what lets the shells complete the four for free. `Status::ALL` is the flow order, which `status_dirs()` and `cmd_mv` both read rather than spelling the names again, and `DONE` is defined from it
|
||||
- The ticket positionals (`show <id>`, `mv <ticket>`, `comment <ticket>`) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with `--`, as in `mv --status committed -- -leading-title`
|
||||
- A bare `--` is a value when it follows an option (`--title -- ` stores `--`) and clap's end-of-options marker when it sits in a positional. So a `comment` body of exactly `--` needs its own separator, `comment <ticket> -- --`. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop
|
||||
@@ -90,11 +91,24 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **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
|
||||
- Sections are a table in `util.rs`: `DESCRIPTION`, `ACCEPTANCE`, `PLAN`, each with a heading, a label, the placeholder `add` writes when empty, and a `SectionKind`. Adding a section later is one entry, not edits in both commands
|
||||
- `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` in `command.rs`. Clearing a field is not supported yet, and the error says so rather than guessing
|
||||
- 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
|
||||
|
||||
### 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
|
||||
@@ -322,7 +336,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- The UUID tier applies from `MIN_ID_SEARCH` (4) characters up. Not 8: `ls` prints `SHORT_ID_WIDTH` (7) characters, so a longer minimum would drop the printed id out of the UUID tier and let any title quoting it win instead. Below the minimum the search is text, so `show 641` is a title search
|
||||
- The filename tier earns its place by reaching the middle of a UUID, which the prefix tier cannot. It is also why a short UUID search still resolves under a longer minimum, just at the wrong precedence, so a test for the minimum needs a decoy title to be meaningful
|
||||
- Ambiguous matches (multiple results) print options and exit(1)
|
||||
- Never return empty strings for required fields — use `_Not set_` or `_None_` as defaults
|
||||
- Never return empty strings for required fields — use the `NOT_SET` and `NONE` constants in `util.rs`, which are what `add` writes and what `--clear` puts back. `is_unknown_value` reads both, plus the two hyphenated spellings an earlier version wrote
|
||||
|
||||
### Git Workflow
|
||||
- Commit format: `([ticketID]) [short description]`
|
||||
|
||||
Reference in New Issue
Block a user