Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
Phil Hagelberg p...@hagelb.org writes: Michael Klishin writes: It wasn't immediately clear to me, but it makes sense, given how short the MIT license is. What licenses does it make sense to recommend? Given that Clojure libraries must be compatible with Clojure's license, the GPL is ruled out. I used to think that this was true, but actually I think it is not. The GPL specifically talks about standard interfaces. So you *could* build a library or a tool that used GPL, and linking through to clojure.core. The clojure.core libraries would not need to be GPL, and the incompatability with EPL would not matter. This would not extent to all libraries, though. So, for example, I would not link a GPL library to https://github.com/technomancy/robert-hooke legally (you could but that's a different issue!). I recommend the EPL; it's what you get when you run `lein new myproject`, and I feel like Rich made a pragmatic choice with a license that is copyleft without being virally so. To my mind, choice of law clauses are poor. Why would I want to go to New York to assert my legal rights for my code? If there is some reason you want to avoid copyleft, (corporate paranoia, etc.) then the Apache license seems like the best bet among non-copyleft ones, though the requirement that it be included in *every* single file is very annoying. Just the boilerplate surely? Phil -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
In explaining Clojure, for example, you'll find that the motivations are usually brought forth in a Rich Hickey talk. He talks about the motivations for immutable data structures, for time and state, for carrying metadata, and so much more. None of this is in the code base. I can sympathize with this point of view. I also think that Github wikis are a double-edged sword. They're convenient when you're exploring the repository in your browser, and a pain when you're not. It believe it would be a great first step to take the content from the Clojure website (where Rich has explained immutability, state, persistent data structures, etc) and store them as some variant of plain text (org mode?) in the repo itself. This is precisely the approach taken by git, for instance. In its Documentation folder you can find not only man page style docs, but also docs explaining data structures, motivations, things only contributors need to care about and so on. Tools can the process these files as well and make websites or wikis out of them. This is not quite the same as literate programming, obviously, but it seems to me to be an easily achievable first step for any project, including Clojure core, with potential benefits that surpass the effort required to make it happen. P.S. Sorry if the quoting is off...typing from a phone. -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
Good stuff and I really enjoyed reading it too. Thanks, J On Saturday, April 20, 2013 1:11:59 AM UTC-3, Michael Klishin wrote: 2013/4/20 u1204 da...@axiom-developer.org javascript: There is a HUGE gulf between the user documentation and maintaining the code. Just like there is a huge difference between using a car and maintaining a car. There are two things to consider: * Your audience is other developers. * Most projects are relatively small and straightforward compared to the Clojure compiler. My point was at least try to find a new maintainer. Don't let it rot. There is a blog post in the community that I'm referring to between the lines. It won't be hard to figure out which one. The idea is, don't do that. Don't turn your project into abandonware if you no longer want to maintain it well. Projects such as ring, clj-time, clj-http have found new maintainers and those people do a great job with them. -- MK http://github.com/michaelklishin http://twitter.com/michaelklishin -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
Michael Klishin writes: My point was at least try to find a new maintainer. Don't let it rot. I see where you're coming from, but there's definitely a place for phasing out a project gracefully. The majority of projects will have no users outside the original author, and that's fine. There are even cases where it's best for a widely-used library to pass on the torch and have its users migrate to an alternative that's widely understood to be superior. (clojure-json, noir, even monolithic clojure-contrib arguably, etc) So it's not quite as black and white as the post makes it sound. However, just spluttering out and going dark is obviously not what you want; if there's a transition to be done it must be clearly communicated. Anyway, everything else about the post appears solid except for one thing. It recommends the MIT license, which has no patent protection whatsoever; this could open you and your users up to liabilities in ways that are impossible to predict given that the United States Patent Office's tendency to grant patents without examining them first. So I strongly caution against using licenses which don't include patent grant clauses unless it's for throw-away code. While the Apache license can be annoying in all the boilerplate it requires, at least it doesn't have this problem. -Phil pgpyizhRbgG5I.pgp Description: PGP signature
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
On Friday, April 19, 2013 9:37:52 PM UTC-4, da...@axiom-developer.org wrote: TL:DR Write ideas for humans around your code or it will die. Explain, don't document. Excellent post, Tim. Thanks for writing it all up. Though, I tend to think that documenting is the same as explaining (what good is documentation if it doesn't explain?). I mean that you need to write words that communicate IDEAS from human to human. Real sentences with real words that you would say to someone looking at the code. If you don't communicate the idea embodied in a piece of code in words humans can understand, you are writing dead code for yourself. Yes. If you want your code to LIVE, write WORDS for other HUMANS. Lots of words. More words than code. Think of the difference between a math reference textbook and a regular math book. Words. One minor point to add: It's easy to write too much. To meander. Concision is hard. I strongly recommend literate programming but feel free to ignore that. Write words. Hm. Maybe I should ask this off-list, but, in a nutshell, is literate programming: 1. put possibly-out-of-order specially-marked (with an id) code snippets throughout your doc, 2. also put an *ordered* listing of all the id's somewhere in your doc, 3. use tools to find that ordered list of ids, then extract the snippets, put them in order, and glue them all together so they can be compiled/run? Thanks, ---John -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
TL:DR Write ideas for humans around your code or it will die. Explain, don't document. Excellent post, Tim. Thanks for writing it all up. Though, I tend to think that documenting is the same as explaining (what good is documentation if it doesn't explain?). The word explain is semantically the same as document to most people but not to the programmer community. I chose the word explain carefully. The word document has negative emotional overtones for programmers. It usually implies fulfilling checklist requirements like Does it have a Javadoc stanza?. I just gave a talk at the WriteTheDocs conference. People who do this for a living (documentarians) were proposing creating games like document like a pirate day to entice programmers to document. Personally, I see documentation as a mark of a professional. Rise to the standard or retire into management. Tim Daly Curmudgeon at Large -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
On Sat, Apr 20, 2013 at 11:51 AM, u1204 d...@axiom-developer.org wrote: The word explain is semantically the same as document to most people but not to the programmer community. FWIW, I think the situation is closer to precisely the opposite. If I ask you to document what you do today, what will you do? Hold on to your receipts? Log mileage in your car? Compare being asked to explain what you do today. -- Ben Wolfson Human kind has used its intelligence to vary the flavour of drinks, which may be sweet, aromatic, fermented or spirit-based. ... Family and social life also offer numerous other occasions to consume drinks for pleasure. [Larousse, Drink entry] -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
Hm. Maybe I should ask this off-list, but, in a nutshell, is literate programming: I feel this is an on-list topic (although it is obvious that I'm an edge-case fanatic). Clojure is trying to introduce a lot of new ideas that change how programming is done. It is an edge-case community. I'm trying to change the standard to which Clojure programs are written by introducing a shiny, new edge-case idea (from the 1960s). High quality Clojure programs should be literate. 1. put possibly-out-of-order specially-marked (with an id) code snippets throughout your doc, 2. also put an *ordered* listing of all the id's somewhere in your doc, 3. use tools to find that ordered list of ids, then extract the snippets, put them in order, and glue them all together so they can be compiled/run? Programs are written in a certain order because the compiler requires it. For instance, some code in Clojure is required to occur before others (e.g. importing code, pre-compiling java). If you try to explain various ideas and illustrate them with the REAL code that will be EXECUTED you need to be able to arrange the code in human order, not machine order. Most documentation tools (javadoc, doxygen, org-mode, etc.) associate the explanation with the code rather than associate the code with the explanation. This prioritizes the machine over the human. But the point of explanation (not documentation) is to communicate to a human. These tools miss the point. A literate program emphasizes human communication over machine communication. Thus code is introduced in human order. Look at the book Lisp in Small Pieces to get an idea of how well it can be done. A good explanation starts with motivation. Any writing course emphasizes finding the motivation for the character's actions. In explaining Clojure, for example, you'll find that the motivations are usually brought forth in a Rich Hickey talk. He talks about the motivations for immutable data structures, for time and state, for carrying metadata, and so much more. None of this is in the code base. If you don't know about immutable data structures then the code that implements lists is completely inefficient nonsense. It would traditionally be seen as hanging onto nodes that are dead for no apparent reason. Lacking the motivating explanation any good programmer would optimize away all the cruft, breaking Clojure. So to explain something to a human you need to motivate it. To motivate it you need to arrange the thoughts in the proper order. In a literate program the thoughts are reduced to practice by showing the actual code inline. This implies the ability to re-arrange code to suit the human. Ultimately, think of writing code as though you were writing a book. Let the code fall where it fits best in the chapter where it belongs. Now you have a work of literature that communicates to a human. That, I claim, will keep your program alive after you abandon it. Give someone your program. Send them to Hawaii on a 2 week, all expense paid vacation. If, when the return, they can maintain and modify the code as well as the original developers then you have written a literate program. (aka the Hawaii test). Tim Daly -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
On Saturday, April 20, 2013 11:52:29 AM UTC-4, Phil Hagelberg wrote: Anyway, everything else about the post appears solid except for one thing. It recommends the MIT license, which has no patent protection whatsoever; this could open you and your users up to liabilities in ways that are impossible to predict given that the United States Patent Office's tendency to grant patents without examining them first. So I strongly caution against using licenses which don't include patent grant clauses unless it's for throw-away code. While the Apache license can be annoying in all the boilerplate it requires, at least it doesn't have this problem. Glad you brought this up, Phil. My rules of thumb are: * if you want copyleft, *and* wish to require those incorporating your code into their own program to also copyleft, use GPL, * if you want copyleft for just your own code, use LGPL, * otherwise, if you want a more permissive license, use Apache 2. I think those three choices cover the bases pretty well. ---John -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
The word explain is semantically the same as document to most people but not to the programmer community. FWIW, I think the situation is closer to precisely the opposite. If I ask you to document what you do today, what will you do? Hold on to your receipts? Log mileage in your car? Compare being asked to explain what you do today. Precisely my point (unless I miss your point). If I ask you to document your trip you'll hand me receipts. If I ask you to explain your trip you need to tell me why you went, what you did, and why I care. Current documentation tools and standards attach an explanation to the trip receipt (I ate here). What we need to keep a program alive is the explanation of why you did it, what you did (the inline code), and why I care. Tim Daly -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
On Saturday, April 20, 2013 3:35:04 PM UTC-4, da...@axiom-developer.org
wrote:
but, in a nutshell, is literate programming:
1. put possibly-out-of-order specially-marked (with an id) code snippets
throughout your doc,
2. also put an *ordered* listing of all the id's somewhere in your doc,
3. use tools to find that ordered list of ids, then extract the
snippets,
put them in order, and glue them all together so they can be
compiled/run?
Programs are written in a certain order because the compiler
requires it. {snip}
If you try to explain various ideas and illustrate them with the
REAL code that will be EXECUTED you need to be able to arrange
the code in human order, not machine order.
...
Ok. So, if possibly-out-of-order (in my message above) means in human
order, is my nutshell summary of how literate programming works correct?
--
--
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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
On Sat, Apr 20, 2013 at 12:44 PM, u1204 d...@axiom-developer.org wrote: The word explain is semantically the same as document to most people but not to the programmer community. FWIW, I think the situation is closer to precisely the opposite. If I ask you to document what you do today, what will you do? Hold on to your receipts? Log mileage in your car? Compare being asked to explain what you do today. Precisely my point (unless I miss your point). If I ask you to document your trip you'll hand me receipts. If I ask you to explain your trip you need to tell me why you went, what you did, and why I care. My point was that most people will do the same (provide documents vs. contextualize the actions). -- Ben Wolfson Human kind has used its intelligence to vary the flavour of drinks, which may be sweet, aromatic, fermented or spirit-based. ... Family and social life also offer numerous other occasions to consume drinks for pleasure. [Larousse, Drink entry] -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
2013/4/20 Phil Hagelberg p...@hagelb.org Anyway, everything else about the post appears solid except for one thing. It recommends the MIT license, which has no patent protection whatsoever; this could open you and your users up to liabilities in ways that are impossible to predict given that the United States Patent Office's tendency to grant patents without examining them first. So I strongly caution against using licenses which don't include patent grant clauses unless it's for throw-away code. While the Apache license can be annoying in all the boilerplate it requires, at least it doesn't have this problem. Ii wasn't immediately clear to me, but it makes sense, given how short the MIT license is. What licenses does it make sense to recommend? I'll update the post because, indeed, we [maintainers] can't ignore patent protection. -- MK http://github.com/michaelklishin http://twitter.com/michaelklishin -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
but, in a nutshell, is literate programming:
1. put possibly-out-of-order specially-marked (with an id) code snippets
throughout your doc,
2. also put an *ordered* listing of all the id's somewhere in your doc,
3. use tools to find that ordered list of ids, then extract the
snippets,
put them in order, and glue them all together so they can be
compiled/run?
Programs are written in a certain order because the compiler
requires it. {snip}
If you try to explain various ideas and illustrate them with the
REAL code that will be EXECUTED you need to be able to arrange
the code in human order, not machine order.
...
Ok. So, if possibly-out-of-order (in my message above) means in human
order, is my nutshell summary of how literate programming works correct?
As a technology, yes. See
http://daly.axiom-developer.org/clojure.pdf
http://daly.axiom-developer.org/clojure.pamphlet
You'll notice that the Makefile extracts all of Clojure and all of
the tests back to the directory structure required by the compiler.
The code is introduced out of order in the document.
My only hesitation is that it is important not to equate literate
programming with a particular detail. I fear that some bright spot
will add out of order to org-mode or javadoc and call it
literate programming, completely missing the point.
Tim Daly
--
--
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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
Michael Klishin writes: It wasn't immediately clear to me, but it makes sense, given how short the MIT license is. What licenses does it make sense to recommend? Given that Clojure libraries must be compatible with Clojure's license, the GPL is ruled out. I recommend the EPL; it's what you get when you run `lein new myproject`, and I feel like Rich made a pragmatic choice with a license that is copyleft without being virally so. If there is some reason you want to avoid copyleft, (corporate paranoia, etc.) then the Apache license seems like the best bet among non-copyleft ones, though the requirement that it be included in *every* single file is very annoying. However, I don't know of any other non-copyleft licenses which offer good patent protection. It's also worth noting that simply placing your software in the public domain is a bad idea since several European legal systems don't have a concept of public domain. If you want to completely disavow copyright on your work the best choice seems to be the creative-commons-based CC0, which places your work in the public domain where possible but contains exceptions for jurisdictions where it's not: https://creativecommons.org/publicdomain/zero/1.0/legalcode It should go without saying, but don't take this as legal advice, etc; please consult a legal professional before doing anything serious. -Phil -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
Nice write-up. I took some of your advice in releasing Windows.app today: - Put the source on github: https://github.com/sdegutis/windowsapp - Made the readme concise and clear - Added official docs right into the readme - No longer making any breaking changes to API - A friend posted about it on HN at https://news.ycombinator.com/item?id=5582371 (there's no mailing lists for Mac apps afaik) I think I covered each major point. -Steven On Fri, Apr 19, 2013 at 5:09 PM, Michael Klishin michael.s.klis...@gmail.com wrote: Month after month there are more and more people who announce their open source Clojure projects. This is great and we can't get enough of this. What is not great is how easy it often is to get started with some of the projects. Some of the most basic maintainer best practices are completely ignored, even though it often takes 3 minutes to fix some annoyances. So I wrote a little ranty blog post about what you can do to make your project awesome (or at least not suck). This also sums up what we've been trying to practice with ClojureWerkz. I hope it will help the Clojure community to be better library maintainers. Here it is: http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/ Now you have no excuse to not make your library totally awesome. -- MK http://github.com/michaelklishin http://twitter.com/michaelklishin -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out. -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
On Saturday, April 20, 2013 4:50:35 PM UTC-4, Phil Hagelberg wrote:
I recommend the EPL; it's what you get when you
run `lein new myproject`, and I feel like Rich made a pragmatic choice
with a license that is copyleft without being virally so.
My understanding is that copyleft roughly means, any changes you make to
the program (and then subsequently distribute) must be licensed under the
same terms as the original program.
The EPL only appears to be copyleft if the contributor *chooses* to
distribute the source code along with the object code. They can just as
well choose to distribute object code only.
(If you want to guarantee that your source code --- plus future
(distributed) modifications by others --- remains free, the LGPL would be a
good choice.)
If there is some reason you want to avoid copyleft, (corporate paranoia,
etc.) then the Apache license seems like the best bet among non-copyleft
ones, {snip}
Agreed.
--
--
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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
2013/4/21 Steven Degutis sbdegu...@gmail.com A friend posted about it on HN at https://news.ycombinator.com/item?id=5582371 (there's no mailing lists for Mac apps afaik) Steven, Sounds great! As for the mailing list, feel free to start a Google group for your project. It's pretty easy to manage and easy to join (many have Google accounts). -- MK http://github.com/michaelklishin http://twitter.com/michaelklishin -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
2013/4/21 Phil Hagelberg p...@hagelb.org It should go without saying, but don't take this as legal advice, etc; please consult a legal professional before doing anything serious. Definitely. I finally found the site I wanted to link to, TL;DR Legal: http://www.tldrlegal.com/ Great overview of OSS licenses in plain English. -- MK http://github.com/michaelklishin http://twitter.com/michaelklishin -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
On Sat, Apr 20, 2013 at 6:26 PM, Michael Klishin michael.s.klis...@gmail.com wrote: 2013/4/21 Phil Hagelberg p...@hagelb.org It should go without saying, but don't take this as legal advice, etc; please consult a legal professional before doing anything serious. Definitely. That's very nice in theory; in practice, though, many contributors to and initiators of open source projects are hobbyist programmers that can't afford to spend $500/hr consulting a lawyer each time they want to decide on a license for a project. -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
Ah, great idea. Thanks! -Steven On Sat, Apr 20, 2013 at 5:25 PM, Michael Klishin michael.s.klis...@gmail.com wrote: 2013/4/21 Steven Degutis sbdegu...@gmail.com A friend posted about it on HN at https://news.ycombinator.com/item?id=5582371 (there's no mailing lists for Mac apps afaik) Steven, Sounds great! As for the mailing list, feel free to start a Google group for your project. It's pretty easy to manage and easy to join (many have Google accounts). -- MK http://github.com/michaelklishin http://twitter.com/michaelklishin -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out. -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
2013/4/21 Cedric Greevey cgree...@gmail.com That's very nice in theory; in practice, though, many contributors to and initiators of open source projects are hobbyist programmers that can't afford to spend $500/hr consulting a lawyer each time they want to decide on a license for a project. I was referring to don't take this as legal advice, etc. -- MK http://github.com/michaelklishin http://twitter.com/michaelklishin -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
TL:DR Write ideas for humans around your code or it will die. Explain, don't document. Excellent blog post. However, you write Passing It Over At some point you may become disinterested in maintaining your project. Maybe you've moved on to a new job or no longer use your own project. Announce it on the mailing list, ask someone to take over your project. Sooner or later, someone will help. ... No, no, they won't. Why? Because, as you state earlier: Claim that people who are not willing to read the code to figure out even the most basic things are stupid and should flip burgers instead. There is a HUGE gulf between the user documentation and maintaining the code. Just like there is a huge difference between using a car and maintaining a car. I have been trying to reverse-engineer the code the Clojure code base. It uses red-black trees overlaid with a special immutable bit of design. It uses a lot of optimizations, some of which assume a 32-bit implementation. All without a comment anywhere. This is excellent code. It is also unmaintainable. (aside: the word you below is not aimed at the Michael, it is generic. I am following Michael's usage and style from his blog post.) /me drags out his street-worn soapbox. A crowd of two gathers. Nobody, nobody, and I say again, NOBODY is going to pick up your project. Why? Because they are going to look at your code pile and cringe. There are thousands of good projects in Sourceforge. Dead ones all. You too are writing dead code. You have written layer upon layer upon layer of improvements. You have added partially worked out features. You have removed the front-end code but left the old code there because it is backward compatible with version 0.0.0.1.2 which was never released. Just to add to the confusion, you have ported your code to a dozen platforms so you now have compiler switches, annotations, pragmas, special Makefile stanzas, and library dependencies that will fail at the next upgrade. You wrote autoconf macro scripts nobody understands. You have install scripts for linux, an installer for Windows, and one for the MAC. However, the linux script uses tools and directories that only exist on your machine. The Windows installer is for Windows NT, not Windows 8. The MAC installer doesn't check dependencies so it installs but fails to run. You need slime and leiningen but EVERYBODY has moved to smegle and buildme. Leiningen is now 7 versions ahead of your version with plugins that conflict with yours so your code no longer installs. But not a word of explanation on any of it. Your project is unmaintainable. /me stacks another soapbox, with guitar for a ballad. The crowd thins. Consider GNU Common Lisp, GCL. It was originally called Austin Kyoto Common Lisp, AKCL. It was written by Bill Schelter. Bill was a FANTASTIC open source developer. He sat at my desk writing AKCL. He found a bug in emacs, fetched a copy, fixed it, and uploaed a patched version. In 1985. He was hardcore. He wrote amazing code and never wrote comments, like all the greats. AKCL eventually became GCL. Bill is now dead. GCL was picked up by Camm Macquire. Camm is another of those precious-few heavy hackers and GCL was the basis of several huge projects. But Common Lisp has a real standard. Does your project? Have a hundred people written a standard for you? What is not explained is the crufty way that AKCL is built. It is built on top of Kyoto Common Lisp. The Kyoto Common Lisp (KCL) license says that you can't modify the code. It must be distributed unmodified. So Bill wrote a delta program and everything he wrote was in delta files off the original, unmodified KCL sources. Thus, to maintain AKCL source code you have to use patch files. Bill wrote valid patch files by hand. Diff -Naur valid files without diff. Hardcore enough for you? Can you read directories full of patch files? Oh, yeah, and since he was muttering to himself (aka programming) he didn't even explain why the code needed to be written as patches. The only reason I know is that I helped write pieces of AKCL and he sat in my office. Bill was an amazing programmer. But I now know he did it wrong. /me stacks a bar of soap on top of the pile, steps up and ... SCREAMS. Maintaining and modifying source code is hard. Porting it to multiple new platforms may require rewrites. Maintaining library compatibility may require refactoring. Upgrading installers may require code reorganizations. Contributing it to debian may require restructuring. It is all trivial and obvious to you. You wrote it. But finding and fixing the fencepost bug in a red-black immutable tree implementation borders on the impossible. You need to know that bit 31 overflows in a strange way only on Alpha2 processors, causing a interrupt that is not handled by the JVM. What does bit 31 mean? Why did the bug depend on it? Your project exceeds 25,000
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
Good points. I've tried to follow many of these with code I've written, but there are still some things I could stand to do better. Thanks for writing this, it can serve as a checklist for my own projects from now on! Cheers, DD (2013/04/20 7:09), Michael Klishin wrote: Month after month there are more and more people who announce their open source Clojure projects. This is great and we can't get enough of this. What is not great is how easy it often is to get started with some of the projects. Some of the most basic maintainer best practices are completely ignored, even though it often takes 3 minutes to fix some annoyances. So I wrote a little ranty blog post about what you can do to make your project awesome (or at least not suck). This also sums up what we've been trying to practice with ClojureWerkz. I hope it will help the Clojure community to be better library maintainers. Here it is: http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/ Now you have no excuse to not make your library totally awesome. -- MK http://github.com/michaelklishin http://twitter.com/michaelklishin -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out. -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
Re: ANN How To Make Your Open Source Project Awesome (or: Not Suck)
2013/4/20 u1204 d...@axiom-developer.org There is a HUGE gulf between the user documentation and maintaining the code. Just like there is a huge difference between using a car and maintaining a car. There are two things to consider: * Your audience is other developers. * Most projects are relatively small and straightforward compared to the Clojure compiler. My point was at least try to find a new maintainer. Don't let it rot. There is a blog post in the community that I'm referring to between the lines. It won't be hard to figure out which one. The idea is, don't do that. Don't turn your project into abandonware if you no longer want to maintain it well. Projects such as ring, clj-time, clj-http have found new maintainers and those people do a great job with them. -- MK http://github.com/michaelklishin http://twitter.com/michaelklishin -- -- 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+unsubscr...@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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
