correctness checks, ordereddates, balance assertions

[Simon Michael]

Hey all,

here are some recent changes in master, let me know if you have concerns:

1. The order in which correctness checks are performed is now documented, and tweaked:

   commodities are now checked before accounts, and tags are now checked before ordereddates.

   (The order is relevant because we show only the first failure.)

2. ordereddates now ignores --date2 and secondary dates; it checks primary dates only

   (simplifying internals and UX).

And here are two more which have been held back, as they might be too controversial:

3. Move the balance assertions check to --strict mode (ie, don't check them by default).

4. Move the ordereddates check to --strict mode, and check it before balance assertions.

In other words, emphasise ordereddates a bit more and balance assertions a bit less.

This might be a bad idea. Some possible benefits:

- My main goal was to get ordereddates failure reported before balance assertions failure.

  When I get a failing balance assertion during data entry it's often because I copy-pasted

  an old transaction without updating the date, and it would be more useful to see the

  ordereddates error, pointing me directly at the cause.

- Moving them both to strict mode allows the checks to still be explained as a nice linear sequence,

  with the most basic/useful checks coming first.

- Also, balance assertions fairly often get in the way, forcing you to run commands again with -I.

  Eg when you want to run reports to troubleshoot problems during data entry,

  or when you are piping hledger print output to a second hledger command.

- ordereddates is IMHO a useful check with no major downsides. If you want to keep some entries

  outside the overall date order you can always move them to their own file.

  It would be ok to be a little less flexible and a little more opinionated on best practice here.

And costs:

- hledger would do less correctness checking by default. Now unless you use -s/--strict,

  you could see and use report output without realising you have failing balance assertions.

  This cuts both ways.

- The meaning of -s/--strict changes. To start using it, or keep using

  it, you'd now also need to conform to ordereddates. (Or use a

  backward compatibility flag, or use 'hledger check' instead.)

There are other ways to get some of these benefits.. though I haven't found any quite as straightforward.

[Simon Michael]

PS, the relevant docs: https://hledger.org/dev/hledger.html#check

--

You received this message because you are subscribed to the Google Groups "hledger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to hledger+u...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/hledger/f1175a8c-3495-4156-b048-ea2339d5dbd5%40app.fastmail.com.

[Peter Sagerson]

And here are two more which have been held back, as they might be too controversial:

3. Move the balance assertions check to --strict mode (ie, don't check them by default).

4. Move the ordereddates check to --strict mode, and check it before balance assertions.

In principle, the question of what does and doesn't belong in strict mode seems more like a per-journal (or per-user) one than a global one. I'm not sure if it's feasible, but I can easily imagine having each journal (or user) indicate the set of optional checks that it's committing to. Presumably with a cli override along the lines of -I.

[Simon Michael]

On Sat, Apr 27, 2024, at 04:20, Peter Sagerson wrote:

In principle, the question of what does and doesn't belong in strict mode seems more like a per-journal (or per-user) one than a global one. I'm not sure if it's feasible, but I can easily imagine having each journal (or user) indicate the set of optional checks that it's committing to. Presumably with a cli override along the lines of -I.

Certainly feasible, though more costly. I thought I had some old mockups for it but can't find them just now. TBD: would the added flexibility of having correctness checks be per-file be worth the extra variance and complexity.

[Simon Michael]

In particular I'd like to poll hledger users:

How would you feel about balance assertions being checked only in strict mode, not by default ?

How would you feel about ordereddates being added to strict mode ?

https://hledger.org/dev/hledger.html#strict-mode

https://hledger.org/dev/hledger.html#balance-assertions

https://hledger.org/dev/hledger.html#other-checks

To view this discussion on the web visit https://groups.google.com/d/msgid/hledger/a9b8aa61-6a47-44cb-b178-e1d4d574dbe7%40app.fastmail.com.

[Peter Sagerson]

On Sat, Apr 27, 2024, at 11:18 AM, Simon Michael wrote:

In particular I'd like to poll hledger users:

How would you feel about balance assertions being checked only in strict mode, not by default ?

How would you feel about ordereddates being added to strict mode ?

Either of those would be fine with me. I took this opportunity to add a precommit hook to run all relevant checks, so reorgs should have little or no impact on me now.

[Simon Michael]

Still another possibility:

How would you feel about ordereddates being added to the default checks, like assertions ? Possibly with a flag to disable it, like --ignore-assertions.

[Timofey Zakrevskiy]

Hi!

I grew fond of the previous mode - assertions on by default, dates are not ordered. 

I'll be able to modify my aliases and wrappers, of course, and I second the motion to control these checks via journal directives.

Cheers,

Timofey

сб, 27 апр. 2024 г., 21:18 Simon Michael <si...@joyful.com>:

Still another possibility:

How would you feel about ordereddates being added to the default checks, like assertions ? Possibly with a flag to disable it, like --ignore-assertions.

--
You received this message because you are subscribed to the Google Groups "hledger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hledger+u...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/hledger/15f2dec2-b6b3-48f5-b7ff-eb65186f7fdf%40app.fastmail.com.

[Dmytro Astapov]

Hi!

My two cents for the opinion poll:

On ordereddates being on by default, with an option to disable it: I am indifferent, as long as there is a way to disable this (and just this) check. Why I would disable it: because in my "manual entries" journal I group transactions into sections, and while each section is ordered by date, the whole file overall is not (and I am not keen to split it into several files, because I will have to create 5-7 small files for every year I have records for, which seems counterproductive)

On balances not being checked by default: it will not be hard for me to run "hledger check balances -f ..." every time I generate reports (assuming that "hledger check balances" will do the same set of checks that happens now to check that transactions are balanced). However, I am going to be sad overall. Why: 

a)I will now have to run "hledger check balances -f ..." for every file, which will roughly double the amount of hledger invocations I do. This can be alleviated with global or per-user config, or maybe even per-file config, assuming that "hledger print" gains an option that means "print this file with those per-file options embedded in them". So when you convert the CSV, you could immediately say that the resulting journal needs to be balance-checked. If "hledger print" can't do this, it could of course be solved with a bit of sed, but this is yet another reason to be sad - now I need to remember that sed line in all the places where CSV files are converted. 

I would prefer to "balance check" each file separately AND check the master into which they are included as well, to be able to pinpoint the place that violated the balance assertion (just like it is done now).

b)This violates the rule of least surprise in a big way, I think. If I write "= $124" in the journal, and this is called "balance assertion" by the docs, I would not expect it to be an ... aspirational note, to be checked at some point later, or not at all. I would've expected it to be enforced, in the same way "transaction is balanced" is enforced. 

You can probably tell that I am not sharing the sentiment that "balance assertions fairly often get in the way" :)

Best regards, Dmytro

--
You received this message because you are subscribed to the Google Groups "hledger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hledger+u...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/hledger/f1175a8c-3495-4156-b048-ea2339d5dbd5%40app.fastmail.com.

[Simon Michael]

Thanks for your input, all.

On Sun, Apr 28, 2024, at 02:06, Dmytro Astapov wrote:

On ordereddates being on by default, with an option to disable it: I am indifferent, as long as there is a way to disable this (and just this) check. Why I would disable it: because in my "manual entries" journal I group transactions into sections, and while each section is ordered by date, the whole file overall is not (and I am not keen to split it into several files, because I will have to create 5-7 small files for every year I have records for, which seems counterproductive)

If ordereddates moved into strict mode, it becomes a bit harder to avoid. Dmytro, do you use --strict currently ? Would ordereddates in strict mode affect you ?

On balances not being checked by default: it will not be hard for me to run "hledger check balances -f ..." every time I generate reports (assuming that "hledger check balances" will do the same set of checks that happens now to check that transactions are balanced). However, I am going to be sad overall. Why: 

hledger check assertions  - yes, that's equivalent to the the parseable / balanced transactions / assertions checks that currently happen by default.

a)I will now have to run "hledger check balances -f ..." for every file, which will roughly double the amount of hledger invocations I do.

It shouldn't require extra invocations, it would "just" require you use -s (strict mode). (Which would mean also satisfying accounts, commodities, more explicitly balanced transactions, and possibly ordereddates checks.)

This can be alleviated with global or per-user config, or maybe even per-file config,

Re per-file strictness configuration: having thought about it a little more, I think there would be complexities, and quite possibly the kind that are hard to discover in a timely manner, and I'm not going to pursue it. But if someone else wants to, I'd be glad to help test it.

b)This violates the rule of least surprise in a big way, I think. If I write "= $124" in the journal, and this is called "balance assertion" by the docs, I would not expect it to be an ... aspirational note, to be checked at some point later, or not at all. I would've expected it to be enforced, in the same way "transaction is balanced" is enforced. 

My thinking was that by default it is in forgiving edit mode, letting you get things in order, and maybe do casual reporting when you are confident in your data, but everyone would know that when you are doing serious reporting and want assurances, you turn on strict mode. I feel that would be pretty intuitive, since you add -s and get a bunch of new failures, you fix them all at once, and you feel good about strict mode.

But I know we are all used to balance assertions being on by default. And even though we have top-notch correctness checks in hledger, this change of default could look like hledger "weakening correctness checks" which isn't good.

To go back to the/my original problem, I think it's that

1. As an ordereddates user I want ordereddates checked before assertions for more useful errors
   
2. Everyone expects assertions to be always checked
   
3. Only some of us want ordereddates checked (I don't know how many, and we are biased by the designhistory) 
   
4. It's awkward to have an optional, low priority check performed before a default, high priority check.
   

The majority of responders so far don't seem too worried about any of the changes I proposed. But - unless my answers above changed your thinking - I guess it'll be the least disruptive path:  keep assertions and ordereddates checks where they are, and just add an inelegant special case so that when ordereddates are enabled they get checked early, ahead of assertions.

[Simon Michael]

On Wed, May 1, 2024, at 20:16, Simon Michael wrote:

 I guess it'll be the least disruptive path:  keep assertions and ordereddates checks where they are, and just add an inelegant special case so that when ordereddates are enabled they get checked early, ahead of assertions.

I've pushed this to master (along with some updated check docs).

TLDR: I deployed a kludge to prioritise ordereddates errors above balance assertion errors, but it shouldn't disrupt anyone; let me know if you see any issues.

[Dmytro Astapov]

I am late with this reply, but better late than never :)

On Thu, May 2, 2024 at 7:16 AM Simon Michael <si...@joyful.com> wrote:

Thanks for your input, all.

On Sun, Apr 28, 2024, at 02:06, Dmytro Astapov wrote:

On ordereddates being on by default, with an option to disable it: I am indifferent, as long as there is a way to disable this (and just this) check. Why I would disable it: because in my "manual entries" journal I group transactions into sections, and while each section is ordered by date, the whole file overall is not (and I am not keen to split it into several files, because I will have to create 5-7 small files for every year I have records for, which seems counterproductive)

If ordereddates moved into strict mode, it becomes a bit harder to avoid. Dmytro, do you use --strict currently ? Would ordereddates in strict mode affect you ?

I don't and it would not, thank you for asking.

 

On balances not being checked by default: it will not be hard for me to run "hledger check balances -f ..." every time I generate reports (assuming that "hledger check balances" will do the same set of checks that happens now to check that transactions are balanced). However, I am going to be sad overall. Why: 

hledger check assertions  - yes, that's equivalent to the the parseable / balanced transactions / assertions checks that currently happen by default.

a)I will now have to run "hledger check balances -f ..." for every file, which will roughly double the amount of hledger invocations I do.

It shouldn't require extra invocations, it would "just" require you use -s (strict mode). (Which would mean also satisfying accounts, commodities, more explicitly balanced transactions, and possibly ordereddates checks.)

I tried to use strict, but it is too strict :( I have tons of undeclared accounts, commodities only used in a couple of transactions without `commodity` declarations etc etc :(

 

This can be alleviated with global or per-user config, or maybe even per-file config,

Re per-file strictness configuration: having thought about it a little more, I think there would be complexities, and quite possibly the kind that are hard to discover in a timely manner, and I'm not going to pursue it. But if someone else wants to, I'd be glad to help test it.

b)This violates the rule of least surprise in a big way, I think. If I write "= $124" in the journal, and this is called "balance assertion" by the docs, I would not expect it to be an ... aspirational note, to be checked at some point later, or not at all. I would've expected it to be enforced, in the same way "transaction is balanced" is enforced. 

My thinking was that by default it is in forgiving edit mode, letting you get things in order, and maybe do casual reporting when you are confident in your data, but everyone would know that when you are doing serious reporting and want assurances, you turn on strict mode. I feel that would be pretty intuitive, since you add -s and get a bunch of new failures, you fix them all at once, and you feel good about strict mode.

But I know we are all used to balance assertions being on by default. And even though we have top-notch correctness checks in hledger, this change of default could look like hledger "weakening correctness checks" which isn't good.

To go back to the/my original problem, I think it's that

1. As an ordereddates user I want ordereddates checked before assertions for more useful errors
   
2. Everyone expects assertions to be always checked
   
3. Only some of us want ordereddates checked (I don't know how many, and we are biased by the designhistory) 
   
4. It's awkward to have an optional, low priority check performed before a default, high priority check.
   

The majority of responders so far don't seem too worried about any of the changes I proposed. But - unless my answers above changed your thinking - I guess it'll be the least disruptive path:  keep assertions and ordereddates checks where they are, and just add an inelegant special case so that when ordereddates are enabled they get checked early, ahead of assertions.

I think this is a great change.