Do we love scripts in ./bin or do we hate them? (hledger-balance-as-budget breakage)

[adept]

Hi!

I've noticed that scripts in ./bin become broken regularly (if we want a concrete example, commit
80cf1d1 removed combineBudgetAndActual, that two scripts depend on, and I happen to use and love them.

I also think that those same scripts are not built by CI pipeline (which would explain how breakage occurs, and goes unnoticed).

At the same time, the existence of scripts is mentioned in docs, and some, i think, even get an explicit shout-out by name.

@simonmichael , what's the best long-term plan?

• Shoud scripts be built in CI pipeline?
• Or should they be declared best-effor only, and removed on breakage?
• Should the removal of API endpoints be frowned upon if scripts depend on them, or endorsed?
• Something else, like maybe encouraging to quickly convert scripts into hledger command, even at the risk of proliferation of niche narrow-scope commands as a result?

My current issue is that 80cf1d1 is quite a large commit, and it wont be a "swap this API call for that API call kind of fix" (at a first glance). This feels sad.

[simonmichael]

Hi @adept, excellent questions..

Sorry for breaking a tool that you use. I occasionally use one or two of these myself, but not often, and I'll often be using a compiled binary so might not notice a build failure at that time. And feedback about them is rare, so I don't think of them often.

I do usually remember to do a test build of the bin scripts when doing big changes, and I search them when renaming/removing things.
It's unusual that something needed was just dropped without us noticing. Yes we should prevent this.
And we should bring back that bit of code. Perhaps it would be better to put it in the script that uses it.

Here's the list of things in bin/. It contains

• examples - to give people ideas and templates for building their own.
  Some of these are not very useful or even working, but still provide example code and ideas.

• tools - kept outside the main executable for some reason, such as lack of
  general usefulness or lack of maintainers/advocates.

So in short I usually handle the bin scripts like your option 2 - best effort, remove or comment if not working.
I'm hesitant to give them tier 1 designation if they don't justify that effort.
One of the goals of bin/ was to be an overflow/extra area where we can put stuff that's interesting though not industrial strength.
And to reduce my workload / scope of attention.

Does someone want to be responsible for bin/ and give it more oversight ? That would help.

cc @Xitian9

[simonmichael]

API change policy is another issue TBD. At the moment we provide no guarantees; I just try to mention most changes and especially breaking ones in release notes, and avoid gratuitous breakage. The usage level of our APIs hasn't required more effort so far, but improvements/clarifications here are welcome if not too costly. APIs include

• the hledger-lib, hledger, hledger-ui and hledger-web haskell library APIs
• hledger-web's JSON API, which has a openapi spec linked in the manual. Also the CLI's JSON output which follows the same schema.
• the command line interface, which I change very carefully

[simonmichael]

(I do see that if we want to encourage the building and use of scripts and custom tools, we need to provide a dependable api for them or at least rapid fixes.)