What strategic steps can be used to clean-up the API

[Anton-Latukha]

HNix modules expose everything, what is used, and what is not used.

That means that any meaningful work, any minimal function refactoring constantly resolves into interface changes, which means major versions, which means constantly twitch every project downstream.

Also, the big interface means there is more possibilities to pull the rug from some downstream project unknowingly.

It would've been great if the interfaces would be formed by the internal project use and by the demand of the downstream, move everything possible into local functions, and open interfaces needed.

Until HNix is not widely used - it probably should adopt some other approach to interfaces.

What can we do to manage the interface better, to keep it concise and useful?

[Ericson2314]

I think monorepo + split package could help in conjunction, because then people that only need one part are not affected by breaking changes in other parts.

[Anton-Latukha]

What I can do:

1. I can take all reverse dependencies, and build them in CI. In that way during any work we would see what downstream projects are using - that would distinguish what is really used from what project exposed vacuously.

2. Project can post a request to open reports on opening particular parts of interfaces, since extending interface is a minor release - we can ship the opening of the interface fast, without notifying everyone.

[Anton-Latukha]

We have a big API.
For the release and to respect people that use HNix - the changelog needs to be populated first-class. Putting in the short human form the cliffnotes to guide fellows what happened from what they may need to be guided for to update to new HNix. Project is complex, so on top of mentioning changes - people really need an explanations. There is a big list of changes to be parsed and simply explained in the changelog. It is late and I would not finish it today.
If our API is as big and open - we would need to do this guidance all the time for every function we add, and for any function type change - that is additionally also a major release breakage level. Since almost all of them are made public - so we must support what we provide and promise to support to the public.
That is also why I want for us to do an API clean at some point. We need to expose only what downstream needs, and put a disclaimer that if something is additionally needed - for people to open reports or PRs opening it, and issuing those minor releases fast. That is good to do before the abstraction into several smaller packages, so we know what API is used and guide and automation for the migration to several packages made easier.
The changelog effort and a number of breaking major releases are linear to the API size of the project.

#554 (comment)

So this is logical to do before the #778.
Because otherwise: we would have a big API to untangle and split, and then we would need to write a huge map of API migrations, and then since it is possible to semi-automate migration for people - that automation would be more complex to do and then it would probably not happen.
Also I imagine after big migration of modules and split of everything into separate abstractions - if we would do API clean after that - people would be mad - they just made effort to do a huge migration and now after they were loyal and support us - we are blocking the API they just migrated to and use.

So for that to not happen and so the happens the easy right way:

• Make Please, make a CI automation that tests the reverse dependencies #790.
• Then we close this report by publishing the major release that has the API that our reverse-dependencies use. And in the changelog we ask people to request other needed openings from us, and promise to ship them in minor release right after the request. And so to support new release - people would write asking/send openings they need to us, we publish a bunch of minor releases, and in that move stabilize the API. Remember that prior to that we would check what Hackage projects are using from us - so we would probably get a pretty minor number of requests from some {closed, not on Hackage} projects - which may be only a few, if there are any at all.
• Then we have minimal API next steps and Unix philosophy package split becomes much easier for us and for downstream to follow.
• In one jump make the Please, refactor the module grouping #778, documentation of it and automation of migration for downstream, and the package split happens - all in one release. Since the API is smaller and we cleaned-it us - the split is easier and also we can provide a map and automation for people to rename Hierarchical Module Names in their source code, so they would only need to update their .cabal configs.