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.
Subscribe to:
Post Comments (Atom)
-
A short but sweet PM Boulevard interview with Jerry Weinberg on Agile management/methods. Of course, he says we need to drop the A and actu...
-
Here's a good interview question for a tester: how do you define performance/load/stress testing? Many times people use these terms inte...
-
Update 02/26/07 -------- The link to the old httperf page wasn't working anymore. I updated it and pointed it to the new page at HP. Her...
4 comments:
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...
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.
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...
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).
Post a Comment