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:

Anonymous 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...

EY 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.

Anonymous 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).

Modifying EC2 security groups via AWS Lambda functions

One task that comes up again and again is adding, removing or updating source CIDR blocks in various security groups in an EC2 infrastructur...