Fork me on GitHub
#cljdoc
<
2021-10-14
>
rickmoynihan07:10:19

Yeah my issue here was mainly: 1. cljdoc in various places implying that it just works, with little/no-extra work. I suspect this is true for jars lein deploys in its default configuration. I’ve certainly not had any problems in the past with this. 2. Not fully understanding what metadata cljdoc relies on and where it comes from. 3. The build-clj template you get via deps-new does not create or push tags for you. 4. When cljdoc first failed I saw the v prefix which wasn’t in my hand-crafted tag; so I tried adding it, mistakenly to version in my build-clj and then saw it look for vv instead — so I incorrectly assumed it was operating on a convention, rather than relying on the :scm :tag in the pom; which I was only vaguely aware of. @seancorfield I wonder if it would be helpful to add a tag and push-tags function to build-clj, and to change the build-clj library template to include calls to them by default? i.e. to recreate something which is more like lein deploy/release out of the box?

rickmoynihan07:10:10

FWIW you can see my quick and dirty implementation of this in build-clj here: https://github.com/Swirrl/dogstatsd/blob/master/build.clj#L15-L42

martinklepsch07:10:06

Thanks for the detailed recap @rickmoynihan — makes me think that we should more prominently explain some of these things when a build failed

rickmoynihan07:10:11

@martinklepsch you’re welcome — and thanks again for cljdoc. Also improving the contrast on the rebuild button would help 🙂

😅 1
seancorfield07:10:36

Git operations are out of scope for build-clj but you can easily write them yourself using tools.build

seancorfield07:10:27

I never relied on lein to do that sort of thing and it wouldn't have occurred to me to bake it into build-clj

rickmoynihan13:10:23

@seancorfield: Given that stuff like cljdoc rely on tags being set and pushed properly as part of a deploy process, it feels like something that should perhaps be included in the deps-new library template, somehow, if not tools.build or build-clj. If you ever used lein to deploy to clojars, then it will have done this automatically unless you explicitly reconfigured :release-tasks in your project.clj

rickmoynihan14:10:14

The implementations of tag and push-tags are pretty trivial, and could easily be inlined appropriately in the template that deps-new gives you.

(defn tag [opts]
  (b/process {:command-args ["git" "tag" (str "v" (version)) "HEAD"]})
  opts)

(defn push-tags [opts]
  (b/process {:command-args ["git" "push" "--tags"]})
  opts)
Though I think it would perhaps be better for push-tags to just push the current tag.

rickmoynihan14:10:11

Without worrying too much about what the exact workflow is at this stage, I do feel that having an out of the box workflow for starting a library project and deploying it to clojars with cljdocs for free is an important one.

lread15:10:11

From the cljdoc side, yeah, a common issue is scm not being setup correctly (or at all) in the clojars pom. We could beef up our docs with some guidance on how this is commonly achieved. I think we could go over 3 options: 1. tools.build (optionally with Sean’s build wrapper) 2. leiningen 3. roll your own (we wouldn’t provide details on how here, just cover that it is an option). We could also point to working examples in the wild.

lread15:10:28

(btw, apologies to those waiting on support for https://github.com/cljdoc/cljdoc/issues/459, I once again, got distracted)

seancorfield15:10:01

In all the years I used lein for deployment, I never had it interact with git -- and I did not modify its config in that regard. I think most people still create releases in GitHub with release notes and that's how they do tagging? It's how I do releases for all my libraries and it seems to be how most libraries I use handle it, based on the GitHub release notes I see.

rickmoynihan11:10:29

I suspect you were using lein deploy and not using lein release. lein release by default, bumps version numbers and creates corresponding commits removing -SNAPSHOT etc I think the differentiator is when you want to involve CI, and other people in creating releases or not. Many simple libraries don’t really need a CI process. lein release works fine with github releases too, as you just pick the tag to create a release from.

rickmoynihan11:10:50

Anyway I’m not arguing we should have lein release; just that perhaps putting functions in the deps-new library template that create and push tags might be useful

lread15:10:42

Perhaps a bit tangental to discussion but maybe interesting?: My wee efforts are in no way representative, but I automate my release on CI (my projects have a Release job). I think that other clj-commons projects are typically doing the same (but clj-commons projects trigger release on new release tag, I think). I describe changes in my change log and not under GitHub release.

lread16:10:53

But @seancorfield, I see https://github.com/clj-commons/rewrite-clj/releases are much less informative https://github.com/seancorfield/deps-new/releases. I think I’ll attempt to automate a link to my changelog from my release description.

seancorfield16:10:16

I'm doing a snapshot tag & release on every successful CI build for some of my projects -- those don't get release notes obvs. When I make a full release, I write up the CHANGELOG first, and prep everything (update version in docs etc), push that, create a release on GH with a modified version of what's in the CHANGELOG (sometimes organizing it into sections -- docs/bugs/enhancements -- sometimes just wordsmithing), and then I pull back locally to verify the tag and no other changes, then I run the CI pipeline locally in non-snapshot mode and then do a deploy to Clojars.

lread16:10:40

I see, thanks for the info!

seancorfield17:10:33

Yeah, it's all the doc updates that I prefer to do manually for all sorts of reasons.

lread17:10:28

Sure, chacun a son gout!

🙂 1