Clojurians Log v2

Hiya @tengstrand! If I understand correctly a separate cljdoc badge that shows the latest SNAPSHOT release might be what you are looking for? So you'd show two badges, one for latest non-SNAPSHOT, and one for latest SNAPSHOT (and you'd probably do the same for clojars badges)? Will your CI build release a SNAPSHOT release to clojars for each commit to your main branch? One thing to note is that cljdoc does not automatically build SNAPSHOT releases, so you'd probably want your CI workflow trigger a SNAPSHOT build on cljdoc. And I'm sure you know this, but worth mentioning... a downside of SNAPSHOT releases is that if you release multiple times under a single SNAPSHOT version it can sometimes be a bit confusing to know exactly which SNAPSHOT a user is having an issue with.

And to clarify, CURRENT when viewing docs on cljdoc = version our are currently viewing. When coming from outside cljdoc it defaults to the most recent non-SNAPSHOT release. https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc#use-full-api-urls-from-articles.

Okay, I will try to reformulate the ide. If I post a link to a page of the clj-poly documentation in e.g. Slack, I can use CURRENT to link to the latest 0.2.17-alpha release today. If I want to link to the latest SNAPSHOT release, it would be nice if I could use e.g., SNAPSHOT instead. If I e.g. use CURRENT-OR-SNAPSHOT then it should refer to 0.2.17-alpha if that is the latest release, or 0.2.18-SNAPSHOT if a more recent snapshot release exists. I read that I have to trigger SNAPSHOT releases, so I need to update my CI build, but thanks for pointing out. I think it will work fine to let the latest cljdoc documentation reflect what is in the master branch. They are just temporary releases, and not all users will use them anyway, only users that want to use the absolute latest (which is good, because then things will be tested properly). My plan is to release more often than today. I haven't decided yet if I need to put any of the badges on the page (CURRENT/SNAPSHOT) and maybe I will just skip them. I'm not sure of the use case of them. If I have opened a SNAPSHOT version of the documentation, then of course it could take me to the latest released version (CURRENT) but that is probably not something I want to do very often. And the other way around, if I have opened the CURRENT version of the documentation, a badge to the SNAPSHOT version may take me to an older version, if no SNAPSHOT version has been released yet, which is probably not what we want (it will have some value if there is a newer SNAPSHOT version available).

If you are linking from a message on slack, you are probably talking about a specific release. So you can be specific for this use case: A future snapshot link might be: https://cljdoc.org/d/polylith/clj-poly/0.2.18-SNAPSHOT > I haven't decided yet if I need to put any of the badges on the page (CURRENT/SNAPSHOT) and maybe I will just skip them. I'm not sure of the use case of them Right, I made an assumption that you were using badges. Library authors typically use badges to allow their users a familiar way to navigate to the docs (from github) for the current supported stable release. But maybe clj-poly is a bit different as it is maybe more of a tool than a library? If I understand things, you probably would not have a clojars badge because clj-poly is not typically used as a library. I assumed you wanted to offer 2 separate links from your README 1. latest stable release docs 2. latest snapshot release docs And I assumed you wanted to use badges for these. But, I think your use case might be different than I assumed. So without proposing a solution, can you tell me more about the problem you are trying to solve?

Hmm, I think you are right, separate links to specific SNAPSHOT or CURRENT versions would be enough! And yes, for users that come from GitHub, the badges could be useful, especially for users that are used with cljdoc documentation (I also have an explicit link on the starting readme.adoc page) which means that I now think it's a good idea to include them! Some of the poly tool functionality will be accessible in the clj-poly library, so it's also a library, even though the documentation is mostly about the poly command line tool.

Ok, cool! I do think I remember somebody else asking for a similar feature once... maybe. I think what folks typically do today is: read docs on the stable release on cljdoc. Read docs on the snapshot release on github HEAD. Maybe. Dunno really. I do think a new latest snapshot badge might help/encourage folks find/fix more issues in docs for snapshot releases. So I think the idea is interesting. But just to gauge your interest: Given the fact that a change has to be maintained/tested forever, how important is this feature to you?

You mean the extra SNAPSHOT badge? Not important! A lot of conversation for "nothing"! 🙂 But avoiding unnecessary functionality is also a win!

Ha! Ok, well I am happy we explored this!