v01INF3: Submit - Submission Guidelines for comp.sources.reviewed

[Andrew Patrick]

Submitted-by: Andrew Patrick <csr at calvin.doc.ca>
Posting-number: Volume 1, Info 3
Archive-name: Submit


                         Comp.Sources.Reviewed
                       Guidelines for Submissions
                           Version 1.3 (4/10/91)

Comp.sources.reviewed (CSR) is a moderated newsgroup for the
distribution of program sources that have been evaluated by peer review
(new reviewers are always welcome).  This document presents some
guidelines for submitting sources to CSR, and may change from time to
time as we get more experience with the review process.  Comments about
these guidelines are also welcome.

What sources are acceptable?
----------------------------

We will attempt to handle sources that run on all the major computers
and operating systems.  The limiting factor is whether we can find
people who are willing to review sources on particular machines.  We
are equipped to review sources for the major flavors of Unix, DOS, and
perhaps VMS.  If you are in doubt, send a description of the program
and the kinds of systems it is intended for, and we will see if we can
find reviewers for it.

Where should sources be sent?
-----------------------------

Submissions to CSR should be mailed to "csr at calvin.doc.ca".  Most news
software will automatically mail postings to moderated groups to the
moderator, which in this case has been defined as "csr at calvin.doc.ca".

Please use an informative "Subject" line when mailing postings.
Something like "nlist - New file list utility, Part01/04" is preferred
over something like "Submission to comp.sources.reviewed".  Your
submission will be assigned a short "reference" name (<12 characters)
for the review process and for archiving, so you may wish to supply a
possible name in your Subject line.

For very large submissions, authors may wish to contact the moderator
(at "csr at calvin.doc.ca") to arrange an FTP file transfer.

What form should submissions be in?
-----------------------------------

The form of the submission will depend somewhat on the type of system
it is intended for.  The format for Unix submissions is detailed
below, and the format for other systems (e.g., DOS) should follow
these as much as possible.  

Submissions should be in the form of one or more "shar" (shell
archive) files.  Programs to build shar files have been posted to the
net, and are available from the usual archive sites.  

A description of the package should precede the first shar file
(either in the first mailing, or as a separate letter).  This
description should contain a description of the software package like
that contained in the README file (see below).  In fact, in many cases
this description can simply be a copy of the README file.

If you are not familiar with this form of submissions, contact the
moderator of comp.sources.reviewed and we will send you some templates
to get you started.

What should be included in the submission?
------------------------------------------

Each submission should include the following types of files.  

README:  a description of the software package.  This description
    should include:

	- the purpose and value of the software (give details here)
	- the types of systems it is intended for (e.g., BSD only,
	  Unix and DOS, etc.)
	- any dependencies in the system (e.g., must have perl to
	  run)
	- known limitations of the software
	- the authors of the software (with e-mail addresses)
	- the "patchlevel" of the software (see below)
	- any copying or distribution conditions

Makefile:  a standard control file for the make utility.  Having an
    "install" target in the Makefile (so users can type "make install"),
    is often convenient, but many users prefer that they be able to make
    and test software in the current directory before they install it.
    It also often a good idea to include a "clean" target to clean out
    the "core", "*.o", etc.  files.

    Variables that users may wish to change should be clearly identified
    at the beginning of the Makefile.  Also, it is convenient to have
    the parameters for known systems included in the Makefile, but
    commented out.
    e.g., CFLAGS=-DBSD -DUSE_TERMCAP
          #CFLAGS=-DSYSV -DUSE_TERMINFO

Installation (INSTALL):  a description of the steps necessary to
    install the software.  This should include a description of any
    changes a user might wish to make to handle local conditions, and a
    description of what happens when the user types "make install".

Man Page: for Unix sources, you should have one or more documentation
    files prepared in man page format.  If necessary, you may also wish
    to include separate documentation files.  The man page should
    describe how the software is to be run, what parameters and options
    are available, and the functions the software provides.

Patchlevel.h:  you should have some method of determining what version
    of the software this is.  The preferred method is to use a
    "patchlevel.h" file that contains information about the version level
    (e.g., #define PATCHLEVEL 1.1), and this information is then used in
    the source files (e.g., printed in the usage statement).

    When patches are applied (see below), the "patchlevel.h" file should
    be patched to reflect the new version number.

    It is often useful to use some form of a source code control
    system (e.g., SCCS or RCS) to keep track of the different versions
    of software.  Using such a system, each file in a package can
    contain the version number information.
    
For large submissions, it is often useful to make subdirectories like
"man", "doc", "source", etc.

How are patches handled?
------------------------

Patches to published software should to be sent to the usual
submission address ("csr at calvin.doc.ca") with the word "patch" some
where in the "Subject" line.  Patches will be reviewed and distributed
as quickly as possible.  The preferred form for patches is "diff"
format, using the "-c" option to produce context diff files.

Patches should be accompanied by a complete description of the changes
made to the software, and the reasons behind those changes.  The patch
must update the version number contained in the "patchlevel.h" file.

What are the steps of the peer review process?
----------------------------------------------

A typical sequence of events for the review of sources is:

- software is mailed to moderator
- moderator acknowledges receipt
- moderator briefly checks software against guidelines listed above
- moderator sends software to reviewers
- reviewers build, install, run, and test the software
- reviewers return evaluations to moderator (based on guidelines
  described an another document)
- moderator compiles evaluations and makes final publication decision
- if submission is accepted:
	- moderator discusses evaluations with author
	- moderator posts sources and evaluations
- if submission is not accepted:
	- moderator sends evaluations to author
	- moderator may suggest revision and resubmission, or posting
	in another newsgroup

What if the reviewers find problems?
------------------------------------

We are discouraging making repairs to submissions during the review
process.  Reviewers may contact you for information and clarification,
but we do not envision fixes being applied during the course of a
review.

Once the reviews are completed, you will receive a summary from the
moderator, and, if necessary, will have a chance to make repairs to
your package.

Do authors automatically become reviewers?
--------------------------------------------

If you submit a package to CSR, you will be invited to become a
reviewer.  This means that from time-to-time you may be sent other
people's software for evaluation.  You may refuse the invitation, but
you should realize that this group must have a set of qualified
reviewers in order to function.


-- 
        Andrew Patrick acting as Comp.Sources.Reviewed Moderator
              Department of Communications, Ottawa, CANADA
                           csr at calvin.doc.CA