Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify/describe philosophy of Contrib libraries #348

Closed
seancorfield opened this issue Jan 23, 2019 · 13 comments

Comments

Projects
None yet
4 participants
@seancorfield
Copy link
Member

commented Jan 23, 2019

At this point, some Contrib libraries are core to Clojure itself (spec, tools.deps, clj/brew), some are just continuations of what used to be in "Monolithic Contrib". Some are well-maintained, some do not have an active maintainer at the moment. tools.nrepl has forked out of Contrib (and it's not entirely clear what should happen with the version that is still in Contrib). I'm currently designing "next.jdbc" as the next generation of what java.jdbc currently is (one of the ones that continued from "Monolithic Contrib") and I haven't decided yet whether to add this to java.jdbc within Contrib or create it as a general community library.

When the status of Contrib has been raised in the past, the clear message from the core team is that "Contrib is not a 'Clojure Standard Library'" but, given the development process (CLA, JIRA, patches), Contrib is not a "typical" community project.

Some Contrib libraries are very widely used, others are niche. Some offer functionality that is better-served by a popular community library (data.json vs Cheshire comes to mind).

Now that Clojure/core is splitting out features into Contrib -- and those features need to be tightly controlled by the core team -- Contrib seems to be even more of a mixed bag of philosophies.

It would be very helpful -- for Contrib maintainers, and for the broader community -- if there was a clear statement of what it means for a library to be part of the clojure organization, part of Contrib. Perhaps even a re-evaluation of whether some of those projects should even be under that core organization at this point?

@bbatsov

This comment has been minimized.

Copy link
Contributor

commented Feb 4, 2019

I think you’re making a wonderful point!

I have often been thinking about the purpose of Contrib and I guess my thoughts can be summarized like this:

  • originally people hoped that contrib libraries might get promoted to Clojure core (I know for a fact this was the only reason why nREPL joined Contrib in the first place), but as no library never got promoted to Clojure Core this is certainly not the case. Even if this was the original intention I guess it’s no longer the current plan.
  • Most people still believe that Contrib exists for the sake of incubating stuff that might end up in Clojure Core one day (based on numerous conversations I’ve had with Clojurists).
  • All libraries stewarded directly by Rich and Cognitect (e.g. core.async) are somewhat special, so they probably deserve a special status (they are clearly not Contrib libraries after all). Perhaps the notion of contrib can be replaced with a notion of Extended Core (for such libraries) + Contrib (for libs that might potentially make it to core some day - perhaps tools.reader or something like it). Naming is hard, so I’m certain someone can up with better names for those.
  • Some clear goals should be set for Contrib (or whatever succeeds it), so the confusion around it can be put to rest. I’d certainly highlight again that Contrib is not a Standard Library and not some incubator for projects to be promoted, but on the other hand I can’t think of what exactly would be the purpose of such an initiative then.
  • Depending on the goals many of the libraries currently in Contrib can be released from its restrictions (ideally retaining their deployment artifacts for the sake of backwards compatibility).

Generally I think that unless something is special to Clojure (e.g. spec, clojure-tools, reps, etc) it probably should be a normal community library. Everyone has noticed by now the massive surge that nREPL got from leaving Contrib, and I think this speaks volumes. Btw, on the subject of the old tools.nrepl - as it’s never going to see any work again (all projects that were using it have already switched to the new nREPL) I’d suggest simply archiving the repository.

If it were me I’d probably kill Clojure Contrib altother and replace it with something else (organizationally speaking). That’s the best way to send a clear message that something has changed and the new goals are X, Y, and Z. Anyways, ultimately the most important things are to ensure clarity and the remove obstacles to contributions to projects that need them. I’ll leave the exact recipe for achieving this to @stuarthalloway, @puredanger and co.

@puredanger

This comment has been minimized.

Copy link
Contributor

commented Feb 4, 2019

I've added a new page https://clojure.org/community/contrib_libs and reworked some parts of https://clojure.org/api/api and https://clojure.org/community/libraries. The new page outlines what contrib is (a collection of libs that share a development model) and tries to clarify some of the history.

I think generally too much is made of contrib. It's just a collection of libs with a shared dev model. That's no different than clj-commons or ClojureWerkz. They all have different approaches but each has its own view of how to setup and manage projects.

There is no need to kill, archive, or "release" libs. They've been contributed, their artifacts exist. If someone is well served by the existing release, they should use it. Contrib READMEs should clearly state their status (I'm sure improvements could be made). Users should evaluate the status of each lib and whether it's a good fit for their use, exactly as they would evaluate any other open source. If the current owner has stopped working on it, we're always happy to have someone take it over.

There is no "goal" for contrib beyond providing infrastructure for lib dev. It's just a bunch of libs with a shared dev model.

I'm going to close this ticket now as I think I've achieved the intent. If there are small things in the delta to fix, feel free to comment here though and I'll update. If there are big things, you can file a new issue.

@puredanger puredanger closed this Feb 4, 2019

@seancorfield

This comment has been minimized.

Copy link
Member Author

commented Feb 5, 2019

"Builds - Maven with deployment to Maven Central under the groupId clojure.org" -> "... org.clojure

I think that new page accurately describes the current state of the Contrib Libraries. I still think we need discussions around the state/future of individual Contrib Libraries, however. I'd hoped this issue would be a starting point for that discussion :(

@seancorfield

This comment has been minimized.

Copy link
Member Author

commented Feb 5, 2019

I will add that the new page does, at least, delineate between Contrib Libraries, Core Libraries, and Infrastructure/Not-a-Library within the clojure organization so that is definitely "progress" so, thank you for that!

@seancorfield

This comment has been minimized.

Copy link
Member Author

commented Feb 5, 2019

Stuart's blog post (from 2012) links to https://dev.clojure.org/display/community/Contrib+1.0.0+Releases -- is this still considered valid guidance? I've had mixed responses when I've raised this issue (several times over the last few years).

@puredanger

This comment has been minimized.

Copy link
Contributor

commented Feb 5, 2019

What’s the question to answer on individual libs? Pretty much every lib is it’s own case, hard to talk generically.

Re contrib 1.0.0, no I don’t think it’s valid anymore. I trust a lib owner to make that decision.

@seancorfield

This comment has been minimized.

Copy link
Member Author

commented Feb 5, 2019

Re: 1.0.0, I added a clarifying note on that wiki page (pointing back to this issue).

What’s the question to answer on individual libs? Pretty much every lib is it’s own case, hard to talk generically.

Well, I guess that answers that too then (but not in the way I had hoped).

@puredanger

This comment has been minimized.

Copy link
Contributor

commented Feb 5, 2019

I think we could definitely signpost lib readmes better on many of the libs.

@puredanger

This comment has been minimized.

Copy link
Contributor

commented Feb 5, 2019

Turned that list into a table with owners and status.

@seancorfield

This comment has been minimized.

Copy link
Member Author

commented Feb 5, 2019

Perfect! Thank you, @puredanger -- that's a wonderful clarification of the status of Contrib Libraries!

@bbatsov

This comment has been minimized.

Copy link
Contributor

commented Feb 8, 2019

Great job with the updated documentation! I think that’s exactly what was needed - now we just have to promote the page a bit when questions about contrib arise.

One small thing that I think is missing is the “Why?” Of all of this - e.g. why would someone decide to develop a library under contrib. It’d be nice if this was covered somewhere, as it’s certainly puzzling for me.

There is no need to kill, archive, or "release" libs. They've been contributed, their artifacts exist. If someone is well served by the existing release, they should use it. Contrib READMEs should clearly state their status (I'm sure improvements could be made). Users should evaluate the status of each lib and whether it's a good fit for their use, exactly as they would evaluate any other open source. If the current owner has stopped working on it, we're always happy to have someone take it over.

Fair enough. I think there’s nothing wrong with archiving dead projects, as that sends a very clear message about their status and doesn’t affect the existing artifacts at all. Of course, better READMES go a long way as well. As for killing/releasing stuff - I was mostly referring to the unclear negative impact for the existing projects, that the current arrangement might be having. You made a comparison with clj-commons, but they are not really imposing any restrictions in terms of contributions and infrastructure. One the other hand - Clojure Contrib has historically been criticized mostly in this regard. That’s why I brought up the topic of the rationale for all of this - doing something just for the sake of doing it always struck me as weird.

Of course, there’s no way to prove the current arrangement is really harmful, so I’ll leave it at that. Once again - thanks for the great update! Things are now much better than they were and I guess that’s the most important thing at the end of the day.

@seancorfield

This comment has been minimized.

Copy link
Member Author

commented Feb 8, 2019

My feeling is, at this point, I would expect it to be very unlikely for anyone outside Clojure/core to create a new Contrib library. And I think that's just fine.

Contrib defnitely makes sense for "Clojure Core Libraries", and as a place for existing Contrib libraries to continue being maintained, if the maintainers so desire, but I think it has served the purpose(s) it was originally conceived for at this point.

The new pages cover this history pretty well, I think, and if anyone has a burning desire to create a new library in Contrib -- perhaps because they hold hopes it might be incorporated into Clojure or its Core libraries -- then that's a decision they can make, based on all the information (now) available.

Contrib library maintainers can individually make the decision on whether to continue maintaining a library in Contrib or fork it out of Contrib (as clojure.tools.nrepl did) and it's pretty clear what they're giving up: the group ID and the Jenkins/Maven test and deployment pipeline -- and the visibility/governance of the clojure organization. They can pick a new group ID, set up Travis/CircleCI, and deploy to Clojars instead -- and make their project visible however they want (and govern it however they want).

@stuarthalloway

This comment has been minimized.

Copy link
Member

commented Feb 8, 2019

The top 5 reasons to create a contrib are:

  • common CA
  • common CA
  • common CA
  • common CA
  • common CA
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.