Readme.txt vs. README.txt

Question

I have just forked a project in Github, made my changes etc. This got me wondering: I see mostly README.txt in opensource projects and the file I edited was Readme.txt. Is this some sort of standartisation or should I have left it as is?

Answer 1

All-uppercase letters stand out and make the file easily visible which makes sense because it is probably the first thing a new user would want to look at. (Or, at least, should have looked at…) As others have already said, file names starting with a capital letter will be listed before lower-case names in ASCIIbetical sorting (LC_COLLATE=C) which helps make the file visible at a first glance.

The README file is part of a bunch of files a user of a free software package would normally expect to find. Others are INSTALL (instructions for building and installing the software), AUTHORS (list of contributors), COPYING (license text), HACKING (how to get started for contributing, maybe including a TODO list of starting points), NEWS (recent changes) or ChangeLog (mostly redundant with version control systems).

This is what the GNU Coding Standards have to say about the README file.

The distribution should contain a file named README with a general overview of the package:

• the name of the package;
• the version number of the package, or refer to where in the package the version can be found;
• a general description of what the package does;
• a reference to the file INSTALL, which should in turn contain an explanation of the installation procedure;
• a brief explanation of any unusual top-level directories or files, or other hints for readers to find their way around the source;
• a reference to the file which contains the copying conditions. The GNU GPL, if used, should be in a file called COPYING. If the GNU LGPL is used, it should be in a file called COPYING.LESSER.

Since it is always good to strive for the least surprise of your users, you should follow this convention unless there are compelling reasons for a deviation. In the UNIX world, file name extensions were traditionally used sparingly so the canonical name of the file is README without any suffix. But most users probably would have no troubles understanding that a file named README.txt has the same meaning. If the file is written in Markdown, a file name like README.md might also be reasonable. Avoid using more complicated markup languages like HTML in the README file, however, because it should be convenient to read on a text-only terminal. You can point users to the manual of the software or its on-line documentation, that might be written in a more sophisticated format, for details from the README file.

Answer 2

Traditionally the file was called README in uppercase because command-line environments that use alphabetical ordering would then put the file at the top. This makes them easily visible in big directories.

It's most likely a holdover from the Unix/Linux world where you would download sources and then build your software. Having files like README and INSTALL at the top of your 'list directory contents' view makes it easier to see that they are there, instead of having to browse the entire contents from a command-line interface. The same basic principle works for github as well (and actually works in GUI interfaces too, come to think of it, so it might still hold merit)

By no way a hard rule, but very likely something that everybody is doing as a habit because other projects are doing it. Unless there is some explicit reason NOT to, you should probably use all caps just because you'll see it being used that way in lots of other projects. It's also the default naming Github uses when you create a new repository.

Answer 3

README is usually written in upper case. In this way the ls Unix command placed the file near the beginning of the directory listing (upper-case letters comes before lower-case letters in ASCII ordering).