What is the public API? about clj-yaml HOT 7 CLOSED

Be clear about our public API but through :no-doc meta only.

If we would mark those with no-doc we could give ourselves the permission to break those in future releases since we assume nobody relies on those, which isn't a good assumption since there are counter-examples from the wild, yes?

from clj-yaml.

Yes, Option 2 is a softer doc-only version of Option 3 which is, potentially (depending on what we decide is public) a deliberate clj-yaml user breaking change. A very un-clojury thing to do. If only we could rewrite history, eh?

We could do a thorough search and make our public API everything we see being used in the visible wild. Private repos could still be affected. I took this approach for etaoin which also did not distinguish public from internal.
This would include trying to adapt our recent decode change to be an unbreaking change.

Option 1 would be the safest bet for clj-yaml users but leaves us with maybe a bit of an odd public API. And one that is more challenging to support. But at least we'd have an understanding that we shouldn't break it.

from clj-yaml.

I pondered option 4 - deprecate clj-yaml and create clj-yaml2 (if the burden of other options is not palatable). But I think that's not a very good option for babashka, which has clj-yaml baked in.

from clj-yaml.

Maybe Option 1 is the way to go? It's not like its a huge API, for gosh sakes.

from clj-yaml.

Yeah, gonna assume Option 1, pipe in if you have other strong opinions, but please do so soon because I am proceeding.

from clj-yaml.

I would say option 1 but going forward: be very strict about what to expose.

from clj-yaml.

Agreed

from clj-yaml.