On the Capitalization of Project Files

I have noticed a trend with regards to the case of project files. In
the old days these “information files” where all caps --files like
COPYING, CHANGELOG and README. More recently, with the uptake of
GitHub, there has been a trend to add extensions so GitHub can render
the document accordingly, e.g. README.rdoc. Going further it seems Hoe
has popularized the use of title case names with extensions, such as
History.txt and License.txt (perhaps b/c it’s a Mac OS thing?)

Obviously this isn’t some fundamental issue of great import. But I am
curious as to the what and wherefores that others may have for this
minor decision of project development.

COPYING is used for GNU things, though I don’t know why.

In case you wanted to check this important issue, the page
http://www.gnu.org/licenses/gpl-howto.html says “In GNU programs the
license is usually in a file called COPYING.”

Sorry I just realized that wasn’t what you were asking, forgive me.
I’m tired.
I have no help for you :frowning:

hi 7rans -

purely out of curiosity, and you’ll have to forgive me because i have
no useful or relevant dialog whatsoever…

is your name really Tom Sawyer?

thanks, sorry -

  • j

On Thu, Apr 21, 2011 at 08:50:52AM +0900, Johnny M. wrote:

COPYING is used for GNU things, though I don’t know why.

In case you wanted to check this important issue, the page
http://www.gnu.org/licenses/gpl-howto.html says “In GNU programs the
license is usually in a file called COPYING.”

While none of them are GNUish, I’ve taken to using a COPYING file in
some
of my projects – not to contain license text, but to contain some
copyright information, plus information about licenses used by library
dependencies, and to refer to the actual license file, which is
generally named after the license (in most cases for my projects,
owl.txt
for the Open Works License).

As for changes in case, I find that README, LICENSE, and COPYING files
tend to be a good standard to follow for purposes of making them easy to
find and identify. I have no objections to the use of (optional)
filename extensions like .markdown and so on, since it’s basically the
capitalized word identifying file contents that provides the benefits I
enjoy in terms of being able to find useful information for a project.

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. The 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. At least when you see a
filename
like LICENSE you know what to expect if it contains license text. This
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.

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
    the license text it contains without opening it

Those are my thoughts. Yours may differ.

On Thu, Apr 21, 2011 at 04:14, Chad P. [email protected] wrote:

I’m kinda disappointed to see stuff like License.txt, which is both:

  • not really stand-out and standardized the way LICENSE has become

Agreed. LICENSE was not invented here, though, so that may be a
factor…sigh

On Apr 20, 10:14pm, Chad P. [email protected] 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. The 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. At least when you see a filename
like LICENSE you know what to expect if it contains license text. This
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.

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?

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

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
    the license text it contains without opening it

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.

On Thu, Apr 21, 2011 at 04:17:31PM +0900, Nikolai W. wrote:

On Thu, Apr 21, 2011 at 04:14, Chad P. [email protected] wrote:

I’m kinda disappointed to see stuff like License.txt, which is both:

  • not really stand-out and standardized the way LICENSE has become

Agreed. LICENSE was not invented here, though, so that may be a
factor…sigh

Are you referring to the NIH principle of bad engineering in general, or
are you referring to some “here” in particular (such as Apple’s software
ecosystem)?

Anyway . . . I’ve said before that NIH syndrome has no place in open
source software development:

http://blogs.techrepublic.com.com/security/?p=460

. . . and generally, if you’re looking for a license file, that means
open source software development. It’s not like we’re talking about the
official ECMAScript standard (which sucks); it’s just a commonly
accepted
practice that helps make things easier for everyone involved. All open
source projects – even “proprietary” source, if the source is publicly
available somehow – should come with a COPYING and/or LICENSE file at
the very least, and not screw with the naming convention too much. Such
things, along with a README file, should be among the first things
committed to any publicly accessible project repository.

That’s my take on it, at least.

On Thu, Apr 21, 2011 at 4:44 PM, Intransition [email protected]
wrote:

Would it not be good enough to just reference
an official online copy, and only include the minimum copyright notice
required?

The web is ephemeral, and so are links. Hosting disappears (or moves
without a redirect), or gets disconnected (Hello, Amazon EC2! Are you
up yet?), and with it the license file.

A file that isn’t very large to start with, so any savings would be
lost. And distribution happens in a compressed form, anyway (well,
most of the time).

Also: I doubt that lawyers agree with retroactive licensing, too, as
an easily updated license is the only benefit I can see from hosting
the license purely online.


Phillip G.

Though the folk I have met,
(Ah, how soon!) they forget
When I’ve moved on to some other place,
There may be one or two,
When I’ve played and passed through,
Who’ll remember my song or my face.

On Thu, Apr 21, 2011 at 11:44:35PM +0900, Intransition wrote:

summarizing the general license picture of the software.

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.

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.

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.

This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.

| Privacy Policy | Terms of Service | Remote Ruby Jobs