(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
+21
-7
@@ -124,21 +124,34 @@ worklane add \
|
||||
Editing afterwards, on a ticket in any status:
|
||||
|
||||
```
|
||||
worklane set 1b78a24 --priority 1 # replace a field
|
||||
worklane set 1b78a24 --priority 1 # replace a field
|
||||
worklane set 1b78a24 --title "A better title" # renames the file, keeps the uuid
|
||||
worklane set 1b78a24 --clear due # take a value away again
|
||||
worklane set 1b78a24 --clear tags --clear plan # as many fields as you like
|
||||
worklane append 1b78a24 --acceptance "One more criterion"
|
||||
worklane append 1b78a24 --description "What was learned since."
|
||||
worklane chown alice 1b78a24 # hand the ticket to someone
|
||||
worklane chown --clear 1b78a24 # hand it back to nobody
|
||||
```
|
||||
|
||||
`set` replaces, `append` adds. Neither has `--owner` or `--status`: owner is `chown`'s
|
||||
and status is `mv`'s, so each field has exactly one writer. A field set to the value it
|
||||
already holds is reported unchanged and nothing is written.
|
||||
`set` replaces, `append` adds, `--clear` empties. Neither `set` nor `append` has
|
||||
`--owner` or `--status`: owner is `chown`'s and status is `mv`'s, so each field has
|
||||
exactly one writer. A field set to the value it already holds is reported unchanged and
|
||||
nothing is written, and so is a field cleared that was already unset.
|
||||
|
||||
**`--clear` takes the field as its value**, one of `due`, `tags`, `priority`,
|
||||
`description`, `acceptance` or `plan`, and repeats. It writes back exactly what `add`
|
||||
writes for a field it was never given: `_Not set_`, `_None_` for tags, and the section
|
||||
placeholder. There is no `--clear title`, because a title addresses the ticket and names
|
||||
its file. There is no `--clear owner` either: that is `chown --clear <ticket>`, which
|
||||
takes the ticket in the flag since there is no user to give, and returns the field to
|
||||
unset rather than to the git user. Replacing and clearing the same field in one call is
|
||||
refused rather than resolved.
|
||||
|
||||
`chown` takes the **user first and the ticket second**, after Unix `chown`, which is the
|
||||
one command here that does not start with the ticket. The user is free text and is
|
||||
checked against nothing. Swap the two and the call fails, because the username has to
|
||||
resolve as a ticket.
|
||||
resolve as a ticket. `--clear` replaces both arguments with the ticket alone.
|
||||
|
||||
`worklane init` creates `.worklane/` with the four status directories and the campaigns
|
||||
directory beside them, for a repo that has no board yet.
|
||||
@@ -261,6 +274,7 @@ the candidates and exits 1 rather than guessing.
|
||||
`worklane mv --status committed -- -leading-title`.
|
||||
- A comment body of exactly `--` needs its own separator:
|
||||
`worklane comment 1b78a24 -- --`.
|
||||
- An empty value for a scalar is a usage error. Clearing a field back to unset is not
|
||||
supported yet.
|
||||
- An empty value for a scalar is a usage error, not a way to clear the field: use
|
||||
`--clear`. For a section an empty value is a paragraph break, so it cannot mean empty
|
||||
the section either, and an all-blank one is refused with the `--clear` for it named.
|
||||
- Piping is safe: `worklane ls | head -3` exits on the closed pipe instead of panicking.
|
||||
|
||||
Reference in New Issue
Block a user