Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
HEP: clarify status field functionality, UI, docs #564
The status field has been causing some confusion, and we have been brainstorming ways to improve its docs, querying UI, implementation etc. See related discussion links below. It seems that something should be done, but what ? Add more features ? Rework the internals ? Adopt new terminology ? Clarify the docs ? Accept things as they are and stop making a fuss ?
Here's the proposal I currently favour, being drafted in HEP format for more deliberation.
What is being proposed, in one sentence ?
Stop matching pending with --uncleared, add -P for --pending, and allow -U/-P/-C to be combined, making our existing UI more expressive, consistent and intuitive, at the cost of a small incompatibility and slightly more complex behaviour.
What real problem is being solved ?
Empirically, it's confusing to learn and teach how the status field works, what the status characters mean, how to filter precisely based on status, for at least some users.
Some ways of using the status field are inconvenient. Eg including only pending things in hledger-ui, or excluding pending things in the CLI (you must switch to using a status: query argument). The
Discussing, documenting and implementing these things takes too much time and effort, because of unclear (sic) terminology, in particular the difference between uncleared (unmarked) status and --uncleared ("not cleared") flag.
What is the proposed UI and help, if applicable ?
This proposal bundles several related changes, most important first. 4, 5, and 6 are the most optional:
What is a rough draft of the reference documentation, or other details ?
How will this interact with existing features and systems ?
When users and command examples move between Ledger/hledger 1.2- and hledger 1.3+, -U should be translated to and from -UP. This might affect only users of pending status, and only in some cases.
hledger and hledger-ui are discussed in this proposal, but not hledger-web, hledger-api, or other addons. These should pick up the new flags from hledger-lib in their next release, and otherwise shouldn't be much affected.
How will we test or ensure this remains effective ?
Functional tests: tests/journal/status.test, tests/misc/query-status.test.
What is in and out of scope ?
The changes listed above. Bugs will be fixed separately.
What is an estimate of developer hours required ?
Which of our current Projects does this relate to ?