[ID: protocol.txt,v 1.18 2001/12/13 00:26:56 ttn Exp] -*- outline -*-

This file details project entry submission protocol and format, w/
sections: Overall Protocol, Overall Format, Recognized Fields, Notes,
Example.


* Overall Protocol

** Adding an Entry

	First, read the rest of this document, which describes the
	format of a project entry submission.  Send the entry to
	guile-projects@glug.org with subject "Guile Project Submission".
	Please don't forget this subject, or else there's a good chance
	it'll end up in the spam box.  The body should contain the entry.

	You will receive a response indicating that the entry is either
	added or erroneous (or both, in which case a fixed entry will be
	included).

** Updating an Entry

	The procedure for updating a project is the same as for making
	the initial submission, but you don't have to include every
	field, just whatever you want updated.  For example, if you want
	to add a license field to your existing entry, you'd just have

	((name "foo") (license "bar"))

	as a submission.

	You will receive a response indicating that the entry is either
	updated or erroneous (or both, in which case a fixed entry will
	be included).

** Deleting an Entry

	The procedure for deleting a project is similar, but the format
	is very simple; use #f after the name (and optional password)
	field.  For example, with no password:

	((name "foo") #f)

	With password:

	((name "foo") (password "qux") #f)

	You will receive a response indicating that the entry is either
	deleted or erroneous.

* Overall Format

	The format for a submission is an alist.  (Not only is it easy
	to parse, but should be pretty easy for schemers to deal
	with. :)  For each FIELD, you have:

	(FIELD DATA [DATA...])

	FIELD is a symbol, the field being modified.  DATA is a collection of
	strings and/or markup directives, with FIELD-specific meanings.

	There are two markup directives to make it easy to represent
	the different types of information you'd like to put in a
	project description.  These are `url' and `email'.

** (url LOC [TEXT])

	This describes a Uniform Resource Locator.  LOC is the url
	itself, while TEXT is the optional description for the link in a
	webpage.  An example would be

	(url "http://home.thezone.net/~gharvey/guile"
	     "Greg's Guile Page")

	Which will output the html:
	<a href="http://home.thezone.net/~gharvey/guile">Greg's Guile
	Page</a>.

	Or plaintext:
	http://home.thezone.net/~gharvey/guile [Greg's Guile Page]

	If no text is given, the link itself will be used.

** (email NAME ADDR)

	This gives a person's NAME and their email ADDR.  (Possibly one
	of `url' or `email' should be modified to be consistant with
	each other?  "(email addr name)" seems a little odd, though.)

* Recognized Fields

** (name PROJECT-NAME)

	Must be unique.  If it isn't, you'll get back an unable to
	update message (since the password will be incorrect).
	PROJECT-NAME must always appear in the alist.

** (password PASS)

	This is an optional password for the entry (the alternative is
	gnupg signed messages, though this is likely to be implemented
	first).  If given on the first email it sets the password (rather
	than randomly generating one); in subsequent mails, it's used to
	verify the modification.

** (admin NAME PASS)

	This is used to add entries to the database.  As mentioned in
	notes above, there should be a pool of people who are able to
	verify projects; each new submission will be forwarded to a
	random selection of those, who can then send back the submission
	with this field added.

** (new-name NEW-PROJECT-NAME)

	Changes the name for the project to NEW-PROJECT-NAME.

** (new-password NEW-PASS)

	Changes the password for the project to NEW-PASS.

** (location (url loc [text]))

	This should be a pointer to the homepage of the project, or the
	distribution if no page is available.

** (category CAT)

	This is one of a set of pre-defined categories.  These are the
	ones recognized at this time:

	Core
	Libraries		(deprecated, be more specific)
	Libraries/X11
	Libraries/Database
	Libraries/Graphics
	Libraries/Datatypes
	Libraries/SQL
	Exports/Libguile
	Exports/Libguile-High
	Applications		(deprecated, be more specific)
	Applications/Devel	(deprecated, use next one)
	Applications/Development
	Applications/X11
	Applications/Editors
	Applications/Network
	Applications/Shell
	Applications/Math
	Applications/Games
	Applications/Translators
	Applications/Simulation
	Applications/Office
	Applications/Sound
	Applications/Publishing
	Tools/Test-Suites
	Tools/Text

	Please use a string w/ the exact case shown above (for example,
	"Core" instead of "core").  This list documents current entries
	and can be reasonably extended.

** (description DESC)

	This should be a brief description (no more than a paragraph) of
	the project.

** (authors NAME ...)

	The main authors of the project.  Each entry should be a name,
	and optionally an email address for the author.  Basically, for
	each author, you either have a string, or an (email name mail).

** (maintainer NAME)

	The current maintainer of the project.

** (mailing-list DESCRIPTION)

	If the project has a mailing list, it should go there.

** (status DESCRIPTION)

	The status of the project.  (Maybe this should be called news?
	I'd expect that you'd want to update this whenever something
	interesting happens.)  For example, you can use this field to record
	release version number and date.

** (license DESCRIPTION)

	Describe the licensing of the package (e.g., "GPL").  A GPL license
	means automatic inclusion in the gnu.org subset of the list.

** (requires DESCRIPTION)

	Things required to use the project.

** (keywords DESCRIPTION)

	This provides a set of key words that can optionally refer to
	the project.  See guile below for an example.  Basically, choose
	these to cover *major* features/uses when the single category
	isn't quite enough.  Also, space 'em, because the software is
	amazingly stupid, i.e. (keywords "word1 " "term1 ").

* Notes

** State of the Automation

	It's not going to be possible to completely avoid human
	intervention with submissions (at this time).  For example, there's
	nothing stopping some a-hole from sending a couple of thousand
	projects with names like "aaaaa", "aaaab", etc; if everything goes in,
	you could easily exhaust disk space on the server, as well as
	making the actual list itself unusable (and probably a
	tremendous hassle to fix).  What will be needed is a handful of
	volunteers to act as trusted intermediates for initial
	submissions; basically, it would just involve each initial
	submission to be sent to a few of those people, each able to
	verify the submission.  This doesn't prevent mailbombs (though
	the fact that every person doesn't get every submission helps a
	little), but then nothing really does except for the existance
	of a working brain (which probably should be a prerequisite for
	net access, but sadly that isn't the case).

** Restrictions

	The alist should be the entire body of the email message.  Turn off
	signatures.  Do not use attachments.  Make sure the email's "From"
	header is useful in case of bounced entries due to incorrect password
	or other ill-formed input.

* Example

	Here is an example actually used for the guile-projects management
	code.  This is also available in the guile-projects distribution in
	subdirectory docs/sample-entries.

((name "guile projects list management code")
 (password "more bits for everyone")
 (category "Applications/Publishing")
 (description "This is the guile scheme code that maintains the "
	      (url "http://www.glug.org/projects/list.html"
		   "guile projects list")
	      ".  There are configurations for glug.org as well for "
	      (url "http://www.gnu.org/software/guile/gnu-guile-projects.html"
		   "the gnu.org subset of the list")
	      ".")
 (authors "Greg Harvey and Thien-Thi Nguyen")
 (maintainer (email "ttn" "ttn@glug.org"))
 (status "version 1.12 released 2001/12/12")
 (license "GPL"))

[protocol.txt ends here]