This is the mail archive of the guile@cygnus.com mailing list for the guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Guile projects submission draft 3 (hopefully final)



Ok, this is the third draft (and hopefully final) of the format for
guile project submissions. Happy reading.

==begin mail.txt==

This is the 2nd (and hopefully final) revised format for email
entries; new bits include:

Catagory... urm category spelling fixes.

Removed the bloaty, kitchen sinkish undo feature.

Removed %start (it's definately not necessary... I should've re-read
rfc882 first ;)

===end new bits 2===

New bits in the first revision:

Moved to an alist format.

mailing-list: for describing mailing lists associated with the
project. 

help-wanted and testers-wanted are now descriptions, rather than
true or false values. This is so you can describe exactly what you
want help with (porting, new features, etc...) and what really needs
to be tested (the ports, the new features, etc...).

author has been removed, and replaced with authors. I'd think that,
in a lot of cases, it's very rare for a free-software project to have
just one person who deserves mention.

contact has been replaced with maintainer, and now includes a name
as well as an email address. This isn't folded into authors; the
reasoning for this can be easily seen from guile itself, which has
several people who should be credited as authors, but most of these
shouldn't really be included as contacts (Aubrey Jaffer works on scm,
for example). So, you'd have (not exhaustive, a more complete one is
given at the end):

(authors "Aubrey Jaffer")
(maintainer (email "Jim Blandy" "jimb@red-bean.com"))


A sample for guile itself is included.

==end new bits 1==

Contributors: lots of people on the list (sorry, but I'm not in the
grep through my mail archive kinda mood right now... in any case,
suggestions were and are appreciated).

Conventions:

    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 description)

field is the field being modified.

the description is a collection of strings and/or markup
directives. 

Notes:

	It's not going to be possible to completely avoid human
intervention with submissions. 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).

Markup Directives:

There are a few markup directives to make it easy to represent the
different types of information you'd like to put in a project
description.

(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 and an email address for that
person. (possibly one of url or email should be modified to be
consistant with each other? (email addr name) seems a little odd,
though).


Fields:


(name project-name): Must be unique. If it isn't, you'll get back
an unable to update message (since you won't have the correct
password). 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. 


(new-name new-project-name): Changes the name for the project.

(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 will be one of a set of pre-defined
categories. Basically, things like Application/Game or Library
(module?) 

(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)

(help-wanted description): indicates whether additional programmers are
wanted/needed. 

(testers-wanted description): indicates whether the project wants people to
test certain things (of course you want people to use it, but you may
really need someone to test the port to Foonix).

(license description): describe the licensing of the package
(i.e. GPL).

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


Other features:

A full modification history should be kept (and accessable from the
page) for the status field. 

It might be a good idea to allow just bare words (i.e none of that
quoting) for entries, so you could do:

((name Greg's Fantastical Guile Thing))

Spacing is a problem here, though, if plaintext is to be generated.

Sample:

This is a sample entry for guile itself (authors taken from the
distribution's AUTHORS file... you probably wouldn't want to include
this many... rather, just include major authors, and a link an authors
file). Also, I'm not quite sure if that's the actually correct method
of subscribing to guile@cygnus.com (it's been a while, and I've since
changed computers and had a major hd crash).

((name "guile")
 (password "Greg is a froody guy")
 (category "Core")
 (keywords "Extension Language" "Scheme" "Interpreter")
 
 (description "The Guile blurb that I don't feel like looking up right "
	      "now")
 (location (url "http://www.guile.org" "The Guile Webpage"))
 (authors "Aubrey Jaffer, George Carrette, Radey Shouman, Gary Houston, "
	 "Tom Lord, Anthony Green, Mikael Djurfeldt, Mark Galassi, "
	 "Marius Vollmer, R. Kent Dybvig, Roland Orre, Michael "
	 "N. Livshin")
 (maintainer (email "Jim Blandy" "jimb@red-bean.com"))

 (mailing-list (email "Guile mailing list" "guile@cygnus.com") 
              " is the main list for guile, used for "
	      "both general discussion and user questions; "
	      (email "bug-guile" bug-guile@gnu.org)
	      " is the list for reporting bugs; "
	      (email "guile-sources" "guile-sources@gnu.org")
	      " is for posting guile sources. "
	      
	      "To subscribe to the guile list, send mail to "
	      (email "guile-request" "guile-request@cygnus.com")
	      ", with Subject: subscribe your-email-address "
	      "To subscribe to bug-guile or guile-sources, "
	      "send mail to " 
	      (email "bug-guile-request" "bug-guile-request@gnu.org") 
	      " or "
	      (email "guile-sources-request"
	      "guile-sources-request@gnu.org")
	      " with Subject: subscribe your-email-address.")
  
  (status "The current release of guile is 1.3; it is still undergoing "
	 "many changes, but is stable enough for everyday use. Planned "
	 "features include an object system, an enhanced module system "
	 "and native threads support")
  (help-wanted "Cool hackage always appreciated.")
  (testers-wanted "Go for it!")
  (license "GPL, with an exception to allow non-GPL'd programs to "
	   "link to the library without becoming derivitive works."))
	     
	     
-- 
Greg