[Savannah-hackers] Re: troubles with new Savannah project

[Robert J. Chassell]

I read through the entire FAQ.  It it provides lots of information.
However, Savannah Project administrators need even more information.

So I revised part of the existing FAQ Texinfo source file to serve as
the basis for a new document, the `Savannah Project Administrators
Manual and FAQ'.

The new Texinfo source file, `savannah-project-admin.texi', formats
without reported error to HTML, Info, and plain text.  It formats to
DVI without trouble, but with some underfull hboxes that can be
ignored safely.  The DVI formats without reported error to PostScript.

The documentation itself is incomplete -- I incorporated the first
section of the existing FAQ, the one about Registration, but none of
the rest.  Every existing part needs revision.  Also, I put in lots of
`!!! NEED text' and such comments.

However, the file provides a framework that you can use to create real
documentation.

Most of what you need is provided by the FAQ.

Also, as you can see in address@hidden Overview', I wrote the first draft of a
beginning section to tell readers what a Project consists of.

People need this sort of introduction; otherwise they may get confused
or refer to pages erroneously as both Mathieu Roy <address@hidden> and
I did.  To fix this problem, I named the two main project pages in a
way that should prevent confusion:

  * The `Project Operations page' contains the links to the CVS
    repository, the mailing lists, and so on.

  * The `Project Home page' describes the project; it is written in
    HTML that the administrator provides and appears on www.gnu.org

Here is the Texinfo source file:


\input texinfo                @c -*- Texinfo -*-
@c %**start of header
@setfilename savannah-project-admin.info
@settitle Savannah Project Administrators Manual and FAQ
@setchapternewpage on
@c finalout
@set edition-number 2.0
@set update-date 2002 Sep 19
@c %**end of header

@ignore
 ## Summary of shell commands to create various output formats:

    ## Info output
    makeinfo --force --fill-column=70 --no-split --paragraph-indent=0 \
    --verbose savannah-project-admin.texi

    ## HTML output
    makeinfo --no-split --html --verbose savannah-project-admin.texi

    ## DVI output
    texi2dvi savannah-project-admin.texi

    ## Create PostScript from DVI
    dvi2ps savannah-project-admin.dvi > savannah-project-admin.ps

    ## Plain text output
    makeinfo --fill-column=70 --no-split --paragraph-indent=0  \
    --verbose --no-headers --output=savannah-project-admin.txt \
    savannah-project-admin.texi

@end ignore

@dircategory Savannah
@direntry
* Savannah Project Administrator: (savannah-project-admin.info).
                        How to set up and run a project on Savannah.
@end direntry

@copying
This is a manual and FAQ on how to set up and run a project on
Savannah.

Edition @value{edition-number}, @value{update-date}

Copyright @copyright{} 2001, 2002 Free Software Foundation, Inc.

@quotation
Permission is granted to make and distribute verbatim copies
of this entire document without royalty provided the
copyright notice and this permission notice are preserved on
all copies.

@c    The remainder of this paragraph applies to and should
@c    appear in the Texinfo source.
@c Permission is granted to process this file through TeX or
@c other converter and publish the results, provided the
@c published document carries a copying permission notice
@c identical to this one except for the removal of this
@c paragraph (this paragraph not being relevant to the
@c published document).
@end quotation
@end copying

@c half title; three lines here, so do not use `shorttitlepage'
@tex
{\begingroup%
    \hbox{}\vskip 1.5in \chaprm \centerline{Savannah}%
        \endgroup}%
{\begingroup%
    \hbox{}\vskip 0.25in \chaprm \centerline{Project Administrators Manual}%
        \endgroup}%
{\begingroup\hbox{}\vskip 0.25in \chaprm%
        \centerline{and FAQ}%
        \endgroup\page\hbox{}\page}
@end tex

@titlepage
@sp 6
@center @titlefont{Savannah}
@sp 2
@center @titlefont{Project Administrators Manual}
@sp 2
@center @titlefont{and FAQ}
@sp 2
@center Edition @value{edition-number}, @value{update-date}
@sp 2
@center by the Savannah Project authors
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents


@ifnottex
@node Top, Overview, (dir), (dir)
@top Savannah Project Administrators Manual and FAQ
@insertcopying
@end ifnottex

@menu
* Overview::
* registration process::
* YET MORE::
* Index::
@end menu

@node Overview, registration process, Top, Top
@unnumbered Overview
@cindex Overview

A savannah is a place where gnu live.  The Savannah Project is
dedicated to providing a place for people to develop and distribute
Free Software for the GNU Project.

The Savannah software is based on the SourceForge 2.0 software.
!!! PROVIDE more info on the savannah software and its derivation,
but not here; give a cross reference to an appendix.

A project may be a program and its accompanying documentation or
simply be documentation.  Savannah provides many tools for setting up
and running a project:  a CVS repository, a site for snapshot
downloads, a project-specific bug tracker and project-specific mailing
lists.

@need 1000
Generally, a Savannah project possesses two major pages:

@itemize @bullet
@cindex Project Home page, defined
@item
A @dfn{Project Home page} that describes the project.  This page is written
in HTML that the administrator provides.  It is located on
@url{http://www.gnu.org/software/} in a location such as

@smallexample
http://www.gnu.org/software/softfree
@end smallexample

@item
@cindex Project Operations page, defined
A @dfn{Project Operations page} that contains the links to the CVS
repository, the mailing lists, and the rest.  This page is mostly
created automatically by the Savannah software.
@end itemize

@need 1000
When you start a project, you need to:

@enumerate
@cindex Registration
@item
Register your project.  @xref{registration process, ,
What is the registration process?}.

@cindex Project Operations page, info for
@cindex Info for Project Operations page
@item
Fill in the forms for the Project Operations page.  For example, you
need to provide a description. See !!! NEED cross reference here

The project administrator must provide all this information.  None of
the information provided for the registration is automatically copied
from the registration form to the Project Operations page even though
some of the information, such as the description, may well be
identical.  This is because !!! NEED text here

@cindex Project Home page, create
@cindex Create a Project Home page
@item
Write and install a Project Home page.  The project administrator must
provide this page in its entirety.  Unlike the Project Operations
page, no part of this page is generated automatically by the Savannah
software.  This page can be written in Texinfo and converted to HTML
or written directly in HTML.
!!! NEED cross reference here to Texinfo docs.

@cindex CVS repository on Savannah
@cindex Savannah CVS repository
@cindex repository, CVS, on Savannah
@item
Fill your CVS repository on Savannah with files.
See !!! NEED cross reference here

@item
[... and so on.]   !!! NEED text here
@end enumerate

@node registration process, YET MORE, Overview, Top
@chapter What is the Registration Process?
@cindex What is the registration process
@cindex registration process, what is it

@cindex Registration prerequisite..
@cindex Prerequisite for registration
Registration prerequisite..

The steps described in this page are extracted from the project
registration process so that you can have a quick look and figure out
what it requires.  Since these are not the actual registration pages,
they may be out of date (they are current at the date of March, 11
2002). If you notice an inconsistency, please write to
@email{savannah-hackers@@gnu.org, savannah-hackers@@gnu.org}.

@menu
* Registration Services Requirements::
* Basic Information::
* Project Name::
* License::
* Become a GNU package::
@end menu

@node Registration Services Requirements, Basic Information, registration 
process, registration process
@section Services & Requirements
@cindex !!! NEED index entries
@cindex !!! NEED index entries

!!! NEED text here (always need text after a chapter or section
heading before another heading)

@cindex !!! NEED index entries
@subsubheading Use of Project Account

The space given to you on this server is given for the expressed
purpose of advancing Free Software (software development,
documentation, organizing events, system administration of machines
etc.).  Using it to host or advertise non free software is considered
harmful to Free Software.  For more information, please read the
!!! NEED cross reference here to Philosophy of the GNU Project.

@cindex !!! NEED index entries
@subsubheading No dependencies to non free software

Your software may not depend on non free software.  In order to be
available to people who cannot use non free software, it has to be
fully usable with the existing Free Software operating systems and
programs.

@cindex !!! NEED index entries
@subsubheading Advertisements

You may not place any revenue-generating advertisements on a site
hosted here.  But you can point people to commercial support offerings
for your Free Software project.

@cindex !!! NEED index entries
@subsubheading No GIF files

You may not place any GIF files on a site hosted here. For more
information please read Why there are no GIF files on GNU web pages:
@uref{http://www.gnu.org/philosophy/gif.html,,http://www.gnu.org/philosophy/gif.html}

@cindex !!! NEED index entries
@subsubheading Free Software/Rights to Code

You will be presented with a choice of Free Software licenses for your
project. You will still be the owner of the content of your
project. However, all these licenses give the freedom to anyone to
use, copy, study from the source code and modify the software it
contains.

!!! PROVIDE cross references here to list of licenses further on in
this document as well as to Web page on www.gnu.org.

If you wish to use another license that is not listed, let us know and
we will review these requests on a case-by-case basis.

It is our intent to provide a permanent home for all versions of your
project. We do reserve the right, however, to terminate your project
if there is due cause.

@node Basic Information, Project Name, Registration Services Requirements, 
registration process
@section Basic Information
@cindex !!! NEED index entries

We need a short description of your project. This description needs to
contain the purpose of the project and a summarization of your goals.

None of this information is transferred to your Project Operations page.

If the GNU volunteers approve your project account, the account is to
be used purely to meet the goals set forth in this statement. If you
need to change this statement at any time, please inform the GNU
volunteers and we will assist you in getting a new statement approved.

REQUIRED: Provide detailed, accurate description, with URLs
!!! NEED more text here -- perhaps an example and/or references to several.

@node Project Name, License, Basic Information, registration process
@section Project Name
@cindex !!! NEED index entries

We need some basic technical information for your project.
There are two types of names that will be associated with this project.

Your ``Full Name'' is descriptive, has no real restrictions on it
except for a 40 character limit, and can be changed.

@cindex !!! NEED index entries
@need 1000
Your ``System Name'' is important, because it will be used for many
things, including:

@itemize @bullet
@item
Directory names
@item
CVS repository name
@item
Group names
@item
Search engines throughout the site
@end itemize

@cindex !!! NEED index entries
@need 1000
However, your "System Name" has several restrictions because it is
used in so many places around the site.  They are:

@itemize @bullet
@item
Cannot match the system name of any other project
@item
Must be between 2 and 12 characters in length
@item
Can only contain characters, numbers, and dashes
@item
Must be a valid system username
@item
Cannot match one of our reserved domains
@item
System name will never change for this project
@end itemize


@node License, Become a GNU package, Project Name, registration process
@section License
@cindex !!! NEED index entries

If you are applying to become a webmaster of a part of the
@uref{http://www.gnu.org} Web site, please select ``website-only''
from the choices below and proceed.  Also check that the directory you
intend to work on is not already associated with an existing Savannah
project.  See
@uref{http://www.gnu.org/server/standards/www2savannah.html,,http://www.gnu.org/server/standards/www2savannah.html}

@cindex !!! NEED index entries
Choosing a license is a serious decision. Please take some time to
read the text (and our explanations) of several licenses before making
a choice about your project.  See
@uref{http://www.gnu.org/philosophy/license-list.html,,http://www.gnu.org/philosophy/license-list.html}

@cindex !!! NEED index entries
In order to release your project, you should write copyright notices
and license notices at the beginning of every source code file, and
include a copy of the plain text version of the license.  If your
software is published under the GNU GPL license, you should read the
section about applying license terms to your program.  See
@uref{http://www.gnu.org/copyleft/gpl.html#SEC4,,http://www.gnu.org/copyleft/gpl.html#SEC4}

@cindex !!! NEED index entries
For many legal reasons, you may not change a project's license once it
has been set.  If you feel that you have a special case and legal
capability to do this, we will work with you on a case-by-case basis.

@cindex !!! NEED index entries
@subsubheading Licenses compatible with the GNU GPL

Here is a list of licenses compatible with the GNU GPL
Also, see
!!! NEED cross reference here to GNU Web page on licenses

@uref{http://www.gnu.org/copyleft/gpl.html,,http://www.gnu.org/copyleft/gpl.html}
 GNU General Public License

@uref{http://www.gnu.org/copyleft/lesser.html,,http://www.gnu.org/copyleft/lesser.html}
 GNU Lesser General Public License

@uref{http://www.gnu.org/copyleft/fdl.html,,http://www.gnu.org/copyleft/fdl.html}
 GNU Free Documentation License

@uref{http://www.x.org/terms.htm,,http://www.x.org/terms.htm} X11 license

@uref{http://www.cryptix.org/docs/license.html,,http://www.cryptix.org/docs/license.html}
 Cryptix General License

@uref{http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5,,http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5}
 Modified BSD license

@uref{ftp://ftp.freesoftware.com/pub/infozip/zlib/zlib_license.html,,ftp://ftp.freesoftware.com/pub/infozip/zlib/zlib_license.html}
 The
license of ZLib.

The license of the iMatix Standard Function Library

@uref{http://www.w3.org/Consortium/Legal/copyright-software.html,,http://www.w3.org/Consortium/Legal/copyright-software.html}
 The
W3C Software Notice and License

@uref{http://www.sleepycat.com/license.net,,http://www.sleepycat.com/license.net}
 The Berkeley Database License

(aka 
@uref{http://www.sleepycat.com/docs/sleepycat/license.html,,http://www.sleepycat.com/docs/sleepycat/license.html}
 the Sleepycat Software Product License)

@uref{http://www.python.org/doc/Copyright.html,,http://www.python.org/doc/Copyright.html}
 The License of
Python 1.6a2 and earlier versions

@uref{http://www.statistica.unimib.it/utenti/dellavedova/software/artistic2.html,,http://www.statistica.unimib.it/utenti/dellavedova/software/artistic2.html}
 The Clarified Artistic License

@uref{http://www.gnu.org/licenses/license-list.html#Expat,,http://www.gnu.org/licenses/license-list.html#Expat}
 Expat license


@node Become a GNU package,  , License, registration process
@section Become a GNU package
@cindex !!! NEED index entries

Calling a program GNU software means that its developers and the GNU
project agree that ``This program is part of the GNU project, released
under the aegis of GNU'' --- and say so in the program.

@cindex !!! NEED index entries
This means that we normally put the program on @file{ftp.gnu.org}
(although we could instead refer to the developer's choice of @sc{ftp}
site) and that we put the official pages describing the program on the
GNU web server.  (It is OK to have more informal pages about secondary
issues, such as discussion meant for people who want to help develop
the package, on some other site.)

It means that the developers agree to pay some attention to making the
program work well with the rest of the GNU system --- and conversely
that the GNU project will encourage other GNU maintainers to pay some
attention to making their programs fit in well with it.

@cindex !!! NEED index entries
Just what it means to make programs work well together is mainly a
practical matter that depends on what the program does.  But there are
a few general principles.  Certain parts of the GNU coding standards
directly affect the consistency of the whole system.  These include
the standards for configuring and building a program, and the
standards for command-line options.  It is important to make all GNU
programs follow these standards, where they are applicable.

@cindex !!! NEED index entries
Another important GNU standard is that GNU programs should come with
documentation in Texinfo format.  That is the GNU standard
documentation format, and it can be converted automatically into
various other formats.

@cindex !!! NEED index entries
If a GNU program wants to be extensible, it should use the GUILE
language for extensibility--that is the GNU standard extensibility
package.  See
@uref{http://www.gnu.org/software/guile/guile.html,,http://www.gnu.org/software/guile/guile.html}
 )
If the program doesn't use GUILE today, at least there should be a
firm plan to support it in the future.

A GNU program should use the latest version of a license that the GNU
Project recommends --- not just any free software license.

A GNU program should not recommend use of any non-free program, and it
should not refer the user to any non-free documentation for free
software.  The need for free documentation to go with free software is
now a major focus of the GNU project; to show that we are serious
about the need for free documentation, we must not contradict our
position by recommending use of documentation that isn't free.

Occasionally there are issues of terminology which are important for
the success of the GNU project as a whole.  So we expect maintainers
of GNU programs to follow them.  For example, the documentation files
and comments in the program should speak of Linux-based GNU systems or
GNU/Linux systems, rather than calling the whole system "Linux", and
should use the term "free software" rather than "open source".

Deciding that a program is GNU software does not necessarily require
transferring copyright to the FSF; that is a separate question.  If
you transfer the copyright to the FSF, the FSF will enforce the GPL
for the program if someone violates it; if you keep the copyright,
enforcement will be up to you.

@node YET MORE, Index, registration process, Top
@chapter YET MORE @dots{}

The rest of the manual/FAQ can go here.  Much of the work has already
been done.  The current Texinfo source needs some work, but provides
a good beginning.

@node Index,  , YET MORE, Top
@unnumbered Index

@ignore
MENU ENTRY: NODE NAME.
@end ignore

@printindex cp

@bye