Friday, October 21, 2005

Proper location for LICENSE, CHANGELOG and other files?

What do people think should be the proper location for files such as LICENSE, ANNOUNCE, CHANGELOG, README?

Some projects have them in the top-level directory, some have them in a sub-directory such as 'docs'. Currently the Cheesecake index penalizes projects that do not have these files in the top-level project directory.

If you have any ideas, please leave a comment here or, even better, post to this Cheesecake Open Discussion thread.

Update: I also created two mailing lists for the Cheesecake project at SourceForge.net: cheesecake-devel and cheesecake-users.

4 comments:

Mike Watkins said...

Top level = fewer keystrokes to read the durn things, which if you admin a lot, is an issue of some consequence. Also, having primary docs obvious quite possibly results in fewer "RTFM-type" inquiries...

Jason Lai said...

Main directory. It's good to make them obvious, and it fits with the convention that most (non-Python) projects use -- esp. since autoconf requires them in those places.

Titus said...

a README and setup.py should be all that are required in the main directory.

LICENSE and ChangeLog should be more mobile; why the heck do you need them in the top-level directory?? I never look at 'em anyway until I'm actively involved in the development of a project...

Ian Bicking said...

I can see some justification for LICENSE (though I don't include any license document anywhere in any of my projects). README always strikes me as funny and incomplete. Half the time it's just a pointer elsewhere. Other times it's an incomplete and sometimes inaccurate abbreviated document, that summarizes what the "real" intro documentation says. At least PKG-INFO has useful structure, if you are looking for pointers.

As a result, I put everything in docs/, and you can see everything by looking in that directory. Not in project subdirectories, subcomponents don't have their own subcomponent/docs/ directories (they might have docs/subcomponent/, though).

I'm bad at change logs, but then as a user I find a news file generally more useful anyway (and as a developer I try to be at least a little better about generating those files).