Re: [htsserver-devel] concept files
Status: Abandoned
Brought to you by:
uh1763
From: Uwe H. <uh...@bi...> - 1999-12-13 20:20:59
|
Hi, This looks really good, indeed. I made some annotations and commented on things I think could be improved. Any comments are welcome. > General Concept Draft > > No. 0001 "Concept Files - Idea, Realisation, File Format" > Revision 1, 1999-12-12 The date format can be confusing, because for example 1999-3-4 can be interpreted as "March 4, 1999" or "April 3, 1999", depending on where you live. Dates should be of the format "Month Day, Year", e.g. "November 19, 1999". You can use date +"%B %d, %Y" on the commandline to get such a date. > Sven M. Hallberg All references to people should have their email-address included, except they explicitly tell us that they don't want that. > > > CONTENTS Or: TABLE OF CONTENTS > Should a developer have an idea for a formerly undefined concept > he will create a "concept draft" which he will suggest to all > the other developers and the maintainer. This suggestion is then > discussed until the maintainer decides on whether to accept or > deny it. In the course of this discussion the draft should of > course be constantly revised and tweaked in order to make it > fit the idea of the program. I don't think we should differ between a draft and a 'final' version, because most probably there will not be a 'final' version. There will always be things that can be improved. Just have one document, which will be revised if anything needs to be improved or updated. After any change the version number of the document increases. > For suggesting and discussing concepts a mailing list will be > used. Its address can be found on the project webpage. > > Once a given concept is approved it is made available to the > developers electronically via the world wide web and FTP. There Probably not FTP. It will be on the homepage and in the distribution. I don't see a good reason to make them available via FTP. > A concept file will be named "C-XXXX.txt" where XXXX denotes the > concept's ID. CXXXX. There could be systems which don't allow '-' in filenames (?) Maybe we should even allow any filename, because there are already some files, which are similar to such concept-files, e.g. docs/PROTOCOL or docs/README.specifications. We could just change their layout and parts of the contents to match the concept-files. Comments? Opinions? > All lines are 80 characters in length. ^ at a maximum > The concept title should be as descriptive as possible in order > to ease browsing the concept files. > > The next line holds the revision number of the concept file > followed by the creation date of that revision. > The revision number is incremented every time a concept is > changed after its initial release. > > Format: > Revision X, YYYY-MM-DD > X = revision number Or X.Y or Y.Y.Z Starting at 0.1, I'd say. > YYYY = year (four digits) > MM = month > DD = day Better: "Month Day, Year", see above. > After another blank line the author list follows. Each author > is named on a seperate line. Usually the author list will only > contain the persion who originally wrote the file. However, if > a developer contribues changes/additions of reasonable gravity > to the concept he might add his name to the author list. We might add a "Contributions" or "Thanks" section, where all people are listed who suggested improvements, pointed out typos or made any other smaller changes. > 5.2.2. Table of Contents > > The table of contents is introduced by the word "CONTENTS" on > a line by itself. Or: TABLE OF CONTENTS. Any votes? :-) I'll put this on the homepage, soon. Any further improvements can be sent to the mailing-list for discussion. Uwe. -- Uwe Hermann <uh...@bi...> http://www.bingo-ev.de/~uh1763/index.html ----------------------------------------- :wq |