Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.javascript > #29022

Re: [FAQ] Repository on GitHub, license, review cycle

Show all headers | View raw

Asen Bozhilov wrote:

> Thomas 'PointedEars' Lahn wrote:
> > some of you might have noticed already that, as I indicated recently
> > [0], this weekend I have migrated the code repository for the “FAQ for
> > comp.lang.javascript” (“the FAQ”) from SVN to Git, and published it on
> > GitHub:
> >
> >    <https://github.com/PointedEars/faq-cljs>
> 
> Great news! I have waited for years someone starts maintaining the FAQ.

Well, if you follow the references, you can see I *am* maintaining *that* 
FAQ since almost exactly *three years ago* (2012); there have been a few 
off-VCS contributions by others, too.  I have just migrated the code 
repository now so that it is *easier* for people to contribute (I do not 
have to create an account for every contributor, or an anonymous account 
which cannot be easily tracked to an individual contributor, unlike in a 
centralized VCS such as SVN), and for me as I am gradually switching 
everything to Git (which, in case you are interested, is easy to do with 
using git-svn during the transition [1]).

> If I remember correct, the maintaining of FAQ was dropped in the time
> when ES5 was released. 

The maintainance of the “comp.lang.javascript FAQ” was abandoned in  
2010-10; ES 5 was published in 2009-12 (5.1 in 2011-06).  Hence the “FAQ for  
comp.lang.javascript” since 2012-12.

> Today there is ES2015 a.k.a. ES6 is officially approved and I think there
> would be many new frequently asked questions.  By today, the most common
> question is "How can I use ES6 in ES5 environment?". Babel transpiler
> fills that gap, and if you browse npm packages you can notice how many
> packages are written in ES6.

I see.  But AFAIK, that question has never been asked *here*.  For the “FAQ 
for comp.lang.javascript”, the focus must naturally be questions that are 
*asked* *frequently* *in comp.lang.javascript*.  Writing a general 
JavaScript/ECMAScript FAQ would be another project.  I think this precisely 
why we have the FAQ and the FAQ Notes separately.

And therein lies the problem: There are not many people using Usenet these 
days, certainly there are at least fewer people *posting* (one cannot know 
how many there are just reading unless one does a survey).  Without postings 
there are cannot be new questions.

Regardless, I think that the questions-and-answer pairs already collected 
deserve a clean-up.

> > It is my intention (as explained in the README there), in addition to
> > considering FAQ contributions via the already known channels [1], to
> > review Pull Requests for the “dev” branch of that repository (as it is
> > customary, “master” is the name of the stable branch on which the live
> > version is based).  I will continue to post here a summary of the
> > suggestions for the FAQ that I have and receive from you via those
> > channels, and other *direct* channels (like social media), for public
> > discussion.
> 
> The contributions process seems pretty straightforward, but I think
> before PR, it should be open for discussion either via a github issue or
> thread here.

That does not make sense.  How can I know which contributions via Git(Hub) 
there are before someone makes a pull request?

That, same as it already is, pull requests would not be the only way to 
contribute, and that incoming pull requests would in most cases not be 
*merged* before public discussion took place, is precisely what I indicated 
above.

> My predictions, since FAQ is available in github the common
> approach would be using github's bug tracking system. This would lead to
> fragmented discussion, so you have to consider how to prevent it.

ACK.
 
>  > ... via Markdown ...
> 
> As we have discussed in twitter, as long FAQ is in github Markdown
> format would be pretty convenience and straightforward for github users,
> but of course every new entry and changes should be added after
> discussion here or in github, could be discussed in both places.

I am using Markdown in my job on a daily basis.  It is easy to edit indeed, 
but it is rather hard to maintain when documents grow larger.  It is not a 
viable approach to have a FAQ as large as this to consist of only one 
Markdown document (one of the next iterations would see the current FAQ be 
available as separate HTML documents as well, generated dynamically via 
PHP), and when you start referring from one Markdown document to another, 
things quickly become unconvenient.  We (at the company) have also tried 
GitHub pages where the navigation for several documents would be generated, 
and found it to be such a PITA that we had to abandon the approach.

By contrast, the XML/XSLT that the FAQ currently is based on is harder to 
edit (and it can certainly be streamlined), but it has the singular 
advantage that it is very easy to add new content in separate documents, 
reorganize sections, have the Table of Contents updated automatically, and 
present the *same* content in different formats (for example, it would not 
be too hard to implement the posting of a FAQ section as plain text) just by 
applying a different set of transformations.
 
> > To make contributions even easier, I intend to publish the FAQ
> > content under the Creative Commons Attribution-NonCommercial-ShareAlike
> > 4.0 International (CC BY-NC-SA 4.0) License.  AIUI, this change would
> > only codify the existing informal agreement, and it had some support
> > [3].
> >
> > Why that license?
> >
> >    - Although it contains code examples, the FAQ content is more like
> >      a book than a piece of software; so a software license is not the
> >      appropriate type of license for it.  Creative Commons fill that gap
> >      by providing free *content* licenses.
> 
> You are correct, but there are many examples of softwares which include
> their own FAQ and the FAQ is not separately licensed under other license
> than the main project.
> I think some entries of c.l.js FAQ could be included in some open source
> projects licensed under MIT, BSD and LGPL. Those licensed are pretty
> relaxed and the code can be used for commercial purposes, so if they use
> c.l.js FAQ entries, they have to distribute their FAQ or doc separately
> under (CC BY-NC-SA 4.0).
> 
> Please reply with your thoughts about the above statement.

AISB, one must differentiate between source code and other content.  It is 
not reasonable to distribute the FAQ under a software license such as the 
MIT (Expat) or (Modified) BSD license or the (L)GPL¹ because it is not 
software.

Maybe it is possible to distribute the parts that are source code under a 
free software license, but at the moment I do not see the unique creative 
value in those snippets that would warrant that.  Which ones can you point 
out that would not already be found elsewhere on the Web?  The main value 
that the FAQ brings to users is to have all the (hopefully) good answers in 
one place.

__________
¹  <http://www.gnu.org/licenses/why-not-lgpl.html>

[1] <https://www.atlassian.com/git/tutorials/migrating-overview/>
-- 
PointedEars
FAQ: <http://PointedEars.de/faq> | SVN: <http://PointedEars.de/wsvn/>
Twitter: @PointedEars2 | ES Matrix: <http://PointedEars.de/es-matrix>
Please do not cc me. / Bitte keine Kopien per E-Mail.

Back to comp.lang.javascript | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[FAQ] Repository on GitHub, license, review cycle Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-12-13 18:02 +0100
  Re: [FAQ] Repository on GitHub, license, review cycle "danca (Daniele Campagna)" <cyberdanny@tiscalinet.it> - 2015-12-13 21:04 +0100
    Re: [FAQ] Repository on GitHub, license, review cycle Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-12-15 09:46 +0100
  Re: [FAQ] Repository on GitHub, license, review cycle Joao Rodrigues <groups_jr-1@yahoo.com.br> - 2015-12-14 15:22 -0200
    Re: [FAQ] Repository on GitHub, license, review cycle John Harris <niam@jghnorth.org.uk.invalid> - 2015-12-20 11:49 +0000
  Re: [FAQ] Repository on GitHub, license, review cycle Asen Bozhilov <asen.bozhilov@gmail.com> - 2015-12-16 22:35 +0200
    Re: [FAQ] Repository on GitHub, license, review cycle Cezary Tomczyk <cezary.tomczyk@gmail.com> - 2015-12-17 00:05 +0100
    Re: [FAQ] Repository on GitHub, license, review cycle Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-12-17 00:41 +0100
  [FAQ] Updates (was: [FAQ] Repository on GitHub, license, review cycle) Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2016-02-09 01:30 +0100

csiph-web