Is contributing to clojurescript is intentionally made hard ?

[Irakli Gozalishvili]

I have being trying to engage community and to contribute to clojurescript for a while already,

but so far it's being mostly frustrating and difficult. I hope to start discussion here and maybe

get some constructive outcome.

## Rationale

I'm primarily interested in clojurescript and not at all in clojure, because of specific reasons (that

I'll skip since their irrelevant for this discussion) dependency on JVM is a problem. Removing

that's dependency is also my primary motivation to contribute. 

## Problems

- I do understand that most of the clojurescript audience is probably also interested in clojure,

  but please don't enforce that. Have a separate mailing list so that people interested in

  clojurescript and not clojure could follow relevant discussions without manually filtering out

  threads.

- What is the point of being on github if you don't accept pull requests and require I do understand

  that there maybe specific reasons why jira flow was chosen, but seriously that's another ball

  thrown at potential contributor to joggle. Not to mention that there are several options how

  jira and github could be integrated.

- My latest attempt was to configure travis.ci for integration tests
  https://github.com/clojure/clojurescript/pull/21
  

   Integration tests are great specially because they run on every pull request and post details back

   into pull requests. This also means that lot of local test run time can be saved. Not to mention that

   for clojurescript tests you need JVM, v8, spidermonkey and more…

If these things are intentionally made hard to stop new people with more clojurescipt interests then please

make it more clear, cause otherwise it just a motivation killer. 

Thanks

--
Irakli Gozalishvili
Web: http://www.jeditoolkit.com/

[Phil Hagelberg]

Irakli Gozalishvili writes:

> - I do understand that most of the clojurescript audience is probably
> also interested in clojure, but please don't enforce that. Have a
> separate mailing list so that people interested in clojurescript and
> not clojure could follow relevant discussions without manually
> filtering out threads.

I don't know whether or not contributions are intentionally made hard,
but I would also appreciate separate mailing lists and IRC channels for
Clojure and ClojureScript.

-Phil

[Jay Fields]

I'm not sure I've ever sent an email where the entire content should
be "+1", but this is the one where it felt most compelling.

Please split the list.

Sent from my iPhone

> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clo...@googlegroups.com
> Note that posts from new members are moderated - please be patient with your first post.
> To unsubscribe from this group, send email to
> clojure+u...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en

[Andy Fingerhut]

The issue that Clojure, its contrib libraries, and ClojureScript do not accept github pull requests has been brought up several times before on this email list in the past. Feel free to search the Google group for terms like "pull request". Short answer: Rich Hickey prefers a workflow of evaluating patches, not pull requests. It is easier for him. You aren't likely to change his preference on this issue. That choice wasn't made in order to make it harder on contributors.

Instructions on creating patches for Clojure are under the heading "Developing and submitting patches to Clojure and Clojure Contrib" on this web page:

http://dev.clojure.org/display/design/JIRA+workflow

I suspect they are quite similar for ClojureScript, but I haven't submitted a ClojureScript patch before to know for sure.

Andy

[Frank Siebenlist]

One process that could be made a little easier is the contribution of code documentation and suggested improvements of doc-strings.

New or improved doc-strings do not change any functionality, impact any tests, require peer review…

If we could simply suggest new doc-strings for example in the JIRA-issue, have enough eyeballs stare at it, improvements, amendments…,
then after sign-off, a committer could simply copy&paste this approved enhancement in the official code.

Low-impact and it could make it easier to get community involvement and contributions for clojure & clojurescript's documentation, which arguably could use a little patch here and there.

Having to go thru the whole official patch process to suggest an improved docstring is a bit much… and god forbid that you have to thru that multiple time before all the , and . are approved.

-FrankS.

[Sean Corfield]

On Fri, Jan 18, 2013 at 1:33 PM, Andy Fingerhut
<andy.fi...@gmail.com> wrote:
> The issue that Clojure, its contrib libraries, and ClojureScript do not accept github pull requests has been brought up several times before on this email list in the past. Feel free to search the Google group for terms like "pull request". Short answer: Rich Hickey prefers a workflow of evaluating patches, not pull requests. It is easier for him.

My understanding is that with pull requests it becomes much harder to
provide accountability for Intellectual Property which is a legal
concern, and that's why we have a Contributor's Agreement. The patch
process naturally falls out of the legal CA-covered process since each
patch is clearly identified as "belonging" to a specific contributor -
and submitting a patch comes with the responsibility of vouching for
the legal status of that submission. Github's pull request process
makes it all too easy to incorporate code that belongs to a Github
account holder who is not covered by the legal agreement and places
the burden of verification on screeners to verify the IP ownership.

But let's not re-hash the issue of the CA. Folks can just read the
archives and there's really nothing new to add...
--
Sean A Corfield -- (904) 302-SEAN
An Architect's View -- http://corfield.org/
World Singles, LLC. -- http://worldsingles.com/

"Perfection is the enemy of the good."
-- Gustave Flaubert, French realist novelist (1821-1880)

[Hugo Duncan]

Sean Corfield <seanco...@gmail.com> writes:

> My understanding is that with pull requests it becomes much harder to
> provide accountability for Intellectual Property which is a legal
> concern, and that's why we have a Contributor's Agreement.

I wonder if the availability of http://www.clahub.com/ changes anything...

Hugo

[Sean Corfield]

That will depend on whether it traces the origin of each line in the
patch - just relying on the pull request originator is not sufficient
(unfortunately).

> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clo...@googlegroups.com
> Note that posts from new members are moderated - please be patient with your first post.
> To unsubscribe from this group, send email to
> clojure+u...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en

[Irakli Gozalishvili]

At mozilla we also require signing CA but do accept pull requests and there are whole team of legal people that

makes sure things like that don't raise any legal concerns. After all it's just .patch to the pull request url gives you

an actual change patch so if reviewing patches is desired it's easy to build a tool that attaches it to JIRA. We in fact

do that for bugzilla. The good news is that such tools are already written for JIRA so it's just matter of enabling it!

Regards

--
Irakli Gozalishvili
Web: http://www.jeditoolkit.com/

[Irakli Gozalishvili]

One could also copy attach patch with lines that belong to someone else. How is that different ?

Pull requests are just a tool for working with patches nothing else

Regards

--
Irakli Gozalishvili
Web: http://www.jeditoolkit.com/

[Sean Corfield]

Because by submitting a JIRA patch explicitly, you are taking the
legal responsibility for the contents of the patch as being a change
that you are authorized to submit under the CA...

I'm not sure that you can even attach a patch to a Clojure ticket in
JIRA without being given permission to modify tickets (which means you
have a CA on file)?

As you say, at Mozilla, you have a whole team of legal people making
sure things are safe and acceptable. Clojure/core does not have that
luxury.

[Brandon Bloom]

For what it's worth, I've submitted 20+ patches to ClojureScript and one or two to Clojure proper. I still find the process to be extremely unpleasant. I consistently avoid interacting with JIRA until the last possible minute: That software is actively user-hostile. Without naming names, I've spoken with a half dozen other active contributors who feel the same way. If I wasn't between jobs at the time, I'd never have made it over the hump towards being a contributor.

[Irakli Gozalishvili]

On Friday, 2013-01-18 at 18:03 , Sean Corfield wrote:

Because by submitting a JIRA patch explicitly, you are taking the

legal responsibility for the contents of the patch as being a change

that you are authorized to submit under the CA...

You can in fact do similar with contributing guidelines that are displayed once pull requests  is created:

https://github.com/blog/1184-contributing-guidelines

And just reject pulls from people who did not signed CA

 

I'm not sure that you can even attach a patch to a Clojure ticket in

JIRA without being given permission to modify tickets (which means you

have a CA on file)?

Yes I did signed CA and it's always possible to not merge pull requests from people who have not signed CA yet.

 

As you say, at Mozilla, you have a whole team of legal people making

sure things are safe and acceptable. Clojure/core does not have that

luxury.

Maybe I was not clear here but legal people do not go through each pull request only signers

do merges people sending pull requests. I also have contributed to several other projects that

required signing CA before taking any of my pull requests, so I really don't see why it's a problem

for clojure.

[Irakli Gozalishvili]

As a matter of fact I have abandoned clojurescript once before and just wrote my own implementation of JVM free clojurescript

subset:

https://github.com/Gozala/wisp

http://jeditoolkit.com/wisp/

But kanaka's clojurescript in clojurescript https://github.com/kanaka/clojurescript/ got me  excited and I'm trying to get involved

again. Luckily he's being awesome to work with & has no problems accepting pull requests. But if the process of contributing

is more work than I can keep up with I'll have to turn away again :(

I also don't quite see the point of being on github if use of it's features is unacceptable.

Regards

--
Irakli Gozalishvili
Web: http://www.jeditoolkit.com/

[Irakli Gozalishvili]

BTW also as hugo pointed out  with http://www.clahub.com/ one could just reject pull requests if any of the commit included

is from author who have not signed CLA yet. So looks like CLA problem can be also easily solved.

Regards
--
Irakli Gozalishvili
Web: http://www.jeditoolkit.com/

On Friday, 2013-01-18 at 18:03 , Sean Corfield wrote:

[Andy Fingerhut]

On Jan 18, 2013, at 3:52 PM, Sean Corfield wrote:

> On Fri, Jan 18, 2013 at 1:33 PM, Andy Fingerhut
> <andy.fi...@gmail.com> wrote:
>> The issue that Clojure, its contrib libraries, and ClojureScript do not accept github pull requests has been brought up several times before on this email list in the past. Feel free to search the Google group for terms like "pull request". Short answer: Rich Hickey prefers a workflow of evaluating patches, not pull requests. It is easier for him.
>
> My understanding is that with pull requests it becomes much harder to
> provide accountability for Intellectual Property which is a legal
> concern, and that's why we have a Contributor's Agreement. The patch
> process naturally falls out of the legal CA-covered process since each
> patch is clearly identified as "belonging" to a specific contributor -
> and submitting a patch comes with the responsibility of vouching for
> the legal status of that submission. Github's pull request process
> makes it all too easy to incorporate code that belongs to a Github
> account holder who is not covered by the legal agreement and places
> the burden of verification on screeners to verify the IP ownership.
>
> But let's not re-hash the issue of the CA. Folks can just read the
> archives and there's really nothing new to add...

I won't rehash the issue, but will provide direct pointers to a couple of posts that led me to believe my statements above.

Here is a link to the whole thread, with many posts on the then-just-being-started clojure-doc.org web site (which I'm pleased to see has certainly come a long way since early Oct 2012):

https://groups.google.com/forum/?fromgroups=#!topic/clojure/jWMaop_eVaQ

Scan a down to Jay Fields post from Oct 6 2012, and then to Rich Hickey's response later the same day. I don't have any inside info about Rich's preferences for patches outside of such public messages, but it definitely seems to be due to workflow preference issues, not legal issues.

Andy

[Andy Fingerhut]

Irakli:

I am curious about the possibility of auto-creating patches from git pull requests, in case that would bridge the divide between people that would prefer submitting pull requests, and Clojure screeners that would prefer evaluating patches and JIRA tickets.

Causing a new git pull request to to auto-create a JIRA ticket with a patch sounds easy, but that isn't the whole process.

What about comments that are later added to the pull request?  Are they auto-added as comments to the JIRA ticket?

Are comments added to the JIRA ticket auto-added as comments to the pull request?

If the JIRA ticket is closed, does that automatically close the github pull request?

If the answer to all of the above is "yes, already works that way", then I'd be willing to spend a little more time looking into it.  Do you have links to any info on the tools that enable such behavior?

Thanks,

Andy

[Michael Klishin]

Irakli Gozalishvili:

If these things are intentionally made hard to stop new people with more clojurescipt interests then please

make it more clear, cause otherwise it just a motivation killer. 

Irakli,

Over the years, many people have tried raising the question of why contributing to Clojure (and ClojureScript, and anything Clojure/core touches)

involves so many obstacles and bureaucracy. Just search the archives.

Unfortunately, the answer many folks come up with is: Clojure/core don't see it as a major problem.

So, my advice to you: forget about it. Contributing to Clojure[Script] projects

that do not involve Clojure CA and the existing process is much more productive.

MK 

[Alexey Petrushin]

+1

[Aaron Cohen]

Being the maintainer of an open source problem is a hard task.

Contributing to a project is not a process that begins and ends with code submissions. In fact, it's often more work for a maintainer to accept a patch or pull request than it is for him or her to write the equivalent code himself.

Clojure is hardly the only project that doesn't accept pull requests. The Linux Kernel and Guava are two that immediately come to mind. For Guava's rationale, you might read the following: https://plus.google.com/113026104107031516488/posts/ZRdtjTL1MpM Their reasons are not identical to Rich's, but the sentiment is similar.

Does this mean you shouldn't even try to contribute? No, of course not. But, contributions to clojure are definitely less easy to make than to projects that willy-nilly accept any pull request.

[Aaron Cohen]

Also, another blog post dealing with the open source code contribution issue: http://www.igvita.com/2011/12/19/dont-push-your-pull-requests/

[Brandon Bloom]

> contributions to clojure are definitely less easy to make than to projects
> that willy-nilly accept any pull request.

False dichotomy. Accepting pull requests does not mean you need to be willy-nilly about it.

You know how people carefully optimize their signup forms and checkout flows? They do this because there's a (very large) category of people who simply give up when things aren't immediately obvious. Granted, this category is much smaller among the class of folks skilled enough to create a desirable Clojure patch. However, the fact that this topic keeps coming up suggests that maybe that group is large enough to pay attention too.

As the Clojure implementations evolve, fewer and fewer people will discover issues large enough to justify diving into the code base to fix them. Most people just work around the issues. If somebody takes the initiative to properly fix an issue, we shouldn't add yet another hurdle discouraging them from contributing.

[Brandon Bloom]

Aaron, please forgive my failure at formalities: Allow me to add that I agree with the rest of your post.

The Linux kernel and Guava guys are absolutely right about patches defaulting to the rejected state. I'm a big believer in the "minus 100 points" philosophy.

It's just that I just really hate JIRA.

[Softaddicts]

Yep, tools to maintain tickets suck, Jira, Mantis,...

However, having Clojure code in production 24/7 and ClojureScript code
reaching production status in a month or so, I feel reassured that a maintenance process
is in place and that patch screening is tight.

We have enough doing the same thing here with our own code, I wonder how we would
fare if the layers we are building upon were not tightly managed as possible given
the limited resources. Building pyramids on sand is not my cup of tea.

Nobody yet has invented a maintenance process relying on thin air.
Wether you accept or not pull requests is like focusing on the tree and not seeing
the forest.

There's a documented maintenance/enhancement process, it may look rigid
but unless someone makes a formal proposal for a full maintenance workflow
with human costs and benefits, I would rather stick with this one.

Luc P.

> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clo...@googlegroups.com
> Note that posts from new members are moderated - please be patient with your first post.
> To unsubscribe from this group, send email to
> clojure+u...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en

--
Softaddicts<lprefo...@softaddicts.ca> sent by ibisMail from my ipad!

[Irakli Gozalishvili]

I think Brandon, in fact I discovered bunch of clojurescript bugs while working on my wisp project but since submitting and fixing them felt like too much work I just ignored them. Unfortunately I keep looking into my fixes now to back port them to cljs_in_cljs. 

I also absolutely agree if issues keeps coming up that certainly means there is a problem worth looking into

Regards

--
Irakli Gozalishvili
Web: http://www.jeditoolkit.com/

--

[Irakli Gozalishvili]

As of comments related to projects that also make contributions hard that's their choice, and I really hope clojure community will do better than that. I also know that sometimes rewriting patch is a lot less work than making someones contribution acceptable, my day job involves all of that, but still we help people trying to contribute regardless sometimes that means they send in copies of files :) Never the less we work with them so people are still encouraged to contribute, over the time level of these contributions also grows. Turning them away is just strange to me. And yes at mozilla we do code that is production and used by billions of people over the world and being helpful to contributors never had being harmful in doing that.

Regards

--
Irakli Gozalishvili
Web: http://www.jeditoolkit.com/

--

[Irakli Gozalishvili]

On Saturday, 2013-01-19 at 11:56 , Andy Fingerhut wrote:

Irakli:

I am curious about the possibility of auto-creating patches from git pull requests, in case that would bridge the divide between people that would prefer submitting pull requests, and Clojure screeners that would prefer evaluating patches and JIRA tickets.

Causing a new git pull request to to auto-create a JIRA ticket with a patch sounds easy, but that isn't the whole process.

What about comments that are later added to the pull request?  Are they auto-added as comments to the JIRA ticket?

Are comments added to the JIRA ticket auto-added as comments to the pull request?

If the JIRA ticket is closed, does that automatically close the github pull request?

If the answer to all of the above is "yes, already works that way", then I'd be willing to spend a little more time looking into it.  Do you have links to any info on the tools that enable such behavior?

I'm afraid I don't have answers to those questions it's just someone have pointed out this link

https://confluence.atlassian.com/display/JIRASTUDIO/Linking+GitHub+Activities+to+JIRA+Issues

in the pull request I created when it was closed down. Bugzilla integration does all of these, but syncing comments. Maybe support for JIRA is better or worth, I have no way of trying that out as I don't have access to JIRA.

 

Thanks,

Andy

On Jan 18, 2013, at 5:13 PM, Irakli Gozalishvili wrote:

At mozilla we also require signing CA but do accept pull requests and there are whole team of legal people that

makes sure things like that don't raise any legal concerns. After all it's just .patch to the pull request url gives you

an actual change patch so if reviewing patches is desired it's easy to build a tool that attaches it to JIRA. We in fact

do that for bugzilla. The good news is that such tools are already written for JIRA so it's just matter of enabling it!

--

[Irakli Gozalishvili]

Than Sean for pointing to that thread that's helpful although that got me wondering if Rich is only one

doing the reviews ? If that's not the case maybe there at least on maintainer that is willing to bridge the

gap here ?

I really hope someone will step up to bridge the gap, maybe setup a fork and then forward contributions as a

patches to JIRA so people who love patches will look at them instead.

Regards

--
Irakli Gozalishvili
Web: http://www.jeditoolkit.com/

[David Nolen]

I have nothing to add to this thread beyond pointing out that ClojureScript has had _51_ contributors in the short year and a half of its existence: http://github.com/clojure/clojurescript/graphs/contributors.

Via JIRA.

David

[Irakli Gozalishvili]

I would be curious to also see number of lost contributors.

Regards
--
Irakli Gozalishvili
Web: http://www.jeditoolkit.com/

--

[Irakli Gozalishvili]

Anyway it's seems to me that message in this thread is pretty clear:

"We're just doing fine without people like you"

It's a shame, but whatever I'll just shut up and let you guys roll as you pleased

Regards
--
Irakli Gozalishvili
Web: http://www.jeditoolkit.com/

[Dave Sann]

It is great that questions are being asked about how things do, might or should work - but tone of the original question and the ensuing discussion, in my view, unfortunate.

[Brandon Bloom]

There are 176 forks on GitHub. Even assuming that all 51 contributors have a public fork (most probably do), that's 125 potential contributors unaccounted for. Only 29% of those forks account for an accepted contribution. What portion of the remainder might have been contributors?

I was curious if 29% was "good" in comparison to other projects on GitHub. I also have never written a Ring/Compojure app, so I took 2ish hours and threw a little toy together and seeded it with some "interesting" repositories from GitHub's "explore" feature.

Code: https://github.com/brandonbloom/cvf

Running: http://boiling-inlet-6842.herokuapp.com/

Feel free to add some repositories to it, but please try not to break it. It's not exactly robust :-)

In short, 29% seems pretty reasonable for the number of forks ClojureScript has. Obviously that percentage goes down as the number of forks goes up, so some normalization would need to occur.

Of note, technomancy/leiningen scores 49% for 331 forks. That's pretty *awesome*. Good job guys!

[Marek Šrank]

On Saturday, January 19, 2013 8:56:28 PM UTC+1, Andy Fingerhut wrote:

Irakli:

I am curious about the possibility of auto-creating patches from git pull requests, in case that would bridge the divide between people that would prefer submitting pull requests, and Clojure screeners that would prefer evaluating patches and JIRA tickets.

Causing a new git pull request to to auto-create a JIRA ticket with a patch sounds easy, but that isn't the whole process.

What about comments that are later added to the pull request?  Are they auto-added as comments to the JIRA ticket?

Are comments added to the JIRA ticket auto-added as comments to the pull request?

If the JIRA ticket is closed, does that automatically close the github pull request?

If the answer to all of the above is "yes, already works that way", then I'd be willing to spend a little more time looking into it.  Do you have links to any info on the tools that enable such behavior?

Thanks,

Andy

There's another, easier possibility - When the pull request is created, create also the JIRA issue with the patch added, then add a github comment pointing to the JIRA issue and close the pull request. This is not perfect, but IMO better than the current state...

Another, even easier would be just to autopost a github comment, stating that pull requests aren't accepted and pointing to the Clojure contributing page...

Marek

[Michael Klishin]

2013/1/20 Aaron Cohen <aa...@assonance.org>

Clojure is hardly the only project that doesn't accept pull requests. The Linux Kernel and Guava are two that immediately come to mind. For Guava's rationale, you might read the following: https://plus.google.com/113026104107031516488/posts/ZRdtjTL1MpM Their reasons are not identical to Rich's, but the sentiment is similar.

…as well as tens of millions that do, and it works wondefully for them.

 

Does this mean you shouldn't even try to contribute? No, of course not. But, contributions to clojure are definitely less easy to make than to projects that willy-nilly accept any pull request.

Who says any pull request should be accepted? It is pretty widely accepted that contributing to Clojure and anything Clojure/core

touches is needlessly hard. That's what this thread is about, not "accepting any pull request".
--
MK

http://github.com/michaelklishin
http://twitter.com/michaelklishin

[Michael Fogus]

I'll just add a few points:

Pull requests are not likely to happen. It's not worth fighting over.
However, I think that is a weak excuse for not contributing. If you
want to contribute a complex bug fix, then the patch process is
trivial by comparison. If you want to contribute doc fixes and think
that the patch process is too cumbersome (or in the case of the wiki,
not applicable) then there are numerous options in order of decreasing
visibility:

- use Github's annotation capabilities to add editorial comments
(e.g. https://t.co/UXrsMk2M)
- mailing lists
- send a tweet
- IRC
- email your suggested enhancements to the maintainer

There are many ways to contribute valuable documentation and minor bug
fixes than the patch system. In most cases a matter of rights never
comes into play because using editorial commentary and the
identification of bugs fall under the aegis of fair use (otherwise Joy
of Clojure would have 24 co-authors). There are other advantages to
Github besides pull requests, annotations being just the one that
directly pertains to this discussion. If you want to help then there
are numerous ways to do so. If you want to push an agenda then by all
means continue this thread.

I would love to see a better system in place for contributing to the
wiki. I have no solution sadly.

Likewise I would love to see a separate mailing lists and IRC for
ClojureScript -- although nothing is stopping someone from creating
them except the promise of a thankless job in moderation. Maybe
that's why it hasn't happened yet - everyone is hoping someone else
will do the dirty work. ;-)

We're all friends here. Everyone wants to help. There are ways to
help that do not involve endless mailing list threads and personal
distaste of process.

[kinleyd]

Well said, Fogus, well said.

[Anthony Grimes]

I think most people here have missed the point.

This thread and the arguments in the past aren't and never have been about how hard it is to get a contribution accepted into Clojure.

It does not matter where that contribution comes from. Your code will be rejected for any number of reasons (stupid, bad code, not a

real problem). It doesn't matter if that code is in a pull request, patch on a jira ticket, printed and mailed to Rich Hickey, or send up in

a rocket to circle the sun before strategically landing in Stuart Halloway's hands. Please do not conflate Github pull requests with the

'willy nilly' acceptance of contributions. The two have nothing to do with one another.

It appears that a few people here are surprised that people want this so bad or that they are persistently arguing for it. It's because we

(including me) do not understand why the pleasant and perfectly legal processes that several other projects (many that I believe are perhaps larger

than Clojure) and we are baffled. The same responses are always reiterated, such as Sean Corfield's (who means well and whom I have no

animosity against) legal responses. Our OP (who appears to have left out of frustration at vague answers and the lack of any response by

clojure/core) is at one of those organizations. Are we saying that Mozilla's open source contribution process is not legal enough? Otherwise,

what exactly are we saying?

Please don't ask people to not rehash this discussion. Don't tell them that it is a 'weak reason' for not contributing and 'not worth fighting over'.

That's ridiculous. How many people have brought this up? Isn't it a little arrogant to just dismiss the issue as "Meh, they're not as smart as I am

and obviously just don't understand my super special complex reason for doing all these bizarre things. Let's just shoo them away"?

In closing, I propose the following. If we're going to continuously deny people things they are accustomed to, instead of treating them like angry

children having tantrums, why don't we get a response from clojure/core and have it displayed prominently somewhere would-be contributors

can see it? The page should at least explain:

* Why we use Jira

* Why we only accept Jira patches

* Why contribution processes like those adopted by organizations and companies like Mozilla are not acceptable

Is that too much to ask for? I know Rich implied problems with entitlement in the community related to other things, and this may come off as me

saying we're entitled to things, I think people who have roughed through the Clojure contribution process and came out on the other side with the

opinion that there is a problem (see Brandon Bloom for a model example) *should* be entitled to more than dismissal. I am not one of them, my

first patch is still in the jira waiting phase, but I cringe when I see this discussion nonetheless. Having spent some amount of time trying to use JIRA,

I almost believe that that in particular *was* done to make the contribution process more hostile. Obviously it wasn't, but was there really nothing better?

Presumably there wasn't, not for Clojure, but do I know why? I do not. Just that single page with those three bullet points would solve that problem. The

next thread that pops up could be responded to with little more than a link, and if people wanted to argue them they'd have a lot more grounds to do so.

-Anthony

[David Nolen]

It makes more sense to compare language projects. I note that ClojureScript does about as well as Scala in this comparison and much better than CoffeeScript. Scala and CoffeeScript use pull requests.

I also do not like JIRA. But I think the happiness of contributing to ClojureScript far outweighs the tedium of JIRA and the quality of the contributions back this up.

--

[Michael Fogus]

Please don't ask people to not rehash this discussion. Don't tell them that it is a 'weak reason' for not contributing and 'not worth fighting over'.

Well, that's only my opinion.  I happen to think it's not worth fighting over so I don't.  Rich has put in place a system he's happy with.  I can either agree with it or not, but regardless I'm unlikely to change anyone's mind.  I apologize for asking not to rehash. Rehash away.

That's ridiculous. How many people have brought this up?

Many. And it's been addressed by Rich numerous times as well.

 Isn't it a little arrogant to just dismiss the issue as "Meh, they're not as smart as I am

I only offered some potential solutions to a couple of nagging problems.  I was unaware that would be taken as displaying an arrogance of intellectual superiority. My bad.

--
-- http://blog.fogus.me
-- http://github.com/fogus
--

[Michael Klishin]

2013/1/20 Michael Fogus <mef...@gmail.com>

We're all friends here. Everyone wants to help.  There are ways to
help that do not involve endless mailing list threads and personal
distaste of process.

Michael,

I'm sorry but given Clojure/core's track record of *actions* (or lack of them, rather) this

sounds a bit offensive to people who are not Clojure/core members, Clojure committers or "screeners".

The current process is broken in many ways:

 * The mail-CA-in-paper process shuts out most developers outside of US, Canada and western Europe

 * It is simply inconvenient to developers used to GitHub which is what the majority of OSS projects use

 * It takes a really long time for a patch to go through the process. It is common that patches land in master 3, 5 or 10 months after the submission, even if they are fairly urgent bug fixes

 * Parts that are not essential (e.g. tools.logging) are still covered by the same broken process. Even documentation is!

 

To make matters worse, Clojure/core consistently avoids discussing these issues in public, leaving developers wondering

if they care about any of these things. Given that adopting Clojure is a non-trivial decision, this

concern isn't helping those looking to introduce Clojure at work.

Since the Evolving Clojure Contribution Process and Goals [2] discussion, there were no changes of any significance

to the contribution process. That was 4 months ago.

Saying "we are all friends here" is a bit optimistic and does not cut it. Clojure/core has real changes to

make to the process, otherwise people will keep leaving upset and spread the word about how broken

Clojure contribution process is. That does not work to Clojure's advantage.

1. http://dev.clojure.org/display/design/Clojure+Workflow+Overview

2. https://groups.google.com/forum/?fromgroups=#!searchin/clojure/evolving$20contribution$20process/clojure/GnfAK6beMN8/aRl7jA0hsP4J

[Anthony Grimes]

Please don't take what I said as directed at just what you said. I couldn't 'reply' to everyone at once, so I picked the last person who had responded.

I think the people here are perfectly swell! I just don't understand why things are handled the way they are in Clojure. I mean, we have all sorts of places

to put up this information and not have to rehash it again. Confluence, clojure.org. I know Rich has responded to some of these questions in the past, but

I can't recall him responding to the last bullet point, which is to compare Clojure's process to other projects and explain why their processes are not suitable.

I think that would solve a lot of problems. If he has responded to them, that's great, but we should still consolidate them somewhere.

[Michael Fogus]

I'm sorry but given Clojure/core's track record of *actions* (or lack of them, rather) this

sounds a bit offensive to people who are not Clojure/core members, Clojure committers or "screeners".

Adding source annotations to a Github project's source base and starting an IRC channel have nothing to do with being a commiter, core member or even having a CA.  The former reduces the friction of offering minor changes.You'll recall that I said nothing about the speed of Core.   I prefer to discuss things that I have control over.

The current process is broken in many ways:

From your perspective perhaps.  There are others whom disagree.  Can there be improvements?  Definitely.  I offered two.

 

To make matters worse, Clojure/core consistently avoids discussing these issues in public

I would guess because their position hasn't changed since the last time.  This is only speculation.  A page like what Anthony proposes could help, but it wouldn't satisfy everyone.  Stuart Sierra wrote up something related, but it doesn't cover everything discussed here http://clojure.com/blog/2012/02/17/clojure-governance.html

Saying "we are all friends here" is a bit optimistic and does not cut it.

It is very optimistic.  Guilty as charged.  I would say that saying Core doesn't care is very pessimistic.

[Anthony Grimes]

On Sunday, January 20, 2013 11:33:56 AM UTC-6, Fogus wrote:

 

To make matters worse, Clojure/core consistently avoids discussing these issues in public

I would guess because their position hasn't changed since the last time.  This is only speculation.  A page like what Anthony proposes could help, but it wouldn't satisfy everyone.  Stuart Sierra wrote up something related, but it doesn't cover everything discussed here http://clojure.com/blog/2012/02/17/clojure-governance.html

Well, no, if the answer remains the same it probably won't satisfy everyone, but at least they'll have an easy way to learn why.

[Irakli Gozalishvili]

I just wanted to mention that pull request was one of the several notes I've made, but looks like it's being irritating enough people that it completely took over this thread. The problem itself is not a JIRA or that sending patches is too hard (even though I think it's too much incidental complexity :) problem is that in order to fix a bug I've encountered, I have to go through a lot of hoops and that's too much for the first sip. Maybe less for people doing Java based programs as I still have dark memories from amount of configuring I have to do to actually get things running, but it definitely is for people that or from other communities and if clojure is not ready to accept people from different backgrounds what is the point of speaking at jsconf

http://blip.tv/jsconf/jsconf2012-david-nolen-6141386 ?

Now I think a lot of points have being completely missed here, pull requests is just a tip of the iceberg, world has moved on from

sending patches to building great tooling like https://travis-ci.org/ integration testing that verifies code quality of an each checking and even those pull requests submitted, which saves a lot of time for both submitter and maintainer that otherwise would have to

download patch, apply and run tests. Of course if you're Rich Hickey you may find bugs in patches without doing all that, but if me sloppy contributor can detect issues before patch reaches Rich would save his time of looking at it. Not to say that I'm sure that even Rich could miss something and having tooling that makes sure nothing breaks is useful. It's actually very surprising to me that project of this size does not has integration testing in place. 

Now it's not clear which browsers clojurescript is going to work but regardless of claims it would be great to have facts. So my next step was to setup integration tests with http://ci.testling.com/ that is like travis.ci but runs your tests in all possible browsers & believe there are tons of bugs when it comes to cross-browser compatibility.

So it's not just that some people keep insisting on using pull requests it's a lot more and maybe it's time for this community to revisit some decisions. It's just natural process of grows.

Regards
--
Irakli Gozalishvili
Web: http://www.jeditoolkit.com/

--

[Brandon Bloom]

I think the inflammatory thread subject didn't help...

Java and cross-browser CI both sound great. I don't know if Clojure/core already has CI or what, but maybe you should take these ideas over to another thread? Possibly on the Dev mailing list. Because of the intentionally slow pace of Clojure development, I'd suggest one thread per topic (CLJ CI is a different topic than CLJS CI) and one thread at a time.

[Andy Fingerhut]

There currently is such testing of patches submitted to Clojure, which I've implemented with some Clojure programs I've cooked up.  It tests all patches attached to Clojure JIRA tickets to see if they apply cleanly and whether the code compiles and passes existing unit tests.  I've been periodically publishing a report of such patches on the Clojure Dev Google group for about 9 months now.

    https://github.com/jafingerhut/clj-prescreen

This testing isn't done for ClojureScript or the Clojure contrib libraries at the current time, at least not to my knowledge.

Andy

[Michał Marczyk]

Clojure and contrib have long had extremely thorough CI in place,
including matrix testing with multiple JVM implementations:

http://build.clojure.org/

Cheers,
M.

[Michał Marczyk]

On a separate note, if there are indeed "tons of bugs when it comes to
cross-browser compatibility" in ClojureScript, pointing (as many as
possible of) them out would be extremely helpful, indeed more than
submitting the actual patches. That would also not require going
through the patch submission process.

M.

[Irakli Gozalishvili]

On Sunday, 2013-01-20 at 14:27 , Michał Marczyk wrote:

On a separate note, if there are indeed "tons of bugs when it comes to

cross-browser compatibility" in ClojureScript, pointing (as many as

possible of) them out would be extremely helpful, indeed more than

submitting the actual patches. That would also not require going

through the patch submission process.

Sorry for not being clear I meant browser bugs that clojurescript can be tripped up upon.

[Andy Fingerhut]

On Jan 20, 2013, at 7:49 AM, Anthony Grimes wrote:

>
>
> In closing, I propose the following. If we're going to continuously deny people things they are accustomed to, instead of treating them like angry
> children having tantrums, why don't we get a response from clojure/core and have it displayed prominently somewhere would-be contributors
> can see it? The page should at least explain:
>
> * Why we use Jira
> * Why we only accept Jira patches
> * Why contribution processes like those adopted by organizations and companies like Mozilla are not acceptable

Anthony and others:

I've spent some time creating a new page that might be a start at addressing some of these questions, and perhaps could be pointed at when this topic arises again. I don't expect it gives satisfying answers to all of your questions above at this time, but it can be enhanced if desired.

http://dev.clojure.org/display/design/Brief+description+of%2C+and+FAQs+about%2C+the+Clojure+contribution+process

The best answer I know of for why Clojure only accepts JIRA patches is that Rich Hickey prefers them, as given on a link on that page now, and which I gave earlier in this thread. He says it saves him time compared to github pull requests, for example. If you want to know in detail *why* it saves him time, I don't have an answer for that question.

Andy

[Aaron Cohen]

(Thanks for the apology Brandon. For those confused, he was responding to a private email I sent him that said: "I feel like you read my email until you found something to nitpick, and then ignored the rest of it.")

On Sat, Jan 19, 2013 at 5:57 PM, Brandon Bloom <snpr...@gmail.com> wrote:

> contributions to clojure are definitely less easy to make than to projects
> that willy-nilly accept any pull request.

False dichotomy. Accepting pull requests does not mean you need to be willy-nilly about it.

You know how people carefully optimize their signup forms and checkout flows? They do this because there's a (very large) category of people who simply give up when things aren't immediately obvious. Granted, this category is much smaller among the class of folks skilled enough to create a desirable Clojure patch. However, the fact that this topic keeps coming up suggests that maybe that group is large enough to pay attention too.

This is only a valid comparison if the goal for Clojure was "gather as many contributors as possible." If the goal is minimize maintainer effort, or maximize maintainer pleasure, or maximize maintainer/submitter pleasure, then the results are less comparable. Are we at the right point on the axis? Maybe not, but Clojure has managed to collect quite a few contributions over its life, so all I know is that we at least are not at a complete minima.

 

As the Clojure implementations evolve, fewer and fewer people will discover issues large enough to justify diving into the code base to fix them. Most people just work around the issues. If somebody takes the initiative to properly fix an issue, we shouldn't add yet another hurdle discouraging them from contributing.

I don't believe this is truly a likely scenario. In my experience there are always minor bugs to be fixed.

However, I do think there is some sort of function that could be graphed of "patch size/complexity vs maintainer effort". The problem is that as patch complexity drops to zero, maintainer effort does NOT, it drops to some minimum. (Also, as patch size grows linearly, I would guess that maintainer effort grows at some exponential). So, a contribution that is truly valuable in terms of saving a maintainer effort actually has a fairly narrow window of complexity.

This by the way, is why getting Rich's buy in before you start coding is valuable.

(I sympathize with your dislike of JIRA by the way)

[Michael Klishin]

2013/1/20 Aaron Cohen <aa...@assonance.org>

Maybe not, but Clojure has managed to collect quite a few contributions over its life, so all I know is that we at least are not at a complete minima.

Whatever the goal of the current process is, it is not stated clearly to the community.

Instead of guessing what the current process is focused on, lets focus on one important thing it fails at. It fails at making

bug fixes reach master quickly. 3 to 10 months is not a time frame to be proud of for a relatively small, fairly young project.

What does this suggest? To me it suggests that maybe Clojure/core simply does not have enough bandwidth to go through this N step

process. The community growing at double digits every year also is not helping. If so, having more people involved will help.

The current process certainly does not make it easy to get involved, even if your goal is to work on boring

things existing maintainers may have little interest in (bug fixing, doc improvements, etc).

Whatever benefits come from a tiny group of people having very tight grip over even the most minor changes to the language, contrib libraries and docs, rapid bug fixing is not one of them.

[Andy Fingerhut]

Michael, I would also love it if bugs got fixed in master more quickly.  I've done some things to try to make that happen, but for all I know I've only exacerbated the issue.  I'm still searching for ways to improve that.

One thing I know at the base of all such suggestions is: I am not going to expect others to change what they do in order to satisfy what I want, unless we've got a mutually agreed upon contract in place that says so.  Acting otherwise is akin to storming the North Pole and demanding that Santa give an accounting of what he's done for me lately.  (I am not saying you have acted like this -- it is an illustration of what I have to remind myself not to do.)

Here is one suggestion that might help.  Remove the "doc improvements" part that you mention from the patch submission process completely.  Today you can fire up a Leiningen REPL, type (cdoc map), and get examples from the ClojureDocs.org web site.  None of those examples went through JIRA, and anyone in the world can update them in 5 minutes.

I'm not saying we should all rest on the laurels of the cdoc macro.  If one wanted *slightly* more editorial control of what appeared in those doc strings, they could publish a not-very-large file of "new improved doc strings" and make a macro like doc and cdoc that shows them.  Or one could even redefine doc in your own REPL to show the new doc strings instead of the ones built into Clojure.  Publishing such a file on github would work, and the person publishing that file of new improved doc strings could take pull requests, or whatever they chose that works for them, to update them.  It would take someone with the energy you have shown in reviewing and accepting upates to clojure-doc.org.  I do not mean by that statement that I expect you to do such a thing -- only to describe the kind of time and thought required.  Anyone could do it.

Andy

[Rich Morin]

On Jan 21, 2013, at 12:20, Andy Fingerhut wrote:
> If one wanted *slightly* more editorial control of what appeared
> in those doc strings, they could publish a not-very-large file of
> "new improved doc strings" and make a macro like doc and cdoc that
> shows them. Or one could even redefine doc in your own REPL to
> show the new doc strings instead of the ones built into Clojure.

I've actually thought about doing something like this. True, there
is the slightly thorny issue of keeping the contributed docs up to
date, but Codeq could certainly tell us when any function (including
its doc string) has changed. That could be used to send a bluebird
to the documentation maintainers whenever an inspection is needed.

Decoupling documentation from the code would have multiple benefits:

* As discussed, it would allow changes to be made easily, quickly,
and by any interested party. Some sort of version management,
coupled with identity tracking for submitters, would keep most
of the noise under control.

* It would completely defuse any arguments about what information
should or shouldn't be included. Indeed, it would let us split
up the documentation into sections (eg, short/full description,
examples, related functions). This information would fit well
in a system like Codeq and could be displayed as desired.

* It would allow us to shift from "ASCII/monospace" formatting to
a more readable (and semantically meaningful) mixture of fonts,
layout directives, etc.

Something like Markdown (with Clojure-friendly sigils) could be
used to identify types of text, add formatting hints, etc. We
could then have a reader (xdoc?) that handled fonts nicely.

Note that a system such as Codeq could easily integrate information
from code quanta with relevant documentation from other sources. I
could also imagine Autodoc getting into this game. In summary, we
HAVE the technology (:-).

-r

--
http://www.cfcl.com/rdm Rich Morin
http://www.cfcl.com/rdm/resume r...@cfcl.com
http://www.cfcl.com/rdm/weblog +1 650-873-7841

Software system design, development, and documentation

[Andy Fingerhut]

Yes, we do have the technology, and have for years now. The technology isn't the hard part in this case. The only barrier to entry is the willingness and ability to spend time, more time, and yet more time, where the benefit is mostly what you learn and the thanks you get, minus any complaints you get for not doing it the way the complainer wants you to (scratch that last part if you can ignore them). If that sounds like fun to you, I heartily recommend going for it! Just let me know when I can submit enhanced docstrings, and you can bet I will.

Minor suggestions: If someone wants to use codeq for this, more power to them. However, having a separate set of "enhanced docstrings" for each released version of Clojure or library would probably be enough, and "diff" is sufficient to keep track of changes when things are relatively stable as they are within many libraries.

I wouldn't say it would defuse any arguments about what information should or shouldn't be included. Any such arguments would move from the Clojure team to whoever maintains the enhanced docstrings. :-) One could imagine allowing multiple sets of such enhanced-docstrings to be distributed from multiple parties, and Clojure users could pick and choose which ones they prefer to look at. However, there is definitely an advantage to having one common source for such things.

Andy

[Rich Morin]

On Jan 21, 2013, at 17:06, Andy Fingerhut wrote:
> Yes, we do have the technology, and have for years now. The technology
> isn't the hard part in this case. The only barrier to entry is the

> willingness and ability to spend time, more time, and yet more time ...

I've been interested in mechanized documentation for decades. I have
speculated about system designs and even generated working code in the
area at times. I really like Codeq's approach, for several reasons:

* The notion of "code quanta" is new (to me, at least) and seems useful.

* The use (and extension) of Git as the system's basis allows Codeq to
take advantage of good (and strongly adopted) technology.

* The use of a flexible, powerful, and scalable database (Datomic) as
the data store allows arbitrary inputs and outputs. (I'm _really_
down on the "information silo" nature of most current doc systems.)

That said, use of Codeq should be be either invisible or optional. If I
type (doc foo) into my REPL, I should have to worry about infrastructure.


Although I wouldn't expect a tsunami of volunteer documenters, I think we
might see a fair amount of activity, given the pent-up demand that we've
seen expressed on this list. Whether the activity persists will depend
on how convenient and useful the resulting system seems.


Given Codeq's structure and Git-friendliness, it might be useful to set
up a doc repo to document each "base" code repo. I'd map each file in
the base repo to a directory in Git and each code quantum in the base
repo to a structured (eg, YAML) documentation file. This would give the
documenter(s) plenty of "elbow room" for adding text, metadata, etc.

> I wouldn't say it would defuse any arguments about what information
> should or shouldn't be included. Any such arguments would move from
> the Clojure team to whoever maintains the enhanced docstrings. :-)
> One could imagine allowing multiple sets of such enhanced-docstrings
> to be distributed from multiple parties, and Clojure users could pick
> and choose which ones they prefer to look at. However, there is
> definitely an advantage to having one common source for such things.

One advantage of storing the documentation separately from the code is
that a given piece of code can have any number of documentation files.
For example, in the system I sketched above, divisive arguments about
"what belongs in the documentation" could turn (harmlessly) into Git
forks and branches.


If I get inspired, maybe I'll create a sample repo for folks to look
over. If the basics seem solid, a trial repo could be mechanically
populated from (say) assorted Clojure libraries.

[Rich Morin]

When I discussed this approach with my spouse, she noted that
keeping documentation with source code gets in the way of a
number of issues, including internationalization. When she
worked at Apple, they had extensive discussions about this.

[Korny Sietsma]

The flip side, of course, is that having documentation separate from code often leads to the documentation becoming out of sync with the code.

What happens when someone renames or moves some code,  but doesn't also move the  docs? What happens if they change the implementation? Will people remember that every code change might potentially also require a change to documentation, stored somewhere else, and potentially versioned independently?

- Korny

[Andy Fingerhut]

Yes, those things can happen, but I think they can all be handled without big troubles.  Note that Rich Morin specifically mentioned using something like codeq to notice when particular functions change, and thus their documentation bears re-examining.  diff also works, at a file granularity rather than function granularity.

In general, what happens when the code changes is that someone eventually notices, preferably with a bit of automation to help them notice, and then goes and does the manual work required to update the docs if necessary.  For something like Clojure and its contrib libraries, the target is moving slowly enough that it can be kept in your targeting sights without much trouble :-)  Clojure has had approximately one release per year, and the behavior of most functions hasn't changed.

For other non-core libraries where new releases come out more often, the default can be to populate the new version of documentation the same as the previous version, and then look for changes where needed.  Then again, for some of those non-core libraries, the doc strings are already quite extensive and the enhanced-docstrings idea might not be desirable for them.

Andy

[Rich Morin]

On Jan 21, 2013, at 23:15, Korny Sietsma wrote:
> The flip side, of course, is that having documentation separate from
> code often leads to the documentation becoming out of sync with thecode.
>
> What happens when someone renames or moves some code, but doesn't also
> move the docs? What happens if they change the implementation? Will
> people remember that every code change might potentially also require a
> change to documentation, stored somewhere else, and potentially versioned independently?

[ Andy addressed this question, but I have my own spin on it, so... ]

Keeping the docs with the code helps to handle this problem, because it
makes it easier for a programmer to spot inconsistencies between the docs
and the adjacent code. However, we can't force the programmer to look at
the docs, let alone keep them up to date.

In any case, putting the docs in with the code causes the other problems
we've discussed (eg, bulking up the code base, making changes difficult,
getting in the way of helpful markup, internationalization issues). So
the real question is whether Codeq offers a way to keep the docs current.

I believe that it does, in a very natural fashion. Codeq tracks "code
quanta" (ie, meaningful subsets of files such as classes, methods, and
functions). If Rich Hickey changes either the code or the comments in
the foo function, Codeq will soon know about the changes. It can then
send an alert to anyone who is interested in making sure the external
documentation for the function stays current.

Given that Rich won't change any given function very often, this isn't
likely to result in a large number of alerts, updates, etc. I agree that
this isn't a perfect solution, but I think it is probably quite workable.

[Korny Sietsma]

Thanks for that explanation - I hadn't fully looked at codeq and how it works - I can see that it might make management of external documentation an easier task; especially for a codebase that changes slowly.

- Korny

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@googlegroups.com
Note that posts from new members are moderated - please be patient with your first post.
To unsubscribe from this group, send email to
clojure+u...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en

--
Kornelis Sietsma  korny at my surname dot com http://korny.info
"We do not quit playing because we grow old, we grow old because we quit playing" - O.W. Holmes

[Andy Fingerhut]

The page above was renamed to be shorter. The new link is http://dev.clojure.org/display/design/Contributing+FAQ

Andy