Please see the [Readme](https://github.com/clojuredocs/cds#readme) for
more info, but the main idea is to have a community repository of
Clojure docs. If you can write well, and want to add a doc you've
written, send a pull-request. :)
Note that the repository lives under the new "clojuredocs"
organization, and not my own username (uvtc). It's certainly intended
to be a community-driven project.
I've already written a few docs (see the ToC), and there are others
who are collaborators but who have not added their docs yet.
This is great to see. Along side efforts like Fogus' REPL love - http://readevalprintlove.fogus.me/ - we're well on our way fixing the documentation problems in our community. I could definitely see something like this migrating into docs.clojure.org once it reached maturity.
Huge thanks to everyone involved in these efforts and responding the call to action.
Also, thanks to Andy Fingerhut - who patched up the docs on contributing and helped to improve the ticket triage process. And thanks to Stu Halloway for taking some time off list to sort out some issues and help push some things forward.
2012/10/4 Paul deGrandis <paul.degran...@gmail.com>
> This is great to see. Along side efforts like Fogus' REPL love -
> http://readevalprintlove.fogus.me/ - we're well on our way fixing the
> documentation problems in our community.
> I could definitely see something like this migrating into docs.clojure.orgonce it reached maturity.
> Huge thanks to everyone involved in these efforts and responding the call
> to action.
> Also, thanks to Andy Fingerhut - who patched up the docs on contributing
> and helped to improve the ticket triage process.
> And thanks to Stu Halloway for taking some time off list to sort out some
> issues and help push some things forward.
> Paul // ohpauleez
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clojure@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+unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
Starting two different projects at the same time with almost the same
purpose seems a waste of efforts...
Wouldn't it be better for readevalprintlove and clojuredocs to join forces
from the beginning?
> 2012/10/4 Paul deGrandis <paul.degran...@gmail.com>
>> This is great to see. Along side efforts like Fogus' REPL love -
>> http://readevalprintlove.fogus.me/ - we're well on our way fixing the
>> documentation problems in our community.
>> I could definitely see something like this migrating into
>> docs.clojure.org once it reached maturity.
>> Huge thanks to everyone involved in these efforts and responding the call
>> to action.
>> Also, thanks to Andy Fingerhut - who patched up the docs on contributing
>> and helped to improve the ticket triage process.
>> And thanks to Stu Halloway for taking some time off list to sort out some
>> issues and help push some things forward.
>> Paul // ohpauleez
>> --
>> You received this message because you are subscribed to the Google
>> Groups "Clojure" group.
>> To post to this group, send email to clojure@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+unsubscribe@googlegroups.com
>> For more options, visit this group at
>> http://groups.google.com/group/clojure?hl=en
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clojure@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+unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
> Wouldn't it be better for readevalprintlove and clojuredocs to join forces
> from the beginning?
It's not clear what readevalprintlove wants to be. clojuredocs has been
discussed for a while by some people who care
about Clojure documentation. There are pretty specific plans about the
guides and moving clojuredocs.org forward
to 1.4 and (hopefully, at some point) multi-version support. In part the
guides portion of clojuredocs (the organization)
will follow the clojurewerkz.org projects model which is known to work well
and even produced some tools
we can easily reuse and adapt.
readevalprintlove looks like a fancy playground so far.
DOh! (and this is one of my favorite TED talks!) Indeed, I didn't mean to state what was going to done before it was done - just that I was happy to see people pick up the torch.
Regarding REPL Love - I think the two projects are indeed sufficiently different and I think they complement each other quite well. It actually excites me to see both projects happening right now. It speaks to the character of the individuals that make up this community.
> readevalprintlove looks like a fancy playground so far.
You say that as if it's a bad thing. I'm of the opinion that these
kinds of efforts should have a low barrier to contribution and be fun.
It's difficult to motivate people to perform a thankless task, so it
should seem like play as much as possible along the way.
> Starting two different projects at the same time with almost the same
> purpose seems a waste of efforts...
> Wouldn't it be better for readevalprintlove and clojuredocs to join forces
> from the beginning?
All information should be freely available, so the sharing aspect is
present from the start. As for wasted effort I would say that any
effort in this direction is a plus, but your point is valid. We're all
friends right? It'll work out for the best for Clojure I'm sure.
On Thu, Oct 4, 2012 at 7:48 PM, Michael Fogus <mefo...@gmail.com> wrote:
> > readevalprintlove looks like a fancy playground so far.
> You say that as if it's a bad thing. I'm of the opinion that these
> kinds of efforts should have a low barrier to contribution and be fun.
> It's difficult to motivate people to perform a thankless task, so it
> should seem like play as much as possible along the way.
On Thu, Oct 4, 2012 at 6:48 PM, Michael Fogus <mefo...@gmail.com> wrote:
>> readevalprintlove looks like a fancy playground so far.
> You say that as if it's a bad thing. I'm of the opinion that these
> kinds of efforts should have a low barrier to contribution and be fun.
> It's difficult to motivate people to perform a thankless task, so it
> should seem like play as much as possible along the way.
My co-workers and I were debating this at work the other day. My
worldview is that it takes hard work to learn good things, but at the
same time it can be fun and even brief. Kent Dybvig's _The Scheme
Programming Language_ is a superb example. The other four developers
said that I'm the 20% and that approach is too pedagogical, that you
need to make everything constant entertainment. _Practical Common
Lisp_ was cited as an example.
I'm just glad there are options.
I'm still looking for Clojure materials that go to this level of detail:
> You say that as if it's a bad thing. I'm of the opinion that these
> kinds of efforts should have a low barrier to contribution and be fun.
My apologies, I did not imply that it is a bad thing, only that it is not
entirely clear what direction the project
will take. While for CDS it is pretty clear (at least to people who have
started it).
While we are at this fun stuff, can we also make the CA submission process
fun?
-- MK
>> You say that as if it's a bad thing. I'm of the opinion that these
>> kinds of efforts should have a low barrier to contribution and be fun.
> My apologies, I did not imply that it is a bad thing, only that it is not
> entirely clear what direction the project
> will take. While for CDS it is pretty clear (at least to people who have
> started it).
> While we are at this fun stuff, can we also make the CA submission process
> fun?
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clojure@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+unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
2012/10/5 Andy Fingerhut <andy.finger...@gmail.com>
> Michael, are these specific plans described anywhere that we could read?
> Or would you be able to describe them briefly?
> Curious to know what is planned there.
We are currently migrating CDS to the same toolchain clojurewerkz.org sites
use. Doing so will let us
not reinvent some wheels and it's the devil we know. This should be done
early next week.
The plan is to have a flat list of guides organized in 3 groups:
* Tutorials
* Language guides
* Tools & Ecosystem guides
There are no grand plans for the guides, just write, edit, deploy, gather
feedback, rinse and repeat.
We already have a list of guides to help people who want to contribute pick
a topic. An example of such TOC:
And then there is the API reference part. The goal is to rewrite
clojuredocs.org source parser to produce
JSON and migrate DB schema to support multiple versions. Ideally,
clojuredocs.org will be Clojure end to end.
But this will take a while and the reference part is not nearly as bad as
it is with the guides and tutorials.
CDS will not have the reference part. It will link to existing resources,
be it clojuredocs.org or something else.
I want to stress that one of the major goals (maybe the most important) of
all this is to be contributor-friendly. Contributing a spelling fix or
improving wording of something should take minutes, not weeks. Everybody
should
be able to quickly submit an improvement. Documentation guides on the
language is its face for potential
users and there is no shortage of smart people who *want* to improve the
situation with the docs, but currently
find it too inconvenient or have no opportunity to do so because of the CA
submission process.
There will be something to show next week. I hope this answers your
question.
-- MK
why don't you use advantage of html and split the site into two panes on left the table of content in hiperlink form and on the right the content reloaded on clickin in link in toc also use numbers for chapters and subchapters dont use bullets for lists, its harder to make references also add disqus.com to allow for comments (like on mysql docs) and your site will be at least useful for someone and treated as reference doc site
+1 to lowering the barrier to entry for contributing to the community.
One of the much lauded features of Git is that it can be used to create a "network of trust". In principle this means you can open your repo up to anyone, but by being choosy about the pull requests you accept you can control what's going to get in.
This is perfect for something like documentation.
Also, as it's been said before, a pen and paper CA is a pain.
On Friday, 5 October 2012 08:26:39 UTC-5, Mayank Jain wrote:
> On Fri, Oct 5, 2012 at 6:54 PM, Michael Klishin <michael....@gmail.com<javascript:> > > wrote:
>> 2012/10/5 Michael Fogus <mef...@gmail.com <javascript:>>
>>> You say that as if it's a bad thing. I'm of the opinion that these >>> kinds of efforts should have a low barrier to contribution and be fun.
>> My apologies, I did not imply that it is a bad thing, only that it is not >> entirely clear what direction the project >> will take. While for CDS it is pretty clear (at least to people who have >> started it).
>> While we are at this fun stuff, can we also make the CA submission >> process fun?
>> -- >> 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<javascript:> >> 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 <javascript:> >> For more options, visit this group at >> http://groups.google.com/group/clojure?hl=en
This insistence on the so-called "CA pain" seems to me overemphasized.
It's a one shot process.
Even if it takes 4 weeks for the paper to reach its destination, it does not
prevent anyone from starting to work on some contribution. The CA
needs to be in by the time the work is about to get published, not by the time
you start to contribute.
My writing is horrible, worst than a doctor, I hate filling forms by hand but I was able to fill the CA, stamp it and drop it in the mailbox in less than 10 mns.
I live in Canada close to the US, I can understand the frustration if you have to drop
by your local post office if it needs to get stamped over there but one time
processes like this rarely benefit from an optimization.
I would be surprised that we end up with >250,000 contributors in the next
3 years. There is simply not enough Clojure wired brains out there to get to numbers like the above.
If it ever happens, you can bet than Clojure Core will come out
with something to avoid being flooded by papers if it is legally feasible.
Laws in many countries have been slow to move to consider
electronic formats as legally binding documents.
This may well be why a written CA is needed considering that contributors come
different countries. What may seem obviously legal in one country may not be legal
at all in another.
Better documentation is to me by far a more urgent priority to attract newbies
than allowing CAs to be submitted electronically given the legal fees involved just
to get an opinion about its feasability.
> +1 to lowering the barrier to entry for contributing to the community.
> One of the much lauded features of Git is that it can be used to create a > "network of trust". In principle this means you can open your repo up to > anyone, but by being choosy about the pull requests you accept you can > control what's going to get in.
> This is perfect for something like documentation.
> Also, as it's been said before, a pen and paper CA is a pain.
> On Friday, 5 October 2012 08:26:39 UTC-5, Mayank Jain wrote:
> > On Fri, Oct 5, 2012 at 6:54 PM, Michael Klishin <michael....@gmail.com<javascript:>
> > > wrote:
> >> 2012/10/5 Michael Fogus <mef...@gmail.com <javascript:>>
> >>> You say that as if it's a bad thing. I'm of the opinion that these
> >>> kinds of efforts should have a low barrier to contribution and be fun.
> >> My apologies, I did not imply that it is a bad thing, only that it is not > >> entirely clear what direction the project
> >> will take. While for CDS it is pretty clear (at least to people who have > >> started it).
> >> While we are at this fun stuff, can we also make the CA submission > >> process fun?
> >> -- > >> 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<javascript:>
> >> 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 <javascript:>
> >> For more options, visit this group at
> >> http://groups.google.com/group/clojure?hl=en
> > -- > > Regards,
> > Mayank.
> -- > You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clojure@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+unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
--
Softaddicts<lprefonta...@softaddicts.ca> sent by ibisMail from my ipad!
The CA process isn't what stops me from contributing, the post a patch
to Jira is what seems broken to me. I don't even remember how to
create a patch. Clojure is on github - we live in a fork & pull
request world, it's time for Clojure to get on board with that.
I once noticed that a Clojure fn didn't have a type hint on a return
value. Adding ^String made a substantial performance difference. Not
knowing the process, I forked, and did a pull request. I got this
response:
"Clojure projects cannot accept pull requests so all issues need to be
logged in the appropriate JIRA project and patches can be accepted
from people who have a signed Contributor's Agreement on file:
<lprefonta...@softaddicts.ca> wrote:
> This insistence on the so-called "CA pain" seems to me overemphasized.
> It's a one shot process.
> Even if it takes 4 weeks for the paper to reach its destination, it does not
> prevent anyone from starting to work on some contribution. The CA
> needs to be in by the time the work is about to get published, not by the time
> you start to contribute.
> My writing is horrible, worst than a doctor, I hate filling forms by hand but I
> was able to fill the CA, stamp it and drop it in the mailbox in less than 10 mns.
> I live in Canada close to the US, I can understand the frustration if you have to drop
> by your local post office if it needs to get stamped over there but one time
> processes like this rarely benefit from an optimization.
> I would be surprised that we end up with >250,000 contributors in the next
> 3 years. There is simply not enough Clojure wired brains out there to get to
> numbers like the above.
> If it ever happens, you can bet than Clojure Core will come out
> with something to avoid being flooded by papers if it is legally feasible.
> Laws in many countries have been slow to move to consider
> electronic formats as legally binding documents.
> This may well be why a written CA is needed considering that contributors come
> different countries. What may seem obviously legal in one country may not be legal
> at all in another.
> Better documentation is to me by far a more urgent priority to attract newbies
> than allowing CAs to be submitted electronically given the legal fees involved just
> to get an opinion about its feasability.
> Luc P.
>> +1 to lowering the barrier to entry for contributing to the community.
>> One of the much lauded features of Git is that it can be used to create a
>> "network of trust". In principle this means you can open your repo up to
>> anyone, but by being choosy about the pull requests you accept you can
>> control what's going to get in.
>> This is perfect for something like documentation.
>> Also, as it's been said before, a pen and paper CA is a pain.
>> On Friday, 5 October 2012 08:26:39 UTC-5, Mayank Jain wrote:
>> > On Fri, Oct 5, 2012 at 6:54 PM, Michael Klishin <michael....@gmail.com<javascript:>
>> > > wrote:
>> >> 2012/10/5 Michael Fogus <mef...@gmail.com <javascript:>>
>> >>> You say that as if it's a bad thing. I'm of the opinion that these
>> >>> kinds of efforts should have a low barrier to contribution and be fun.
>> >> My apologies, I did not imply that it is a bad thing, only that it is not
>> >> entirely clear what direction the project
>> >> will take. While for CDS it is pretty clear (at least to people who have
>> >> started it).
>> >> While we are at this fun stuff, can we also make the CA submission
>> >> process fun?
>> >> --
>> >> 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<javascript:>
>> >> 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 <javascript:>
>> >> For more options, visit this group at
>> >> http://groups.google.com/group/clojure?hl=en
>> > --
>> > Regards,
>> > Mayank.
>> --
>> You received this message because you are subscribed to the Google
>> Groups "Clojure" group.
>> To post to this group, send email to clojure@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+unsubscribe@googlegroups.com
>> For more options, visit this group at
>> http://groups.google.com/group/clojure?hl=en > --
> Softaddicts<lprefonta...@softaddicts.ca> sent by ibisMail from my ipad!
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clojure@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+unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
On Saturday, October 6, 2012 12:03:00 PM UTC-4, Jay Fields wrote:
> I once noticed that a Clojure fn didn't have a type hint on a return > value. Adding ^String made a substantial performance difference. Not > knowing the process, I forked, and did a pull request. I got this > response:
> "Clojure projects cannot accept pull requests so all issues need to be > logged in the appropriate JIRA project and patches can be accepted > from people who have a signed Contributor's Agreement on file:
I do not agree at all with you. Any piece of software that gets used widely
needs to be maintained with some formal process otherwise there's no way
to insure consistency of future releases. It gets worse as you increase
the # of people that can modify code.
Tickets may seem to you as overhead but it's a decent way to track issues and
fixes according to release plans.
Looking at a bunch of commits in git is limited compared to dedicated
ticket logging solutions like Jira. Providing patches attached to the ticket links
the ticket to the code in git is much more usable.
Refusing pull requests is a way to force issues to be logged in Jira.
The main entrance gate is in Jira, not the other way around.
Clojure is not the only open source projects driven by a ticket reporting
system.
This may look as overhead to you but it is still lighter than similar
processes in many software businesses.
You can report the kind of problems you highlighted on the mailing list so at least others can take ownership of the issue if you do not feel
inclined to post it in Jira.
> The CA process isn't what stops me from contributing, the post a patch
> to Jira is what seems broken to me. I don't even remember how to
> create a patch. Clojure is on github - we live in a fork & pull
> request world, it's time for Clojure to get on board with that.
> I once noticed that a Clojure fn didn't have a type hint on a return
> value. Adding ^String made a substantial performance difference. Not
> knowing the process, I forked, and did a pull request. I got this
> response:
> "Clojure projects cannot accept pull requests so all issues need to be
> logged in the appropriate JIRA project and patches can be accepted
> from people who have a signed Contributor's Agreement on file:
> Which is informative and correct, but, do you really think I'm going
> to go through that trouble? If you said yes, you're wrong.
> Cheers, Jay
> On Sat, Oct 6, 2012 at 11:40 AM, Softaddicts
> <lprefonta...@softaddicts.ca> wrote:
> > This insistence on the so-called "CA pain" seems to me overemphasized.
> > It's a one shot process.
> > Even if it takes 4 weeks for the paper to reach its destination, it does not
> > prevent anyone from starting to work on some contribution. The CA
> > needs to be in by the time the work is about to get published, not by the time
> > you start to contribute.
> > My writing is horrible, worst than a doctor, I hate filling forms by hand but I
> > was able to fill the CA, stamp it and drop it in the mailbox in less than 10 mns.
> > I live in Canada close to the US, I can understand the frustration if you have to drop
> > by your local post office if it needs to get stamped over there but one time
> > processes like this rarely benefit from an optimization.
> > I would be surprised that we end up with >250,000 contributors in the next
> > 3 years. There is simply not enough Clojure wired brains out there to get to
> > numbers like the above.
> > If it ever happens, you can bet than Clojure Core will come out
> > with something to avoid being flooded by papers if it is legally feasible.
> > Laws in many countries have been slow to move to consider
> > electronic formats as legally binding documents.
> > This may well be why a written CA is needed considering that contributors come
> > different countries. What may seem obviously legal in one country may not be legal
> > at all in another.
> > Better documentation is to me by far a more urgent priority to attract newbies
> > than allowing CAs to be submitted electronically given the legal fees involved just
> > to get an opinion about its feasability.
> > Luc P.
> >> +1 to lowering the barrier to entry for contributing to the community.
> >> One of the much lauded features of Git is that it can be used to create a
> >> "network of trust". In principle this means you can open your repo up to
> >> anyone, but by being choosy about the pull requests you accept you can
> >> control what's going to get in.
> >> This is perfect for something like documentation.
> >> Also, as it's been said before, a pen and paper CA is a pain.
> >> On Friday, 5 October 2012 08:26:39 UTC-5, Mayank Jain wrote:
> >> > On Fri, Oct 5, 2012 at 6:54 PM, Michael Klishin <michael....@gmail.com<javascript:>
> >> > > wrote:
> >> >> 2012/10/5 Michael Fogus <mef...@gmail.com <javascript:>>
> >> >>> You say that as if it's a bad thing. I'm of the opinion that these
> >> >>> kinds of efforts should have a low barrier to contribution and be fun.
> >> >> My apologies, I did not imply that it is a bad thing, only that it is not
> >> >> entirely clear what direction the project
> >> >> will take. While for CDS it is pretty clear (at least to people who have
> >> >> started it).
> >> >> While we are at this fun stuff, can we also make the CA submission
> >> >> process fun?
> >> >> --
> >> >> 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<javascript:>
> >> >> 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 <javascript:>
> >> >> For more options, visit this group at
> >> >> http://groups.google.com/group/clojure?hl=en
> >> > --
> >> > Regards,
> >> > Mayank.
> >> --
> >> You received this message because you are subscribed to the Google
> >> Groups "Clojure" group.
> >> To post to this group, send email to clojure@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+unsubscribe@googlegroups.com
> >> For more options, visit this group at
> >> http://groups.google.com/group/clojure?hl=en > > --
> > Softaddicts<lprefonta...@softaddicts.ca> sent by ibisMail from my ipad!
> > --
> > You received this message because you are subscribed to the Google
> > Groups "Clojure" group.
> > To post to this group, send email to clojure@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+unsubscribe@googlegroups.com
> > For more options, visit this group at
> > http://groups.google.com/group/clojure?hl=en
> -- > You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clojure@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+unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
--
Softaddicts<lprefonta...@softaddicts.ca> sent by ibisMail from my ipad!
I don't always remember how to create a patch, either, but I do remember where to go to get the short instructions to do so in case I forget. In case you are curious, the process for creating a patch is documented here, under the heading "Developing and submitting patches to Clojure and Clojure Contrib". This page is linked to from the contributing and patches pages you give links for in your message.
> The CA process isn't what stops me from contributing, the post a patch
> to Jira is what seems broken to me. I don't even remember how to
> create a patch. Clojure is on github - we live in a fork & pull
> request world, it's time for Clojure to get on board with that.
> I once noticed that a Clojure fn didn't have a type hint on a return
> value. Adding ^String made a substantial performance difference. Not
> knowing the process, I forked, and did a pull request. I got this
> response:
> "Clojure projects cannot accept pull requests so all issues need to be
> logged in the appropriate JIRA project and patches can be accepted
> from people who have a signed Contributor's Agreement on file:
I would agree that the CA pain is overemphasized if the submitter lives in the USA or Canada. It isn't difficult at all.
I have since heard that to get a letter from Russia to the USA, there are several methods, but they range from inexpensive-but-can-take-months-and-are-unreliable, to quick-and-reliable-but-$200.
Those are significantly higher barriers than for developers based in the USA and Canada, where it is a 44 cent stamp and a few days to get there quite reliably.
> This insistence on the so-called "CA pain" seems to me overemphasized.
> It's a one shot process.
> Even if it takes 4 weeks for the paper to reach its destination, it does not
> prevent anyone from starting to work on some contribution. The CA
> needs to be in by the time the work is about to get published, not by the time
> you start to contribute.
> My writing is horrible, worst than a doctor, I hate filling forms by hand but I > was able to fill the CA, stamp it and drop it in the mailbox in less than 10 mns.
> I live in Canada close to the US, I can understand the frustration if you have to drop
> by your local post office if it needs to get stamped over there but one time
> processes like this rarely benefit from an optimization.
> I would be surprised that we end up with >250,000 contributors in the next
> 3 years. There is simply not enough Clojure wired brains out there to get to > numbers like the above.
> If it ever happens, you can bet than Clojure Core will come out
> with something to avoid being flooded by papers if it is legally feasible.
> Laws in many countries have been slow to move to consider
> electronic formats as legally binding documents.
> This may well be why a written CA is needed considering that contributors come
> different countries. What may seem obviously legal in one country may not be legal
> at all in another.
> Better documentation is to me by far a more urgent priority to attract newbies
> than allowing CAs to be submitted electronically given the legal fees involved just
> to get an opinion about its feasability.
> I do not agree at all with you. Any piece of software that gets used widely
> needs to be maintained with some formal process otherwise there's no way
> to insure consistency of future releases. It gets worse as you increase
> the # of people that can modify code.
Sorry, have you tried reading what people who complain about the CA
submission process
actually complain about? They do not complain about having the CA. They are
not eager to
jump in working on the language. They complain about being shut out from
contributing *anything*
(including documentation and updates to libraries like data.json) by the
requirement
that CA has to be mailed in paper, in the year 2012.
We have posted examples of projects and corporations that accept PDFs over
email:
Oracle, OpenJDK, Apache Software Foundation, Neo4J. Scala and Opscode found
more creative solutions
that use OAuth and similar techniques.
As far as the number of language designers, I think there is little
disagreement that the number Clojure has right now
(1 or 2, with some influence from maybe 5-6 more) is about optimal. There
is much more to success and adoption
of Clojure than just language features, design, consistency and other
things that may benefit from this "tight grip".
> Tickets may seem to you as overhead but it's a decent way to track issues
> and
> fixes according to release plans.
> Looking at a bunch of commits in git is limited compared to dedicated
> ticket logging solutions like Jira. Providing patches attached to the
> ticket links
> the ticket to the code in git is much more usable.
> Refusing pull requests is a way to force issues to be logged in Jira.
> The main entrance gate is in Jira, not the other way around.
This is all handwaving. You can use a bug tracker and plan the hell out of
releases on github.
Many projects do so. However, how quickly contributions are accepted
matters a lot for smaller improvements
like the Jay's example.
Go take a look at repositories under github.com/clojure, you will find
10-20 people contributing small improvements
and being rejected every single month. Do you really think most of them
actually will come back? Do you have the
guts to say they should not be considered valuable members of the community
because of that?
If you make something difficult or time consuming, people will do it less.
> Clojure is not the only open source projects driven by a ticket reporting
> system.
> This may look as overhead to you but it is still lighter than similar
> processes in many software businesses.
> You can report the kind of problems you highlighted on the mailing list
> so at least others can take ownership of the issue if you do not feel
> inclined to post it in Jira.
It's about even having a chance to participate. JIRA and patches are
annoying to anyone who has used github for
at least a few months but it is not really a big deal to anyone I know who
is unhappy about the situation.
It is all about the fact that if you do not live in North America or
western Europe, you are shut out of the game.
And the reason why CDS distances itself from Clojure/core and the existing
process as far as possible is to at least give Clojure users
a chance to help with the biggest pain point: documentation.
-- MK
> The CA process isn't what stops me from contributing, the post a patch
> to Jira is what seems broken to me. I don't even remember how to
> create a patch. Clojure is on github - we live in a fork & pull
> request world, it's time for Clojure to get on board with that.
Lots of people eat fast food as well.
> I once noticed that a Clojure fn didn't have a type hint on a return
> value. Adding ^String made a substantial performance difference. Not
> knowing the process, I forked, and did a pull request. I got this
> response:
> "Clojure projects cannot accept pull requests so all issues need to be
> logged in the appropriate JIRA project and patches can be accepted
> from people who have a signed Contributor's Agreement on file:
> Which is informative and correct, but, do you really think I'm going
> to go through that trouble? If you said yes, you're wrong.
I'm responding to Jay here (because we're friends and I know he can take it:), but this is for everyone who feels similarly:
I prefer patches. I understand some people don't. Can't we just agree to disagree? Why must this be repeatedly gone over?
I'm not sure what value you think a message like this is going to provide to the thousands of participants in this list. Does it make you feel better? It will not convince me otherwise.
Here's how I see it. I've spent at least 100,000x as much time on Clojure as you will in the difference between producing a patch vs a pull request. The command is:
There are two sides to change management - production/submission, and management/assessment/application/other-stewardship. People who argue that the process should be optimized for ease of submission are simply wrong. What if I said patches were twice as efficient for me to assess and manage as pull requests? (it's more than that) Do the math and figure out how the effort should best be distributed.
I don't think asking for patches is asking too much, and I truly appreciate the people who are going to the extra effort. And, I respect the fact that people disagree, and they might decide not to participate as a result. However, I don't need to justify my decision over and over. How about a little consideration for me, and the other list participants? There is a real diluting effect of get-it-off-my-chest messages such as these on the value of the list and the utility of reading it for myself and others.
Sometimes it's better to save it for your bartender :)
