Source Code 1994 March/Source_Code_CD-ROM_Walnut_Creek_March_1994.iso/compsrcs/reviewed/intro

Internet Message Format | 1992-08-04 | 13.0 KB

From: Andrew Patrick <[e-mail]>
Subject: v02INF10: Intro - Introduction, Status, & Submission Guidelines
Newsgroups: comp.sources.reviewed
Approved: [e-mail]

Submitted-by: Andrew Patrick <[e-mail]>
Posting-number: Volume 2, Info 10
Archive-name: Intro
Supersedes: Intro: Volume 2, Info 9

This monthly posting provides an introduction to the newsgroup
"comp.sources.reviewed" (CSR).  It contains a description of the group,
its current status, information about the CSR archives, and the
guidelines for submitting sources.

Other information that is available includes the "Guidelines for
Reviewers" document that we use in evaluating submissions, and an Index
of sources already posted to the group.  This information is posted
occasionally to CSR, or it can be obtained via anonymous FTP from
ftp.uu.net:/usenet/comp.sources.reviewed.  Failing that, you can ask me
for the information.

People wanting to submit sources, become a reviewer, or get more
information should send mail to "[e-mail]".


                     ------------------------------
                     What is Comp.Sources.Reviewed?
                     ------------------------------

"Comp.sources.reviewed" is a moderated newsgroup (moderator: Andrew
Patrick [[e-mail]]) with the following charter:

    "Comp.sources.reviewed" is a moderated newsgroup for the
    distribution of program sources that have been subjected to a Peer
    Review process.  Similar to the process used for academic
    journals, submissions are sent to a moderator who then sends the
    sources to Peer Review volunteers for evaluation.  The Reviewers are
    asked to provided a timely evaluation of the software by compiling
    and running it on their machine.  If time does not permit them to
    complete a review, they are responsible for asking the moderator to
    select another reviewer.  If the Moderator and Peer Reviewers judge
    a submission to be acceptable, the sources will be posted along with
    the written comments provided by the Reviewers.  If a submission is
    not found to be acceptable, the author will be provided with the
    Reviewers' comments, and they will have the option of addressing
    those comments and submitting the sources again.



                    -------------------------------
                    Status of Comp.Sources.Reviewed
                    -------------------------------

The status of comp.sources.reviewed as of August 5 1992 is:

- submissions to date: 41
- posted: 12
- under review: 8
- reviewed, comments returned, not yet resubmitted: 14
- rejected: 1
- not reviewed: 6 (required software reviewers did not have)

- reviewers: 91

- average time to complete reviews:  30 days
   (last calculated Jan 16, 1992; based on 36 reviews)


                        -----------------------
                        Where are the Archives?
                        -----------------------

The official archive site for comp.sources.reviewed is ftp.uu.net
(uunet.uu.net), and the sources are available by anonymous FTP (and
other means) in /usenet/comp.sources.reviewed.  Like most sources
groups, the archives for CSR are organized in terms of "volumes".

We have also been told that:

    The USENET archive section of the Anonymous FTP area of kirk [in
    Australia] now holds an archive of comp.sources.reviewed.  This
    archive is updated daily (i.e.  any posting will can be found in the
    archive and associated indexes within 24 hours of the news article
    being received by kirk).

    The archive is available via anonymous FTP only on kirk.bu.oz.au:
    (131.244.1.1).  Fetchfile access will be available in the near
    future.

    For more information, please contact [e-mail].

An alternative archive site in the USA is:

Site:         sparky.sterling.com (sparky)
Contact:      Kent Landfield ([e-mail]) [phone]
Location:     Omaha/Bellevue, NE
Modems:       Telebit
UUCP:         On request
FTP:          Anonymous FTP
Mail server:  NA (Yet)
Additional:   This archive site uses Volume-Issue archiving.



                       --------------------------
                       Guidelines for Submissions
                       --------------------------
                           Version 1.9 (7/30/92)

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 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 "[e-mail]".  Most
news software will automatically mail postings to moderated groups to
the moderator, which in this case has been defined as
"[e-mail]".

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 "[e-mail]") to arrange an FTP file transfer.


Policy on submissions to multiple groups
----------------------------------------

You should NOT submit packages to CSR that have also been submitted to,
or posted in, one of the other Usenet groups (comp.sources.misc,
comp.sources.unix, alt.sources, etc.) in the SAME FORM.  CSR will
consider submissions that have been revised since they were posted to
another sources group.  The group alt.sources can be useful for early
testing of software and one might post to alt.sources to get some
initial reaction, make revisions, and then submit to CSR.


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.  The prefered shar program
is Rich Salz' "cshar2" program, which can be found in the
comp.sources.unix archives (Volume 15) or you can get it from me.  The
shar files should be around 50 K in length, and should never exceed 60
K.  A "modern" shell archiving program that places 'X' characters at the
beginning of each line is usually required.  Also, submission files
should NOT contain ANY control characters since these often do not
survive mailing.  Contact the moderator if you need more information.

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.  Submissions
that are not complete may be returned to the author for corrections
before they are sent out for review.

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

MANIFEST: a list of all the files that make-up the submission.

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 ("[e-mail]") 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 description of software to reviewers
- reviewers volunteer for package and receive it from moderator
- 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.