Re: On the Capitalization of Project Files

On Thu, Apr 21, 2011 at 11:44:35PM +0900, Intransition wrote:
> On Apr 20, 10:14=A0pm, Chad Perrin <[e-mail]> wrote:
> >
> > For the record, I think actually putting license text in the COPYING
> > file is a bad idea, *especially* when using absurdly complex licenses
> > like the GPL. =A0The filename seems indicative of guidance for the
> > reader, rather than legal boilerplate -- a "user friendly" filename
> > that leads the user into an ambush by a wall of legal text. =A0At least
> > when you see a filename like LICENSE you know what to expect if it
> > contains license text. =A0This is why I prefer to use COPYING to convey
> > information in layman's terms about stuff like copyrights and
> > summarizing the general license picture of the software.
>=20
> Interesting. So you advocate splitting copyright information and the
> actual license text and naming the license file so it is recognizable
> by name. I notice some doing the later with a `MIT-LICENSE` file. And
> really I've always wondered if it is really necessary to distribute the
> entire license text. Would it not be good enough to just reference an
> official online copy, and only include the minimum copyright notice
> required? In which case, wouldn't a clause in the README file be enough
> and we can just dispose of any COPYING or LICENSE files?

Whether just referencing the license location online, et cetera, would be
"better" largely depends on what generation of redistribution is going on
and what license you are using, as well as the intended audience.  In
general, it's "safer" to just include the license text, especially
because most open source licenses *require* the license text to be
distributed with the materials in question.  Obviously, if you're the
sole copyright holder, you can distribute it with nothing but notice that
recipients who redistribute must do so under the terms of the license
without actually including the license text yourself, but then -- again,
for most open source licenses -- the person to whom you distribute it
then has to find the license text and include it with any
redistributions.  Including the license text yourself saves such
recipients the trouble.

A brief mention of copyright information is generally better than a
COPYING file as I've described it, but in some cases the copyright
circumstances of a given project that collects a lot of components that
may be subject to varying copyright conditions could involve enough
explanation that separating a description of that legal minefield should
be separated from the README file itself.  After all, one doesn't want
installation and usage information in the README file to get completely
drowned out by a copyright circumstances wall-o-text, generally speaking.

So, in short . . .

You should have a README file and a LICENSE file for most cases.  In some
cases -- if copyright circumstances for the project warrant enough
explanation to have a separate file -- you may want a README file, a
COPYING file, and (perhaps) a separate license text file of some sort.
In those circumstances, you may not want to call it LICENSE, so that
people will be drawn to the explanatory text in the COPYING file first,
especially since there may be need to include several different licenses
with the project.


>=20
> Also, as to the former, for awhile I seriously considered having a file
> named `(c)2011` (or whatever year it is).

That's probably okay-ish for proprietary code, but potentially confusing
for open source projects.


> >
> > I'm kinda disappointed to see stuff like License.txt, which is both:
> >
> > * not really stand-out and standardized the way LICENSE has become
> >
> > * generically named so that you don't, for instance, know anything about
> > =A0 the license text it contains without opening it
>=20
> For a long time I didn't like the whole License.txt style either. For
> starters I find file extensions a bit archaic. I'm not sure why our
> file systems don't support file type attributes. But clearly that's not
> something that will be changing anytime soon, so I've come to accept
> the extensions b/c they are useful to document renderers such as
> GitHub. As for the letter case, I felt the same way about not standing
> out and not a common practice. More recently however I started to think
> the standing out was rather relative. When every file is all caps none
> of them standout either. So now I am thinking the titlecase filenames
> are a bit easier on the eyes.

Look -- if you want to call your license file LICENSE.txt, go for it.
That's close enough for government work, and fits in with the
README.markdown idea, where you specify the file's purpose with LICENSE
and its content format with the .txt extension.  This can be handy as a
cue to the reader as well as to any parsing scripts.  My biggest
complaint about License.txt as a departure from the way it's generally
done is not the file extension; it's the fact it doesn't stand out from
the pile of other files the way LICENSE(.txt) does.

As for "when every file is all caps" . . . don't name all your files with
all-caps letters.  Use all-lower-case or title-case for files, depending
on the purpose and type of file, except for special files like README and
COPYING/LICENSE files.  Note, for instance, that when I use a COPYING
file, my license text is in owl.txt, not in OWL.TXT, and that I do not
use all-caps letters for my source files either.

I don't see how pointing out that someone using a braindead approach to
file naming means that we have to de-emphasize the README and
COPYING/LICENSE file names even when we use more reasonable file naming
conventions for the rest of the files.  That seems a bit like saying that
we shouldn't kill the harmful bacteria in dental plaque on the teeth of
otherwise healthy people because, for people with ebola, dental plaque is
the least of their worries.  I don't have ebola, so I take the time to
brush my teeth, floss occasionally, and use mouthwash.  What about you?

Similarly, I don't name all my files with all capital letters, so naming
(on average) two files per project using all-caps doesn't suffer the
problem you identify for projects with filenaming convention ebola.

--=20
Chad Perrin [ original content licensed OWL: http://owl.apotheon.org ]