2718 lines
67 KiB
HTML
2718 lines
67 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>Software Release Practice HOWTO</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD
|
|
><BODY
|
|
CLASS="article"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="ARTICLE"
|
|
><DIV
|
|
CLASS="TITLEPAGE"
|
|
><H1
|
|
CLASS="title"
|
|
><A
|
|
NAME="AEN2"
|
|
></A
|
|
>Software Release Practice HOWTO</H1
|
|
><H3
|
|
CLASS="author"
|
|
><A
|
|
NAME="AEN4"
|
|
>Eric Steven Raymond</A
|
|
></H3
|
|
><DIV
|
|
CLASS="affiliation"
|
|
><SPAN
|
|
CLASS="orgname"
|
|
><A
|
|
HREF="http://www.catb.org/~esr/"
|
|
TARGET="_top"
|
|
> Thyrsus Enterprises</A
|
|
><BR></SPAN
|
|
><DIV
|
|
CLASS="address"
|
|
><P
|
|
CLASS="address"
|
|
><br>
|
|
<TT
|
|
CLASS="email"
|
|
><<A
|
|
HREF="mailto:esr@thyrsus.com"
|
|
>esr@thyrsus.com</A
|
|
>></TT
|
|
><br>
|
|
</P
|
|
></DIV
|
|
></DIV
|
|
><P
|
|
CLASS="copyright"
|
|
>Copyright © 2000 Eric S. Raymond</P
|
|
><DIV
|
|
CLASS="revhistory"
|
|
><TABLE
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TH
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
COLSPAN="3"
|
|
><B
|
|
>Revision History</B
|
|
></TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revision 4.1</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>2013-01-14</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revised by: esr</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
COLSPAN="3"
|
|
>Check out from a repo to be sure of making patches against fresh code.
|
|
Freshmeat changed its name. USENET topic groups aren't very visible
|
|
any more.</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revision 4.0</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>2010-04-11</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revised by: esr</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
COLSPAN="3"
|
|
>It's no longer necessary to provide RPMS or debs at project
|
|
level. The packaging infrastructure has gotten good at that.
|
|
New caveats about configuration and autotools. AsciiDOC
|
|
is now a viable alternative for documentation masters.</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revision 3.9</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>2004-11-28</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revised by: esr</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
COLSPAN="3"
|
|
>New material on good patching practice. Recommend Electric Fence
|
|
and valgrind rather than proprietary tools.</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revision 3.8</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>2003-02-17</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revised by: esr</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
COLSPAN="3"
|
|
>URL fixups after site move.</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revision 3.7</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>2002-09-25</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revised by: esr</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
COLSPAN="3"
|
|
>Point at the DocBook Demystification HOWTO.</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revision 3.6</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>2002-09-12</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revised by: esr</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
COLSPAN="3"
|
|
>Incorporated material on portability by Keith Bostic.</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revision 3.6</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>2002-08-14</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revised by: esr</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
COLSPAN="3"
|
|
>Rewrote section on documentation practice, since XML-Docbook is
|
|
mature now.</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revision 3.5</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>2002-07-04</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revised by: esr</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
COLSPAN="3"
|
|
>Added section on providing checksums. Cited doclifter.</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revision 3.4</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>2002-01-04</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revised by: esr</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
COLSPAN="3"
|
|
>More about good patching practice.</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revision 3.3</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>2001-08-16</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revised by: esr</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
COLSPAN="3"
|
|
>New section about how to send good patches.</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revision 3.2</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>2001-07-11</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revised by: esr</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
COLSPAN="3"
|
|
>Note about not relying on proprietary components.</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revision 3.1</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>2001-02-22</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revised by: esr</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
COLSPAN="3"
|
|
>LDP Styleguide fixes.</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revision 3.0</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>2000-08-12</TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
>Revised by: esr</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
ALIGN="LEFT"
|
|
COLSPAN="3"
|
|
>First DocBook version. Advice on SourceForge and a major section
|
|
on documentation practice added.</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><DIV
|
|
><DIV
|
|
CLASS="abstract"
|
|
><A
|
|
NAME="AEN82"
|
|
></A
|
|
><P
|
|
></P
|
|
><P
|
|
>This HOWTO describes good release practices for Linux and other
|
|
open-source projects. By following these practices, you will make it
|
|
as easy as possible for users to build your code and use it, and for
|
|
other developers to understand your code and cooperate with you to
|
|
improve it.</P
|
|
><P
|
|
>This document is a must-read for novice developers. Experienced
|
|
developers should review it when they are about to release a new
|
|
project. It will be revised periodically to reflect the evolution of
|
|
good-practice standards.</P
|
|
><P
|
|
></P
|
|
></DIV
|
|
></DIV
|
|
><HR></DIV
|
|
><DIV
|
|
CLASS="TOC"
|
|
><DL
|
|
><DT
|
|
><B
|
|
>Table of Contents</B
|
|
></DT
|
|
><DT
|
|
>1. <A
|
|
HREF="#introduction"
|
|
>Introduction</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>1.1. <A
|
|
HREF="#purpose"
|
|
>Why this document?</A
|
|
></DT
|
|
><DT
|
|
>1.2. <A
|
|
HREF="#newversions"
|
|
>New versions of this document</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>2. <A
|
|
HREF="#patching"
|
|
>Good patching practice</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>2.1. <A
|
|
HREF="#AEN107"
|
|
>Do send patches, don't send whole archives or files</A
|
|
></DT
|
|
><DT
|
|
>2.2. <A
|
|
HREF="#AEN117"
|
|
>Send patches against the current version of the code.</A
|
|
></DT
|
|
><DT
|
|
>2.3. <A
|
|
HREF="#AEN123"
|
|
>Don't include patches for generated files.</A
|
|
></DT
|
|
><DT
|
|
>2.4. <A
|
|
HREF="#AEN133"
|
|
>Don't send patch bands that just tweak version-control $-symbols.</A
|
|
></DT
|
|
><DT
|
|
>2.5. <A
|
|
HREF="#AEN140"
|
|
>Do use -c or -u format, don't use the default (-e) format</A
|
|
></DT
|
|
><DT
|
|
>2.6. <A
|
|
HREF="#AEN147"
|
|
>Do include documentation with your patch</A
|
|
></DT
|
|
><DT
|
|
>2.7. <A
|
|
HREF="#AEN154"
|
|
>Do include an explanation with your patch</A
|
|
></DT
|
|
><DT
|
|
>2.8. <A
|
|
HREF="#AEN169"
|
|
>Do include useful comments in your code</A
|
|
></DT
|
|
><DT
|
|
>2.9. <A
|
|
HREF="#AEN182"
|
|
>Just one bugfix or new feature per patch.</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>3. <A
|
|
HREF="#naming"
|
|
>Good project- and archive- naming practice</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>3.1. <A
|
|
HREF="#AEN192"
|
|
>Use GNU-style names with a stem and major.minor.patch numbering.</A
|
|
></DT
|
|
><DT
|
|
>3.2. <A
|
|
HREF="#local"
|
|
>But respect local conventions where appropriate</A
|
|
></DT
|
|
><DT
|
|
>3.3. <A
|
|
HREF="#prefix"
|
|
>Try hard to choose a name prefix that is unique and easy to type</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>4. <A
|
|
HREF="#licensetheory"
|
|
>Good licensing and copyright practice: the theory</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>4.1. <A
|
|
HREF="#copyrights"
|
|
>Open source and copyrights</A
|
|
></DT
|
|
><DT
|
|
>4.2. <A
|
|
HREF="#opensource"
|
|
>What qualifies as open source</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>5. <A
|
|
HREF="#licensepractice"
|
|
>Good licensing and copyright practice: the practice</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>5.1. <A
|
|
HREF="#holder"
|
|
>Make yourself or the FSF the copyright holder</A
|
|
></DT
|
|
><DT
|
|
>5.2. <A
|
|
HREF="#osd"
|
|
>Use a license conformant to the Open Source Definition</A
|
|
></DT
|
|
><DT
|
|
>5.3. <A
|
|
HREF="#unoriginal"
|
|
>Don't write your own license if you can possibly avoid it.</A
|
|
></DT
|
|
><DT
|
|
>5.4. <A
|
|
HREF="#visible"
|
|
>Make your license visible in a standard place.</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>6. <A
|
|
HREF="#develpractice"
|
|
>Good development practice</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>6.1. <A
|
|
HREF="#language"
|
|
>Choose the most portable language you can</A
|
|
></DT
|
|
><DT
|
|
>6.2. <A
|
|
HREF="#proprietary"
|
|
>Don't rely on proprietary code</A
|
|
></DT
|
|
><DT
|
|
>6.3. <A
|
|
HREF="#build_systems"
|
|
>Build systems</A
|
|
></DT
|
|
><DT
|
|
>6.4. <A
|
|
HREF="#testcode"
|
|
>Test your code before release</A
|
|
></DT
|
|
><DT
|
|
>6.5. <A
|
|
HREF="#sanitycode"
|
|
>Sanity-check your code before release</A
|
|
></DT
|
|
><DT
|
|
>6.6. <A
|
|
HREF="#sanitydocs"
|
|
>Sanity-check your documentation and READMEs before release</A
|
|
></DT
|
|
><DT
|
|
>6.7. <A
|
|
HREF="#cport"
|
|
>Recommended C/C++ portability practices</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>7. <A
|
|
HREF="#distpractice"
|
|
>Good distribution-making practice</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>7.1. <A
|
|
HREF="#tarballs"
|
|
>Make sure tarballs always unpack into a single new directory</A
|
|
></DT
|
|
><DT
|
|
>7.2. <A
|
|
HREF="#readme"
|
|
>Have a README</A
|
|
></DT
|
|
><DT
|
|
>7.3. <A
|
|
HREF="#filenames"
|
|
>Respect and follow standard file naming practices</A
|
|
></DT
|
|
><DT
|
|
>7.4. <A
|
|
HREF="#upgradeability"
|
|
>Design for Upgradability</A
|
|
></DT
|
|
><DT
|
|
>7.5. <A
|
|
HREF="#checksums"
|
|
>Provide checksums</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>8. <A
|
|
HREF="#documentation"
|
|
>Good documentation practice</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>8.1. <A
|
|
HREF="#docpractice"
|
|
>Documentation formats</A
|
|
></DT
|
|
><DT
|
|
>8.2. <A
|
|
HREF="#AEN547"
|
|
>Good practice recommendations</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>9. <A
|
|
HREF="#communication"
|
|
>Good communication practice</A
|
|
></DT
|
|
><DD
|
|
><DL
|
|
><DT
|
|
>9.1. <A
|
|
HREF="#announce"
|
|
>Announce to Freecode</A
|
|
></DT
|
|
><DT
|
|
>9.2. <A
|
|
HREF="#website"
|
|
>Have a website</A
|
|
></DT
|
|
><DT
|
|
>9.3. <A
|
|
HREF="#lists"
|
|
>Host project mailing lists</A
|
|
></DT
|
|
><DT
|
|
>9.4. <A
|
|
HREF="#archives"
|
|
>Release to major archives</A
|
|
></DT
|
|
></DL
|
|
></DD
|
|
><DT
|
|
>10. <A
|
|
HREF="#management"
|
|
>Good project-management practice</A
|
|
></DT
|
|
></DL
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect1"
|
|
><H1
|
|
CLASS="sect1"
|
|
><A
|
|
NAME="introduction"
|
|
></A
|
|
>1. Introduction</H1
|
|
><DIV
|
|
CLASS="sect2"
|
|
><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="purpose"
|
|
></A
|
|
>1.1. Why this document?</H2
|
|
><P
|
|
>There is a large body of good-practice traditions for
|
|
open-source code that helps other people port, use, and cooperate with
|
|
developing it. Some of these conventions are traditional in the Unix
|
|
world and predate Linux; others have developed recently in response to
|
|
particular new tools and technologies such as the World Wide
|
|
Web.</P
|
|
><P
|
|
>This document will help you learn good practice. It is organized
|
|
into topic sections, each containing a series of checklist items. Think of
|
|
these as a pre-flight checklist for your patch or software
|
|
distribution.</P
|
|
><P
|
|
>A translation into
|
|
<A
|
|
HREF="http://www.sschubiger.ch/services/content/documents/computer/software-release-practice-howto/"
|
|
TARGET="_top"
|
|
>German</A
|
|
>
|
|
is available.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="newversions"
|
|
></A
|
|
>1.2. New versions of this document</H2
|
|
><P
|
|
>This document will be posted monthly to the newsgroups <A
|
|
HREF="News:comp.os.linux.answers"
|
|
TARGET="_top"
|
|
>comp.os.linux.answers</A
|
|
>. You
|
|
can also view the latest version of this HOWTO on the World Wide Web
|
|
via the URL <A
|
|
HREF="http://tldp.org/HOWTO/Software-Release-Practice-HOWTO.html"
|
|
TARGET="_top"
|
|
> http://tldp.org/HOWTO/Software-Release-Practice.html</A
|
|
>.
|
|
</P
|
|
><P
|
|
>Feel free to mail any questions or comments about this HOWTO to
|
|
Eric S. Raymond, <TT
|
|
CLASS="email"
|
|
><<A
|
|
HREF="mailto:esr@snark.thyrsus.com"
|
|
>esr@snark.thyrsus.com</A
|
|
>></TT
|
|
>.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect1"
|
|
><HR><H1
|
|
CLASS="sect1"
|
|
><A
|
|
NAME="patching"
|
|
></A
|
|
>2. Good patching practice</H1
|
|
><P
|
|
>Most people get involved in open-source software by writing patches
|
|
for other peoples' software before releasing projects of their own.
|
|
Suppose you've written a set of source-code changes for someone else's
|
|
baseline code. Now put yourself in that person's shoes. How is he
|
|
to judge whether to include the patch?</P
|
|
><P
|
|
>The truth is that it is very difficult to judge the quality of code.
|
|
So developers tend to evaluate patches by the quality of the submission.
|
|
They look for clues in the submitter's style and communications behavior
|
|
instead — indications that the person has been in their shoes and
|
|
understands what it's like to have to evaluate and merge an incoming patch.
|
|
</P
|
|
><P
|
|
>This is actually a pretty reliable proxy for code quality. In many
|
|
years of dealing with patches from many hundreds of strangers, I have only
|
|
seldom seen a patch that was thoughtfully presented and respectful of my
|
|
time but technically bogus. On the other hand, experience teaches me that
|
|
patches which look careless or are packaged in a lazy and inconsiderate way
|
|
are very likely to actually <EM
|
|
>be</EM
|
|
> bogus.</P
|
|
><P
|
|
>Here are some tips on how to get your patch accepted:</P
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="AEN107"
|
|
></A
|
|
>2.1. Do send patches, don't send whole archives or files</H2
|
|
><P
|
|
>If your change includes a new file that doesn't exist in the code,
|
|
then of course you have to send the whole file. But if you're modifying
|
|
an already-existing file, don't send the whole file. Send a diff instead;
|
|
specifically, send the output of the
|
|
<SPAN
|
|
CLASS="citerefentry"
|
|
><SPAN
|
|
CLASS="refentrytitle"
|
|
>diff</SPAN
|
|
>(1)</SPAN
|
|
>
|
|
command run to compare the baseline distributed version against your
|
|
modified version.</P
|
|
><P
|
|
>The diff command and its dual,
|
|
<SPAN
|
|
CLASS="citerefentry"
|
|
><SPAN
|
|
CLASS="refentrytitle"
|
|
>patch</SPAN
|
|
>(1)</SPAN
|
|
>
|
|
(which automatically applies a diff to a baseline file)
|
|
are the most basic tools of open-source development. Diffs are better
|
|
than whole files because the developer you're sending a patch to may
|
|
have changed the baseline version since you got your copy. By sending
|
|
him a diff you save him the effort of separating your changes from his;
|
|
you show respect for his time.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="AEN117"
|
|
></A
|
|
>2.2. Send patches against the current version of the code.</H2
|
|
><P
|
|
>It is both counterproductive and rude to send a maintainer
|
|
patches against the code as it existed several releases ago, and expect
|
|
him to do all the work of determining which changes duplicate things he
|
|
have since done, versus which things are actually novel in your patch.</P
|
|
><P
|
|
>As a patch submitter, it is <EM
|
|
>your</EM
|
|
> responsibility
|
|
to track the state of the source and send the maintainer a minimal patch
|
|
that expresses what you want done to the main-line codebase. That means
|
|
sending a patch against the current version.</P
|
|
><P
|
|
>Nowadays effectively all open-source projects make their source code
|
|
available through public anonymous access to the project's version-control
|
|
repositrity. The most effective way to ensure that you're patching what's
|
|
current is to check the head version of the code out of the project's
|
|
repository. All version-control systems have a command that lets you
|
|
make a diff between your working copy and head; use that.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="AEN123"
|
|
></A
|
|
>2.3. Don't include patches for generated files.</H2
|
|
><P
|
|
>Before you send your patch, walk through it and delete any
|
|
patch bands for files in it that are going to be automatically regenerated
|
|
once he applies the patch and remakes. The classic examples of this
|
|
error are C files generated by <SPAN
|
|
CLASS="application"
|
|
>Bison</SPAN
|
|
>
|
|
or <SPAN
|
|
CLASS="application"
|
|
>Flex</SPAN
|
|
>.</P
|
|
><P
|
|
>These days the most common mistake of this kind is sending a diff
|
|
with a huge band that is nothing but changebars between your
|
|
<B
|
|
CLASS="command"
|
|
>configure</B
|
|
> script and his. This file is generated by
|
|
<B
|
|
CLASS="command"
|
|
>autoconf</B
|
|
>.</P
|
|
><P
|
|
>This is inconsiderate. It means your recipient is put to the trouble
|
|
of separating the real content of the patch from a lot of bulky noise.
|
|
It's a minor error, not as important as some of the things we'll get
|
|
to further on — but it will count against you.</P
|
|
><P
|
|
>You will probably avoid this automatically if you have checked out
|
|
the code from the project repo and use the version-control system's diff
|
|
command to generate your patch.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="AEN133"
|
|
></A
|
|
>2.4. Don't send patch bands that just tweak version-control $-symbols.</H2
|
|
><P
|
|
>Some people put special tokens in their source files that are
|
|
expanded by the version-control system when the file is checked in: the
|
|
<SPAN
|
|
CLASS="markup"
|
|
>$Id$</SPAN
|
|
> construct used by RCS, CVS, and
|
|
Subversion, for example.</P
|
|
><P
|
|
>If you're using a local version-control system yourself, your changes
|
|
may alter these tokens. This isn't really harmful, because when your
|
|
recipient checks his code back in after applying your patch they'll get
|
|
re-expanded based on <EM
|
|
>his</EM
|
|
> version-control status. But
|
|
those extra patch bands are noise. They're distracting. It's more
|
|
considerate not to send them.</P
|
|
><P
|
|
>This is another minor error. You'll be forgiven for it if you
|
|
get the big things right. But you want to avoid it anyway.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="AEN140"
|
|
></A
|
|
>2.5. Do use -c or -u format, don't use the default (-e) format</H2
|
|
><P
|
|
>The default (-e) format of
|
|
<SPAN
|
|
CLASS="citerefentry"
|
|
><SPAN
|
|
CLASS="refentrytitle"
|
|
>diff</SPAN
|
|
>(1)</SPAN
|
|
>
|
|
is very brittle. It doesn't include any context, so the patch tool
|
|
can't cope if any lines have been inserted or deleted in the baseline
|
|
code since you took the copy you modified.</P
|
|
><P
|
|
>Getting an -e diff is annoying, and suggests that the sender is
|
|
either an extreme newbie, careless, or clueless. Most such patches
|
|
get tossed out without a second thought.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="AEN147"
|
|
></A
|
|
>2.6. Do include documentation with your patch</H2
|
|
><P
|
|
>This is very important. If your patch makes a user-visible addition
|
|
or change to the software's features, <EM
|
|
>include changes to the
|
|
appropriate man pages and other documentation files in your patch</EM
|
|
>.
|
|
Do <EM
|
|
>not</EM
|
|
> assume that the recipient will be happy to
|
|
document your code for you, or else to have undocumented features lurking
|
|
in the code.</P
|
|
><P
|
|
>Documenting your changes well demonstrates some good things. First,
|
|
it's considerate to the person you are trying to persuade. Second, it
|
|
shows that you understand the ramifications of your change well enough
|
|
to explain it to somebody who can't see the code. Third, it demonstrates
|
|
that you care about the people who will ultimately use the software.</P
|
|
><P
|
|
>Good documentation is usually the most visible sign of what separates
|
|
a solid contribution from a quick and dirty hack. If you take the time
|
|
and care necessary to produce it, you'll find you're already 85% of the
|
|
way to having your patch accepted with most developers.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="AEN154"
|
|
></A
|
|
>2.7. Do include an explanation with your patch</H2
|
|
><P
|
|
>Your patch should include cover notes explaining why you think the
|
|
patch is necessary or useful. This is explanation directed not to the
|
|
users of the software but to the maintainer to whom you are sending the
|
|
patch.</P
|
|
><P
|
|
>The note can be short — in fact, some of the most effective
|
|
cover notes I've ever seen just said "See the documentation updates in this
|
|
patch". But it should show the right attitude.</P
|
|
><P
|
|
>The right attitude is helpful, respectful of the maintainer's time,
|
|
quietly confident but unassuming. It's good to display understanding of
|
|
the code you're patching. It's good to show that you can identify with the
|
|
maintainer's problems. It's also good to be up front about any risks you
|
|
perceive in applying the patch. Here are some examples of the sorts of
|
|
explanatory comments that I like to see in cover notes:</P
|
|
><P
|
|
><SPAN
|
|
CLASS="QUOTE"
|
|
>"
|
|
I've seen two problems with this code, X and Y. I fixed problem X, but I
|
|
didn't try addressing problem Y because I don't think I understand
|
|
the part of the code that I believe is involved.
|
|
"</SPAN
|
|
></P
|
|
><P
|
|
><SPAN
|
|
CLASS="QUOTE"
|
|
>"
|
|
Fixed a core dump that can happen when one of the foo inputs is too long.
|
|
While I was at it, I went looking for similar overflows elsewhere. I
|
|
found a possible one in blarg.c, near line 666. Are you sure the sender
|
|
can't generate more than 80 characters per transmission?
|
|
"</SPAN
|
|
></P
|
|
><P
|
|
><SPAN
|
|
CLASS="QUOTE"
|
|
>"
|
|
Have you considered using the Foonly algorithm for this problem? There
|
|
is a good implementation at <http://www.somesite.com/~jsmith/foonly.html>.
|
|
"</SPAN
|
|
></P
|
|
><P
|
|
><SPAN
|
|
CLASS="QUOTE"
|
|
>"
|
|
This patch solves the immediate problem, but I realize it complicates the
|
|
memory allocation in an unpleasant way. Works for me, but you should
|
|
probably test it under heavy load before shipping.
|
|
"</SPAN
|
|
></P
|
|
><P
|
|
><SPAN
|
|
CLASS="QUOTE"
|
|
>"
|
|
This may be featurititis, but I'm sending it anyway. Maybe you'll know a
|
|
cleaner way to implement the feature.
|
|
"</SPAN
|
|
></P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="AEN169"
|
|
></A
|
|
>2.8. Do include useful comments in your code</H2
|
|
><P
|
|
>Usually as a maintainer, I will want to have strong confidence that I
|
|
understand your changes before merging them in. This isn't an invariable
|
|
rule; if you have a track record of good work, with me I may just run a
|
|
casual eyeball over the changes before checking them in semi-automatically.
|
|
But everything you can do to help me understand your code and decrease my
|
|
uncertainty increases your chances that I will accept your patch.</P
|
|
><P
|
|
>Good comments in your code help me understand it. Bad comments
|
|
don't.</P
|
|
><P
|
|
>Here's an example of a bad comment:</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
> /* norman newbie fixed this 13 Aug 2009 */
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
>This conveys no information. It's nothing but a muddy territorial
|
|
bootprint you're planting in the middle of my code. If I take your patch
|
|
(which you've made less likely) I'll almost certainly strip out this
|
|
comment. If you want a credit, include a patch band for the project
|
|
<TT
|
|
CLASS="filename"
|
|
>NEWS</TT
|
|
> or <TT
|
|
CLASS="filename"
|
|
>HISTORY</TT
|
|
> file. I'll
|
|
probably take that.</P
|
|
><P
|
|
>Here's an example of a good comment:</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
> /*
|
|
* This conditional needs to be guarded so that crunch_data()
|
|
* never gets passed a NULL pointer. <norman_newbie@foosite.com>
|
|
*/
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
>This comment shows that you understand not only my code but the
|
|
kind of information that I need to have confidence in your changes.
|
|
This kind of comment <EM
|
|
>gives</EM
|
|
> me confidence in your
|
|
changes.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="AEN182"
|
|
></A
|
|
>2.9. Just one bugfix or new feature per patch.</H2
|
|
><P
|
|
>Don't gather various bugfixes, new features or other stuff and
|
|
send them as one single diff file. Instead, build a single diff for every
|
|
bugfix or feature. Every single diff should be generated using the current
|
|
version of the code and should not depend on any other patch you or someone
|
|
else sent before.</P
|
|
><P
|
|
>This helps the maintainer to read and understand your code, and he can
|
|
decide whether he wants to accept or abadon this single bugfix or feature.
|
|
For example, if you add a feature garanting full root access for everyone
|
|
because it's useful in your special setting, the maintainer will probably not
|
|
accept this part of your patch. When you send a single diff file confounding
|
|
this root access feature along with some bugfixes and other useful things, you
|
|
have a good chance the maintainer will ignore your complete patch.</P
|
|
><P
|
|
>With each bugfixes and new feature as a single diff file, the
|
|
maintainer could e.g. include your bugfixes in a few minutes and take later
|
|
a closer look to your new features or security issues.</P
|
|
><P
|
|
>Patches depending on other patches raise similar problems. If the
|
|
maintainer rejects your basic patch, he won't be able to apply the
|
|
others. If you can't avoid such dependencies, offer to the maintainer that
|
|
you will bundle a patch with the sections or features he wants to
|
|
add.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect1"
|
|
><HR><H1
|
|
CLASS="sect1"
|
|
><A
|
|
NAME="naming"
|
|
></A
|
|
>3. Good project- and archive- naming practice</H1
|
|
><P
|
|
>As the load on maintainers of archives like Metalab, the PSA
|
|
site and CPAN increases, there is an increasing trend for submissions
|
|
to be processed partly or wholly by programs (rather than entirely by
|
|
a human).</P
|
|
><P
|
|
>This makes it more important for project and archive-file names
|
|
to fit regular patterns that computer programs can parse and
|
|
understand.</P
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="AEN192"
|
|
></A
|
|
>3.1. Use GNU-style names with a stem and major.minor.patch numbering.</H2
|
|
><P
|
|
>It's helpful to everybody if your archive files all have GNU-like
|
|
names — all-lower-case alphanumeric stem prefix, followed by a dash,
|
|
followed by a version number, extension, and other suffixes.</P
|
|
><P
|
|
>Let's suppose you have a project you call `foobar' at version 1,
|
|
release 2, level 3. If it's got just one archive part (presumably the
|
|
sources), here's what its names should look:</P
|
|
><P
|
|
></P
|
|
><DIV
|
|
CLASS="variablelist"
|
|
><DL
|
|
><DT
|
|
>foobar-1.2.3.tar.gz</DT
|
|
><DD
|
|
><P
|
|
>The source archive</P
|
|
></DD
|
|
><DT
|
|
>foobar.lsm</DT
|
|
><DD
|
|
><P
|
|
>The LSM file (assuming you're submitting to Metalab).</P
|
|
></DD
|
|
></DL
|
|
></DIV
|
|
><P
|
|
>Please <EM
|
|
>don't</EM
|
|
> use these:</P
|
|
><P
|
|
></P
|
|
><DIV
|
|
CLASS="variablelist"
|
|
><DL
|
|
><DT
|
|
>foobar123.tar.gz</DT
|
|
><DD
|
|
><P
|
|
>This looks to many programs like an archive
|
|
for a project called`foobar123' with no version number.</P
|
|
></DD
|
|
><DT
|
|
>foobar1.2.3.tar.gz</DT
|
|
><DD
|
|
><P
|
|
>This looks to many programs like an archive
|
|
for a project called `foobar1' at version 2.3.</P
|
|
></DD
|
|
><DT
|
|
>foobar-v1.2.3.tar.gz</DT
|
|
><DD
|
|
><P
|
|
>Many programs think this goes with a
|
|
project called `foobar-v1'.</P
|
|
></DD
|
|
><DT
|
|
>foo_bar-1.2.3.tar.gz</DT
|
|
><DD
|
|
><P
|
|
>The underscore is hard for people to speak,
|
|
type, and remember.</P
|
|
></DD
|
|
><DT
|
|
>FooBar-1.2.3.tar.gz</DT
|
|
><DD
|
|
><P
|
|
>Unless you <EM
|
|
>like</EM
|
|
> looking like a
|
|
marketing weenie. This is also hard for people to speak, type, and
|
|
remember.</P
|
|
></DD
|
|
></DL
|
|
></DIV
|
|
><P
|
|
>If you have to differentiate between source and binary archives, or
|
|
between different kinds of binary, or express some kind of build
|
|
option in the file name, please treat that as a file extension to go
|
|
<EM
|
|
>after</EM
|
|
> the version number. That is, please do this:</P
|
|
><P
|
|
></P
|
|
><DIV
|
|
CLASS="variablelist"
|
|
><DL
|
|
><DT
|
|
>foobar-1.2.3.src.tar.gz</DT
|
|
><DD
|
|
><P
|
|
>sources</P
|
|
></DD
|
|
><DT
|
|
>foobar-1.2.3.bin.tar.gz</DT
|
|
><DD
|
|
><P
|
|
> binaries, type not specified</P
|
|
></DD
|
|
><DT
|
|
>foobar-1.2.3.bin.ELF.tar.gz</DT
|
|
><DD
|
|
><P
|
|
>ELF binaries</P
|
|
></DD
|
|
><DT
|
|
>foobar-1.2.3.bin.ELF.static.tar.gz</DT
|
|
><DD
|
|
><P
|
|
>ELF binaries statically linked</P
|
|
></DD
|
|
><DT
|
|
>foobar-1.2.3.bin.SPARC.tar.gz</DT
|
|
><DD
|
|
><P
|
|
>SPARC binaries</P
|
|
></DD
|
|
></DL
|
|
></DIV
|
|
><P
|
|
>Please <EM
|
|
>don't</EM
|
|
> use names like
|
|
`foobar-ELF-1.2.3.tar.gz', because programs have a hard time telling
|
|
type infixes (like `-ELF') from the stem.</P
|
|
><P
|
|
>A good general form of name has these parts in order:</P
|
|
><P
|
|
></P
|
|
><OL
|
|
TYPE="1"
|
|
><LI
|
|
><P
|
|
>project prefix</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>dash</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>version number</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>dot</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>"src" or "bin" (optional)</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>dot or dash (dot preferred)</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>binary type and options (optional)</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>archiving and compression extensions</P
|
|
></LI
|
|
></OL
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="local"
|
|
></A
|
|
>3.2. But respect local conventions where appropriate</H2
|
|
><P
|
|
>Some projects and communities have well-defined conventions for names and
|
|
version numbers that aren't necessarily compatible with the above advice.
|
|
For instance, Apache modules are generally named like mod_foo, and have
|
|
both their own version number and the version of Apache with which they
|
|
work. Likewise, Perl modules have version numbers that can be treated as
|
|
floating point numbers (e.g., you might see 1.303 rather than 1.3.3), and
|
|
the distributions are generally named Foo-Bar-1.303.tar.gz for version
|
|
1.303 of module Foo::Bar. (Perl itself, on the other hand, switched to
|
|
using the conventions described in this document in late 1999.)</P
|
|
><P
|
|
>Look for and respect the conventions of specialized
|
|
communities and developers; for general use, follow the above
|
|
guidelines.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="prefix"
|
|
></A
|
|
>3.3. Try hard to choose a name prefix that is unique and easy to type</H2
|
|
><P
|
|
>The stem prefix should be easy to read, type, and remember. So
|
|
please don't use underscores. Don't capitalize or BiCapitalize without
|
|
extremely good reason — it messes up the natural human-eyeball search
|
|
order, among other things.</P
|
|
><P
|
|
>It confuses people when two different projects have the same stem
|
|
name. So try to check for collisions before your first release. Google is
|
|
your friend — and if the stem you're thinking about gets lots of
|
|
Google hits, that in itself may be sufficient reason to think up a
|
|
different one. Another good place to check is
|
|
the application indexes at at <A
|
|
HREF="http://www.freecode.com"
|
|
TARGET="_top"
|
|
>Freecode</A
|
|
> and <A
|
|
HREF="http://www.sourceforge.net"
|
|
TARGET="_top"
|
|
>SourceForge</A
|
|
>; do a name search
|
|
there.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect1"
|
|
><HR><H1
|
|
CLASS="sect1"
|
|
><A
|
|
NAME="licensetheory"
|
|
></A
|
|
>4. Good licensing and copyright practice: the theory</H1
|
|
><P
|
|
>The license you choose defines the social contract you wish to set up
|
|
among your co-developers and users. The copyright you put on the software
|
|
will function mainly as a legal assertion of your right to set license
|
|
terms on the software and derivative works of the software.</P
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="copyrights"
|
|
></A
|
|
>4.1. Open source and copyrights</H2
|
|
><P
|
|
>Anything that is not public domain has a copyright, possibly more than
|
|
one. Under the Berne Convention (which has been U.S. law since 1978),
|
|
the copyright does not have to be explicit. That is, the authors of a
|
|
work hold copyright even if there is no copyright notice.</P
|
|
><P
|
|
> Who counts as an author can be very complicated, especially for
|
|
software that has been worked on by many hands. This is why licenses
|
|
are important. By setting out the terms under which material can be
|
|
used, they grant rights to the users that protect them from arbitrary
|
|
actions by the copyright holders.</P
|
|
><P
|
|
>In proprietary software, the license terms are designed to
|
|
protect the copyright. They're a way of granting a few rights to
|
|
users while reserving as much legal territory is possible for the
|
|
owner (the copyright holder). The copyright holder is very important,
|
|
and the license logic so restrictive that the exact technicalities of
|
|
the license terms are usually unimportant.</P
|
|
><P
|
|
>In open-source software, the situation is usually the exact opposite;
|
|
the copyright exists to protect the license. The only rights the
|
|
copyright holder always keeps are to enforce the license. Otherwise,
|
|
only a few rights are reserved and most choices pass to the user. In
|
|
particular, the copyright holder cannot change the terms on a copy you
|
|
already have. Therefore, in open-source software the copyright holder
|
|
is almost irrelevant — but the license terms are very important.</P
|
|
><P
|
|
>Normally the copyright holder of a project is the current
|
|
project leader or sponsoring organization. Transfer of the project to
|
|
a new leader is often signaled by changing the copyright holder.
|
|
However, this is not a hard and fast rule; many open-source projects
|
|
have multiple copyright holders, and there is no instance on record of
|
|
this leading to legal problems.</P
|
|
><P
|
|
>Some projects choose to assign copyright to the Free Software Foundation,
|
|
on the theory that it has an interest in defending open source and lawyers
|
|
available to do it.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="opensource"
|
|
></A
|
|
>4.2. What qualifies as open source</H2
|
|
><P
|
|
>For licensing purposes, we can distinguish several different
|
|
kinds of rights that a license may convey. Rights to <EM
|
|
>copy
|
|
and redistribute</EM
|
|
>, rights to <EM
|
|
>use</EM
|
|
>,
|
|
rights to <EM
|
|
>modify for personal use</EM
|
|
>, and rights to
|
|
<EM
|
|
>redistribute modified copies</EM
|
|
>. A license may
|
|
restrict or attach conditions to any of these rights.</P
|
|
><P
|
|
>The <A
|
|
HREF="http://www.opensource.org"
|
|
TARGET="_top"
|
|
>Open Source
|
|
Initiative</A
|
|
> is the result of a great deal of thought about what
|
|
makes software <SPAN
|
|
CLASS="QUOTE"
|
|
>"open source"</SPAN
|
|
> or (in older terminology)
|
|
<SPAN
|
|
CLASS="QUOTE"
|
|
>"free software"</SPAN
|
|
>. Its constraints on licensing require that:</P
|
|
><P
|
|
></P
|
|
><OL
|
|
TYPE="1"
|
|
><LI
|
|
><P
|
|
>An unlimited right to copy be granted.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>An unlimited right to use be granted.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>An unlimited right to modify for personal use be granted.</P
|
|
></LI
|
|
></OL
|
|
><P
|
|
>The guidelines prohibit restrictions on redistribution of
|
|
modified binaries; this meets the needs of software distributors, who
|
|
need to be able to ship working code without encumbrance. It allows
|
|
authors to require that modified sources be redistributed as pristine
|
|
sources plus patches, thus establishing the author's intentions and an
|
|
<SPAN
|
|
CLASS="QUOTE"
|
|
>"audit trail"</SPAN
|
|
> of any changes by others.</P
|
|
><P
|
|
>The OSD is the legal definition of the `OSI Certified Open Source'
|
|
certification mark, and as good a definition of <SPAN
|
|
CLASS="QUOTE"
|
|
>"free software"</SPAN
|
|
> as
|
|
anyone has ever come up with. All of the standard licenses (MIT, BSD,
|
|
Artistic, and GPL/LGPL) meet it (though some, like GPL, have other
|
|
restrictions which you should understand before choosing it).</P
|
|
><P
|
|
>Note that licenses which allow noncommercial use only do
|
|
<EM
|
|
>not</EM
|
|
> qualify as open-source licenses, even if they
|
|
are decorated with <SPAN
|
|
CLASS="QUOTE"
|
|
>"GPL"</SPAN
|
|
> or some other standard license. They
|
|
discriminate against particular occupations, persons, and groups.
|
|
They make life too complicated for CD-ROM distributors and others
|
|
trying to spread open-source software commercially.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect1"
|
|
><HR><H1
|
|
CLASS="sect1"
|
|
><A
|
|
NAME="licensepractice"
|
|
></A
|
|
>5. Good licensing and copyright practice: the practice</H1
|
|
><P
|
|
>Here's how to translate the theory above into practice:</P
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="holder"
|
|
></A
|
|
>5.1. Make yourself or the FSF the copyright holder</H2
|
|
><P
|
|
>In some cases, if you have a sponsoring organization behind you with
|
|
lawyers, you might wish to give copyright to that organization.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="osd"
|
|
></A
|
|
>5.2. Use a license conformant to the Open Source Definition</H2
|
|
><P
|
|
>The Open Source Definition is the community gold standard for
|
|
licenses. The OSD is not a license itself; rather, it defines a
|
|
minimum set of rights that a license must guarantee in order to be
|
|
considered an open-source license. The OSD, and supporting materials,
|
|
may be found at the web site of the <A
|
|
HREF="http://www.opensource.org"
|
|
TARGET="_top"
|
|
>Open Source Initiative</A
|
|
>.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="unoriginal"
|
|
></A
|
|
>5.3. Don't write your own license if you can possibly avoid it.</H2
|
|
><P
|
|
>The widely-known OSD-conformant licenses have well-established
|
|
interpretive traditions. Developers (and, to the extent they care, users)
|
|
know what they imply, and have a reasonable take on the risks and tradeoffs
|
|
they involve. Therefore, use one of the standard licenses carried on the
|
|
OSI site if at all possible.</P
|
|
><P
|
|
>If you must write your own license, be sure to have it certified
|
|
by OSI. This will avoid a lot of argument and overhead. Unless
|
|
you've been through it, you have no idea how nasty a licensing
|
|
flamewar can get; people become passionate because the licenses are
|
|
regarded as almost-sacred covenants touching the core values of the
|
|
open-source community.</P
|
|
><P
|
|
>Furthermore, the presence of an established interpretive tradition may
|
|
prove important if your license is ever tested in court. At time of
|
|
writing (early 2002) there is no case law either supporting or invalidating
|
|
any open-source license. However, it is a legal doctrine (at least in
|
|
the U.S., and probably in other common-law countries such as England
|
|
and the rest of the British Commonwealth) that courts are supposed to
|
|
interpret licenses and contracts according to the expectations and
|
|
practices of the community in which they originated.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="visible"
|
|
></A
|
|
>5.4. Make your license visible in a standard place.</H2
|
|
><P
|
|
>As larger and larger volumes of open-source software are deployed,
|
|
the problem of auditing these volumes for which licenses cover them become
|
|
nontrivial — in fact, it becomes larger than an unaided human being
|
|
can perform. Therefore, it is valuable to have conventions that support
|
|
mechanized querying of the licensing information. Fortunately, existing
|
|
community practise already tends in this direction.</P
|
|
><P
|
|
>As a beginning, the license information for your software should
|
|
live in a file named either COPYING or LICENSE in the top-level directory
|
|
of your source distribution. If a single license applies to the entire
|
|
distribution, that file should include a copy of the license. If multiple
|
|
licenses apply, that file should list the applicable licenses and
|
|
indicate to which files and subdirectories they apply.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect1"
|
|
><HR><H1
|
|
CLASS="sect1"
|
|
><A
|
|
NAME="develpractice"
|
|
></A
|
|
>6. Good development practice</H1
|
|
><P
|
|
>Most of these are concerned with ensuring portability across all
|
|
POSIX and POSIX-like systems. Being widely portable is not just a worthy
|
|
form of professionalism and hackerly politeness, it's valuable insurance
|
|
against future changes in Linux.</P
|
|
><P
|
|
>Finally, other people <EM
|
|
>will</EM
|
|
> try to build your
|
|
code on non-Linux systems; portability reduces the amount of support
|
|
email you receive.</P
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="language"
|
|
></A
|
|
>6.1. Choose the most portable language you can</H2
|
|
><P
|
|
>Choose a development language which minimizes the differences of
|
|
the underlying environments in which it will run. C/C++ programs are
|
|
likely to be more portable than Fortran. Java is preferable to C/C++,
|
|
and a high-level scripting language such as Perl, Python or Ruby is the
|
|
best choice of all (since scripting languages have only one
|
|
cross-platform implementation).</P
|
|
><P
|
|
>Scripting languages that qualify include Python, Perl, Tcl, Emacs
|
|
Lisp, and PHP. Historic Bourne shell (/bin/sh) does
|
|
<EM
|
|
>not</EM
|
|
> qualify; there are too many different
|
|
implementations with subtle idiosyncrasies, and the shell environment
|
|
is subject to disruption by user customizations such as shell
|
|
aliases.</P
|
|
><P
|
|
>If you choose a compiled language such as C/C++, do not use
|
|
compiler extensions (such as allocating variable-length arrays on the
|
|
stack, or indirecting through void pointers). Regularly build using as
|
|
many different compilers and test machines as you can.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="proprietary"
|
|
></A
|
|
>6.2. Don't rely on proprietary code</H2
|
|
><P
|
|
>Don't rely on proprietary languages, libraries, or other code.
|
|
In the open-source community this is considered rude. Open-source
|
|
developers don't trust code for which they can't review the source.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="build_systems"
|
|
></A
|
|
>6.3. Build systems</H2
|
|
><P
|
|
>A significant advantage of open source distributions is they allow
|
|
each source package to adapt at compile-time to the environment it finds.
|
|
One of the choices you need to make is of a "build system", the toolkit you
|
|
(and other people) will rely on to transform your source into
|
|
executables.</P
|
|
><P
|
|
>One thing your build script cannot do is ask the user for system
|
|
information at compile-time. The user installing the package will not
|
|
necessarily know the answers to your questions, so this approach is doomed
|
|
from the start. Your software, calling the build system tools, must be able
|
|
to determine for itself any information that it may need at compile- or
|
|
install-time.</P
|
|
><P
|
|
>Community notions of best practice in build systems are now (rearly
|
|
2010) in a starte of some flux.</P
|
|
><DIV
|
|
CLASS="sect3"
|
|
><HR><H3
|
|
CLASS="sect3"
|
|
><A
|
|
NAME="autoconf"
|
|
></A
|
|
>6.3.1. GNU autotools: fading but still standard</H3
|
|
><P
|
|
>Previous versions of this HOWTO urged using GNU autotools to handle
|
|
portability issues, do system-configuration probes, and tailor your
|
|
makefiles. This is still the standard and most popular approach, but it is
|
|
becoming increasingly problematic because GNU autotools is showing its age.
|
|
Autotools was always a pile of crocks upon hacks upon kluges, implemented
|
|
in a messy mixture of languages and with some serious design flaws. The
|
|
resulting mess was tolerable for many years, but as projects become
|
|
more complex it is increasingly failing.</P
|
|
><P
|
|
>Still, people building from C sources expect to be able to type
|
|
"configure; make; make install" and get a clean build. Supposing you choose
|
|
a non-autotools system, you will probably want to emulate this behavior
|
|
(which should be easy).</P
|
|
><P
|
|
>There is a good tutorial on autotools <A
|
|
HREF="http://seul.org/docs/autotut/"
|
|
TARGET="_top"
|
|
>here</A
|
|
>.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect3"
|
|
><HR><H3
|
|
CLASS="sect3"
|
|
><A
|
|
NAME="scons"
|
|
></A
|
|
>6.3.2. SCons: leading a crowded field</H3
|
|
><P
|
|
>The race to replace autotools does not yet have a winner, but it has
|
|
a front runner: <A
|
|
HREF="http://www.scons.org/"
|
|
TARGET="_top"
|
|
>SCons</A
|
|
>. SCons
|
|
abolishes makefiles; it combines the "configure" and "make" parts of the
|
|
autotools build sequence into one step. It offers cross-platfoem builds
|
|
with a single recipe on Unix/Linux, Maoc OS X, and Windows. It is
|
|
written in Python, is extensible in Python, and is to some extent riding
|
|
the increasing popularity of that language.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect3"
|
|
><HR><H3
|
|
CLASS="sect3"
|
|
><A
|
|
NAME="cmake_and_others"
|
|
></A
|
|
>6.3.3. CMake and others</H3
|
|
><P
|
|
>SCons is still a minority choice, and has stiff competition from
|
|
several others, of which CMake and WAF are probably the most
|
|
prominant. Fairly even-handed cross-comparisons, considering the source,
|
|
can be <A
|
|
HREF="http://www.scons.org/wiki/SconsVsOtherBuildTools"
|
|
TARGET="_top"
|
|
>found
|
|
on the SCons wiki</A
|
|
>.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="testcode"
|
|
></A
|
|
>6.4. Test your code before release</H2
|
|
><P
|
|
>A good test suite allows the team to buy inexpensive hardware for
|
|
testing and then easily run regression tests before releases. Create a
|
|
strong, usable test framework so that you can incrementally add tests
|
|
to your software without having to train developers up in the
|
|
intricacies of the test suite.</P
|
|
><P
|
|
>Distributing the test suite allows the community of users to test
|
|
their ports before contributing them back to the group.</P
|
|
><P
|
|
>Encourage your developers to use a wide variety of platforms as
|
|
their desktop and test machines so that code is continuously being
|
|
tested for portability flaws as part of normal development.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="sanitycode"
|
|
></A
|
|
>6.5. Sanity-check your code before release</H2
|
|
><P
|
|
>If you're writing C/C++ using GCC, test-compile with -Wall and
|
|
clean up all warning messages before each release. Compile your code
|
|
with every compiler you can find — different compilers often find
|
|
different problems. Specifically, compile your software on true 64-bit
|
|
machine. Underlying data types can change on 64-bit machines, and you
|
|
will often find new problems there. Find a UNIX vendor's system and run
|
|
the lint utility over your software.</P
|
|
><P
|
|
>Run tools that for memory leaks and other run-time errors;
|
|
Electric Fence
|
|
and
|
|
<A
|
|
HREF="http://developer.kde.org/~sewardj"
|
|
TARGET="_top"
|
|
>Valgrind</A
|
|
>
|
|
are two good ones available in open source.</P
|
|
><P
|
|
>For Python projects, the
|
|
<A
|
|
HREF="http://sourceforge.net/projects/pychecker"
|
|
TARGET="_top"
|
|
>PyChecker</A
|
|
>
|
|
program can be a useful check. It's not out of beta yet, but nevertheless
|
|
often catches nontrivial errors.</P
|
|
><P
|
|
>If you're writing Perl, check your code with perl -c (and maybe
|
|
-T, if applicable). Use perl -w and 'use strict' religiously. (See the
|
|
Perl documentation for further discussion.)</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="sanitydocs"
|
|
></A
|
|
>6.6. Sanity-check your documentation and READMEs before release</H2
|
|
><P
|
|
>Spell-check your documentation, README files and error messages
|
|
in your software. Sloppy code, code that produces warning messages when
|
|
compiled, and spelling errors in README files or error messages, leads
|
|
users to believe the engineering behind it is also haphazard and
|
|
sloppy.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="cport"
|
|
></A
|
|
>6.7. Recommended C/C++ portability practices</H2
|
|
><P
|
|
>If you are writing C, feel free to use the full ANSI features.
|
|
Specifically, do use function prototypes, which will help you spot
|
|
cross-module inconsistencies. The old-style K&R compilers are
|
|
history.</P
|
|
><P
|
|
>Do not assume compiler-specific features such as the GCC "-pipe"
|
|
option or nested functions are available. These will come around and
|
|
bite you the second somebody ports to a non-Linux, non-GCC system.</P
|
|
><P
|
|
>Code required for portability should be isolated to a single area
|
|
and a single set of source files (for example, an "os" subdirectory).
|
|
Compiler, library and operating system interfaces with portability
|
|
issues should be abstracted to files in this directory. This includes
|
|
variables such as "errno", library interfaces such as "malloc", and
|
|
operating system interfaces such as "mmap".</P
|
|
><P
|
|
>Portability layers make it easier to do new software ports. It is
|
|
often the case that no member of the development team knows the porting
|
|
platform (for example, there are literally hundreds of different
|
|
embedded operating systems, and nobody knows any significant fraction
|
|
of them). By creating a separate portability layer it is possible for
|
|
someone who knows the port platform to port your software without having
|
|
to understand it.</P
|
|
><P
|
|
>Portability layers simplify applications. Software rarely needs
|
|
the full functionality of more complex system calls such as mmap or
|
|
stat, and programmers commonly configure such complex interfaces
|
|
incorrectly. A portability layer with abstracted interfaces
|
|
("__file_exists" instead of a call to stat) allows you to export only
|
|
the limited, necessary functionality from the system, simplifying the
|
|
code in your application.</P
|
|
><P
|
|
>Always write your portability layer to select based on a feature,
|
|
never based on a platform. Trying to create a separate portability layer
|
|
for each supported platform results in a multiple update problem
|
|
maintenance nightmare. A "platform" is always selected on at least two
|
|
axes: the compiler and the library/operating system release. In some
|
|
cases there are three axes, as when Linux vendors select a C library
|
|
independently of the operating system release. With M vendors, N
|
|
compilers and O operating system releases, the number of "platforms"
|
|
quickly scales out of reach of any but the largest development teams.
|
|
By using language and systems standards such as ANSI and POSIX 1003.1,
|
|
the set of features is relatively constrained.</P
|
|
><P
|
|
>Portability choices can be made along either lines of code or
|
|
compiled files. It doesn't make a difference if you select alternate
|
|
lines of code on a platform, or one of a few different files. A rule of
|
|
thumb is to move portability code for different platforms into separate
|
|
files when the implementations diverged significantly (shared memory
|
|
mapping on UNIX vs. Windows), and leave portability code in a single
|
|
file when the differences are minimal (using gettimeofday,
|
|
clock_gettime, ftime or time to find out the current
|
|
time-of-day).</P
|
|
><P
|
|
>Avoid using complex types such as "off_t" and "size_t". They vary
|
|
in size from system to system, especially on 64-bit systems. Limit your
|
|
usage of "off_t" to the portability layer, and your usage of "size_t"
|
|
to mean only the length of a string in memory, and nothing else.</P
|
|
><P
|
|
>Never step on the namespace of any other part of the system,
|
|
(including file names, error return values and function names). Where
|
|
the namespace is shared, document the portion of the namespace that you
|
|
use.</P
|
|
><P
|
|
>Choose a coding standard. The debate over the choice of standard
|
|
can go on forever — regardless, it is too difficult and expensive to
|
|
maintain software built using multiple coding standards, and so some
|
|
coding standard must be chosen. Enforce your coding standard ruthlessly,
|
|
as consistency and cleanliness of the code are of the highest priority;
|
|
the details of the coding standard itself are a distant second.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect1"
|
|
><HR><H1
|
|
CLASS="sect1"
|
|
><A
|
|
NAME="distpractice"
|
|
></A
|
|
>7. Good distribution-making practice</H1
|
|
><P
|
|
>These guidelines describe how your distribution should look when
|
|
someone downloads, retrieves and unpacks it.</P
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="tarballs"
|
|
></A
|
|
>7.1. Make sure tarballs always unpack into a single new directory</H2
|
|
><P
|
|
>The single most annoying mistake newbie developers make is to build
|
|
tarballs that unpack the files and directories in the distribution into
|
|
the current directory, potentially stepping on files already located there.
|
|
<EM
|
|
>Never do this!</EM
|
|
></P
|
|
><P
|
|
>Instead, make sure your archive files all have a common directory part
|
|
named after the project, so they will unpack into a single top-level
|
|
directory directly <EM
|
|
>beneath</EM
|
|
> the current one.</P
|
|
><P
|
|
>Here's a makefile trick that, assuming your distribution directory is
|
|
named `foobar' and SRC contains a list of your distribution files,
|
|
accomplishes this. SRC may also contain names of subdirectories to
|
|
be included whole.</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
> foobar-$(VERS).tar.gz:
|
|
@find $(SRC) -type f | sed s:^:foobar-$(VERS)/: >MANIFEST
|
|
@(cd ..; ln -s foobar foobar-$(VERS))
|
|
(cd ..; tar -czvf foobar/foobar-$(VERS).tar.gz `cat foobar/MANIFEST`)
|
|
@(cd ..; rm foobar-$(VERS))
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="readme"
|
|
></A
|
|
>7.2. Have a README</H2
|
|
><P
|
|
>Have a file called <TT
|
|
CLASS="filename"
|
|
>README</TT
|
|
> or
|
|
<TT
|
|
CLASS="filename"
|
|
>READ.ME</TT
|
|
> that is a roadmap of your source
|
|
distribution. By ancient convention, this is the first file intrepid
|
|
explorers will read after unpacking the source.</P
|
|
><P
|
|
>Good things to have in the README include:</P
|
|
><P
|
|
></P
|
|
><OL
|
|
TYPE="1"
|
|
><LI
|
|
><P
|
|
>A brief description of the project.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>A pointer to the project website (if it has
|
|
one)</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Notes on the developer's build environment and
|
|
potential portability problems.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>A roadmap describing important files and subdirectories.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Either build/installation instructions or a pointer to a file
|
|
containing same (usually <TT
|
|
CLASS="filename"
|
|
>INSTALL</TT
|
|
>).</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Either a maintainers/credits list or a pointer to a
|
|
file containing same (usually
|
|
<TT
|
|
CLASS="filename"
|
|
>CREDITS</TT
|
|
>).</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Either recent project news or a pointer to a file
|
|
containing same (usually <TT
|
|
CLASS="filename"
|
|
>NEWS</TT
|
|
>).</P
|
|
></LI
|
|
></OL
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="filenames"
|
|
></A
|
|
>7.3. Respect and follow standard file naming practices</H2
|
|
><P
|
|
>Before even looking at the README, your intrepid explorer will
|
|
have scanned the filenames in the top-level directory of your unpacked
|
|
distribution. Those names can themselves convey information. By
|
|
adhering to certain standard naming practices, you can give the
|
|
explorer valuable clues about what to look in next.</P
|
|
><P
|
|
>Here are some standard top-level file names and what they mean. Not
|
|
every distribution needs all of these.</P
|
|
><P
|
|
></P
|
|
><DIV
|
|
CLASS="variablelist"
|
|
><DL
|
|
><DT
|
|
>README or READ.ME</DT
|
|
><DD
|
|
><P
|
|
>the roadmap file, to be read first</P
|
|
></DD
|
|
><DT
|
|
>INSTALL</DT
|
|
><DD
|
|
><P
|
|
> configuration, build, and installation instructions</P
|
|
></DD
|
|
><DT
|
|
>AUTHORS</DT
|
|
><DD
|
|
><P
|
|
> list of project contributers.</P
|
|
><P
|
|
>An older, still-acceptable convention for this is to name it CREDITS</P
|
|
></DD
|
|
><DT
|
|
>NEWS</DT
|
|
><DD
|
|
><P
|
|
> recent project news</P
|
|
></DD
|
|
><DT
|
|
>HISTORY</DT
|
|
><DD
|
|
><P
|
|
> project history</P
|
|
></DD
|
|
><DT
|
|
>COPYING</DT
|
|
><DD
|
|
><P
|
|
> project license terms (GNU convention)</P
|
|
></DD
|
|
><DT
|
|
>LICENSE</DT
|
|
><DD
|
|
><P
|
|
> project license terms</P
|
|
></DD
|
|
><DT
|
|
>MANIFEST</DT
|
|
><DD
|
|
><P
|
|
> list of files in the distribution</P
|
|
></DD
|
|
><DT
|
|
>FAQ</DT
|
|
><DD
|
|
><P
|
|
> plain-text Frequently-Asked-Questions document for
|
|
the project</P
|
|
></DD
|
|
><DT
|
|
>TAGS</DT
|
|
><DD
|
|
><P
|
|
> generated tag file for use by Emacs or vi</P
|
|
></DD
|
|
></DL
|
|
></DIV
|
|
><P
|
|
>Note the overall convention that filenames with all-caps names are
|
|
human-readable metainformation about the package, rather than build
|
|
components (TAGS is an exception to the first, but not to the second).</P
|
|
><P
|
|
>Having a FAQ can save you a lot of grief. When a question about the
|
|
project comes up often, put it in the FAQ; then direct users to read the
|
|
FAQ before sending questions or bug reports. A well-nurtured FAQ can
|
|
decrease the support burden on the project maintainers by an order of
|
|
magnitude or more.</P
|
|
><P
|
|
>Having a HISTORY or NEWS file with timestamps in it for each release
|
|
is valuable. Among other things, it may help establish prior art if
|
|
you are ever hit with a patent-infringement lawsuit (this hasn't
|
|
happened to anyone yet, but best to be prepared).</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="upgradeability"
|
|
></A
|
|
>7.4. Design for Upgradability</H2
|
|
><P
|
|
>Your software will change over time as you put out new releases. Some
|
|
of these changes will not be backward-compatible. Accordingly, you
|
|
should give serious thought to designing your installation layouts so
|
|
that multiple installed versions of your code can coexist on the same
|
|
system. This is especially important for libraries — you can't
|
|
count on all your client programs to upgrade in lockstep with your
|
|
API changes.</P
|
|
><P
|
|
>The Emacs, Python, and Qt projects have a good convention for handling
|
|
this; version-numbered directories. Here's how an installed Qt
|
|
library hierarchy looks (${ver} is the version number):</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="screen"
|
|
> /usr/lib/qt
|
|
/usr/lib/qt-${ver}
|
|
/usr/lib/qt-${ver}/bin # Where you find moc
|
|
/usr/lib/qt-${ver}/lib # Where you find .so
|
|
/usr/lib/qt-${ver}/include # Where you find header files
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
>With this organization, you can have multiple versions
|
|
coexisting. Client programs have to specify the library version they
|
|
want, but that's a small price to pay for not having the interfaces
|
|
break on them.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="checksums"
|
|
></A
|
|
>7.5. Provide checksums</H2
|
|
><P
|
|
>Provide checksums with your binaries (tarballs, RPMs, etc.). This
|
|
will allow people to verify that they haven't been corrupted or had
|
|
Trojan-horse code inserted in them.</P
|
|
><P
|
|
>While there are several commands you can use for this purpose (such
|
|
as <B
|
|
CLASS="command"
|
|
>sum</B
|
|
> and <B
|
|
CLASS="command"
|
|
>cksum</B
|
|
>) it is best to use a
|
|
cryptographically-secure hash function. The GPG package provides this
|
|
capability via the <TT
|
|
CLASS="option"
|
|
>—detach-sign</TT
|
|
> option; so does the GNU
|
|
command <B
|
|
CLASS="command"
|
|
>md5sum</B
|
|
>.</P
|
|
><P
|
|
>For each binary you ship, your project web page should list
|
|
the checksum and the command you used to generate it.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect1"
|
|
><HR><H1
|
|
CLASS="sect1"
|
|
><A
|
|
NAME="documentation"
|
|
></A
|
|
>8. Good documentation practice</H1
|
|
><P
|
|
>The most important good documentation practice is to actually
|
|
write some! Too many programmers omit this. But here are two good
|
|
reasons to do it:</P
|
|
><P
|
|
></P
|
|
><OL
|
|
TYPE="1"
|
|
><LI
|
|
><P
|
|
> <EM
|
|
>Your documentation can be your design document.</EM
|
|
>
|
|
The best time to write it is before you type a single line of code,
|
|
while you're thinking out what you want to do. You'll find that the
|
|
process of describing the way you want your program to work in natural
|
|
language focuses your mind on the high-level questions about what it should
|
|
do and how it should work. This may save you a lot of effort later.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> <EM
|
|
>Your documentation is an advertisement for the
|
|
quality of your code.</EM
|
|
>
|
|
Many people take poor, scanty, or illiterate documentation for a program as
|
|
a sign that the programmer is sloppy or careless of potential users' needs.
|
|
Good documentation, on the other hand, conveys a message of intelligence
|
|
and professionalism. If your program has to compete with other programs,
|
|
better make sure your documentation is at least as good as theirs lest
|
|
potential users write you off without a second look.
|
|
</P
|
|
></LI
|
|
></OL
|
|
><P
|
|
>This HOWTO wouldn't be the place for a course on technical writing
|
|
even if that were practical. So we'll focus here on the formats and tools
|
|
available for composing and rendering documentation.</P
|
|
><P
|
|
>Though Unix and the open-source community have a long tradition of
|
|
hosting powerful document-formatting tools, the plethora of different
|
|
formats has meant that documentation has tended to be fragmented and
|
|
difficult for users to browse or index in a coherent way.
|
|
We'll summarize the uses, strengths, and weaknesses of the common
|
|
documentation formats. Then we'll make some recommendations for good
|
|
practice.</P
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="docpractice"
|
|
></A
|
|
>8.1. Documentation formats</H2
|
|
><P
|
|
>Here are the documentation markup formats now in widespread use among
|
|
open-source developers. When we speak of "presentation" markup, we mean
|
|
markup that controls the document's appearance explicitly (such as a font
|
|
change). When we speak of "structural" markup, we mean markup that
|
|
describes the logical structure of the document (like a section break or
|
|
emphasis tag.) And when we speak of "indexing", we mean the process
|
|
of extracting from a collection of documents a searchable collection
|
|
of topic pointers that users can employ to reliably find material
|
|
of interest across the entire collection.</P
|
|
><P
|
|
></P
|
|
><DIV
|
|
CLASS="variablelist"
|
|
><DL
|
|
><DT
|
|
>man pages</DT
|
|
><DD
|
|
><P
|
|
>The most most common format, inherited from Unix, a primitive form of
|
|
presentation markup.
|
|
<SPAN
|
|
CLASS="citerefentry"
|
|
><SPAN
|
|
CLASS="refentrytitle"
|
|
>man</SPAN
|
|
>(1)</SPAN
|
|
>
|
|
command provides a pager and a stone-age search facility. No support for
|
|
images or hyperlinks or indexing. Renders to Postscript for printing fairly
|
|
well. Doesn't render to HTML at all well (essentially as flat text).
|
|
Tools are preinstalled on all Linux systems.</P
|
|
><P
|
|
>Man page format is not bad for command summaries or short reference
|
|
documents intended to jog the memory of an experienced user. It starts to
|
|
creak under the strain for programs with complex interfaces and many
|
|
options, and collapses entirely if you need to maintain a set of documents
|
|
with rich cross-references (the markup has only weak and normally unused
|
|
support for hyperlinks).</P
|
|
></DD
|
|
><DT
|
|
>HTML</DT
|
|
><DD
|
|
><P
|
|
>Increasingly common since the Web exploded in 1993-1994. Markup is
|
|
partly structural, mostly presentation. Browseable through any web browser.
|
|
Good support for images and hyperlinks. Limited built-in facilities for
|
|
indexing, but good indexing and search-engine technologies exist and are
|
|
widely deployed. Renders to Postscript for printing pretty well. HTML
|
|
tools are now universally available.</P
|
|
><P
|
|
>HTML is very flexible and suitable for many kinds of documentation.
|
|
Actually, it's <EM
|
|
>too</EM
|
|
> flexible; it shares with man page
|
|
format the problem that it's hard to index automatically because a lot of the
|
|
markup describes presentation rather than document structure.</P
|
|
></DD
|
|
><DT
|
|
>Texinfo</DT
|
|
><DD
|
|
><P
|
|
>Texinfo is the documentation format used by the Free Software
|
|
Foundation. It's a set of macros on top of the powerful TeX formatting
|
|
engine. Mostly structural, partly presentation. Browseable through Emacs
|
|
or a standalone <B
|
|
CLASS="command"
|
|
>info</B
|
|
> program. Good support for
|
|
hyperlinks, none for images. Good indexing for both print and on-line
|
|
forms; when you install a Texinfo document, a pointer to it is
|
|
automatically added to a browsable "dir" document listing all the Texinfo
|
|
documents on your system. Renders to excellent Postscript and useable
|
|
HTML. Texinfo tools are preinstalled on most Linux systems, and available
|
|
at the <A
|
|
HREF="http://www.gnu.org"
|
|
TARGET="_top"
|
|
>Free Software Foundation</A
|
|
>
|
|
website.</P
|
|
><P
|
|
>Texinfo is a good design, quite usable for typesetting books as well
|
|
as small on-line documents, but like HTML it's a sort of amphibian — the
|
|
markup is part structural, part presentation, and the presentation part
|
|
creates problems for rendering. </P
|
|
></DD
|
|
><DT
|
|
>DocBook</DT
|
|
><DD
|
|
><P
|
|
>DocBook is a large, elaborate markup format based on SGML (more
|
|
recent versions on XML). Unlike the other formats described here it is
|
|
entirely structural with no presentation markup. Excellent support for
|
|
images and hyperlinks. Good support for indexing. Renders well to HTML,
|
|
acceptably to Postscript for printing (quality is improving as the tools
|
|
evolve). Tools and documentation are available at the <A
|
|
HREF="http://www.docbook.org/"
|
|
TARGET="_top"
|
|
>DocBook website</A
|
|
>.</P
|
|
><P
|
|
>DocBook is excellent for large, complex documents; it was designed
|
|
specifically to support technical manuals and rendering them in multiple
|
|
output formats. Its main drawback is its verbosity. Fortunately, good
|
|
tools and introductory-level documentation are now available; see the
|
|
<A
|
|
HREF="http://tldp.org/HOWTO/DocBook-Demystification-HOWTO/"
|
|
TARGET="_top"
|
|
>DocBook Demystification
|
|
HOWTO</A
|
|
> for an introduction.</P
|
|
></DD
|
|
><DT
|
|
>asciidoc</DT
|
|
><DD
|
|
><P
|
|
>The one serious drawback of DocBook is that its markup is rather
|
|
heavyweight and obtrusive. A clever recent workaround is <A
|
|
HREF="http://www.methods.co.nz/asciidoc/"
|
|
TARGET="_top"
|
|
>AsciiDOC</A
|
|
>. This tool is a
|
|
front end to DocBook with a much simpler and more natural input
|
|
syntax. Users don't need to be aware of DocBook at all, but still get
|
|
nearly the full power of those tools.</P
|
|
><P
|
|
>AsciiDOC (often referred to by the all-lower-case name of the
|
|
formatter it ships) has been seeing very rapid uptake recently by
|
|
projects which had previously moved to DocBook.</P
|
|
></DD
|
|
></DL
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="AEN547"
|
|
></A
|
|
>8.2. Good practice recommendations</H2
|
|
><P
|
|
>Documentation practice has been changing since 2000, when some key
|
|
open-source project groups (including the Linux kernel project, GNOME, KDE,
|
|
the Free Software Foundation, and the Linux Documentation Project) agreed
|
|
on an approach more web-friendly than traditional Unix's print-oriented
|
|
tools. Today's best practice, since the XML-DocBook toolchain reached
|
|
production status in mid-2001, is this:</P
|
|
><P
|
|
></P
|
|
><OL
|
|
TYPE="1"
|
|
><LI
|
|
><P
|
|
>Maintain your document masters in either XML-DocBook or asciidoc.
|
|
Even your man pages can be DocBook <TT
|
|
CLASS="sgmltag"
|
|
>RefEntry</TT
|
|
> documents.
|
|
There is a very good <A
|
|
HREF="http://tldp.org/HOWTO/mini/Man-Page.html"
|
|
TARGET="_top"
|
|
>HOWTO</A
|
|
>
|
|
on writing manual pages that explains the sections and organization your
|
|
users will expect to see.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Ship the XML or asciidoc masters. Also, in case your users' systems don't have
|
|
<SPAN
|
|
CLASS="citerefentry"
|
|
><SPAN
|
|
CLASS="refentrytitle"
|
|
>xmlto</SPAN
|
|
>(1)</SPAN
|
|
>
|
|
(standard on all Red Hat distributions since 7.3), ship the troff sources
|
|
that you get by running conversions on your masters. Your
|
|
software distribution's installation procedure should install those in
|
|
the normal way, but direct people to the XML/asciidoc files if they want to write
|
|
documentation patches.</P
|
|
><P
|
|
>It's easy to tell <SPAN
|
|
CLASS="citerefentry"
|
|
><SPAN
|
|
CLASS="refentrytitle"
|
|
>make</SPAN
|
|
>(1)</SPAN
|
|
> to keep the generated man files up
|
|
to date. Just do something like this in your makefile:</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
> foo.1: foo.xml
|
|
xmlto man foo.xml
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
>If you're using asciidoc, something like this should serve:</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
> foo.1: foo.txt
|
|
asciidoc --backend=docbook foo.txt
|
|
xmlto man foo.xml
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Generate XHTML from your masters (with <B
|
|
CLASS="command"
|
|
>xmlto
|
|
xhtml</B
|
|
>, or directly using <B
|
|
CLASS="command"
|
|
>asciidoc</B
|
|
>) and make it
|
|
available from your project's web page, where people can browse it in order
|
|
to decide whether to download your code and join your project.</P
|
|
></LI
|
|
></OL
|
|
><P
|
|
>For converting legacy documentation in troff formats to DocBook,
|
|
check out <A
|
|
HREF="http://www.catb.org/~esr//doclifter/"
|
|
TARGET="_top"
|
|
>doclifter</A
|
|
>. If you're
|
|
unwilling to move from using man sources as a master format, at least try
|
|
to clean them up so <SPAN
|
|
CLASS="application"
|
|
>doclifter</SPAN
|
|
> can lift them
|
|
to XML automatically.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect1"
|
|
><HR><H1
|
|
CLASS="sect1"
|
|
><A
|
|
NAME="communication"
|
|
></A
|
|
>9. Good communication practice</H1
|
|
><P
|
|
>Your software and documentation won't do the world much good if
|
|
nobody but you knows it exists. Also, developing a visible presence for
|
|
the project on the Internet will assist you in recruiting users and
|
|
co-developers. Here are the standard ways to do that.</P
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="announce"
|
|
></A
|
|
>9.1. Announce to Freecode</H2
|
|
><P
|
|
>See <A
|
|
HREF="http://www.freecode.com"
|
|
TARGET="_top"
|
|
>Freecode</A
|
|
>. Distribution watch this
|
|
channel to see when new releases are issuing.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="website"
|
|
></A
|
|
>9.2. Have a website</H2
|
|
><P
|
|
>If you intend try to build any substantial user or developer community
|
|
around your project, it should have a website. Standard things to have
|
|
on the website include:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
>The project charter (why it exists, who the audience is, etc).</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Download links for the project sources.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Instructions on how to join the project mailing list(s).</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>A FAQ (Frequently Asked Questions) list.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>HTMLized versions of the project documentation</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Links to related and/or competing projects.</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>Some project sites even have URLs for anonymous access to the master
|
|
source tree.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="lists"
|
|
></A
|
|
>9.3. Host project mailing lists</H2
|
|
><P
|
|
>It's standard practice to have a private development list
|
|
through which project collaborators can communicate and exchange
|
|
patches. You may also want to have an announcements list for people
|
|
who want to be kept informed of the project's process.</P
|
|
><P
|
|
>If you are running a project named `foo'.
|
|
your developer list might be foo-dev or foo-friends; your announcement
|
|
list might be foo-announce.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><HR><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="archives"
|
|
></A
|
|
>9.4. Release to major archives</H2
|
|
><P
|
|
>Since it was launched in fall 1999,
|
|
<A
|
|
HREF="http://www.sourceforge.net"
|
|
TARGET="_top"
|
|
>SourceForge</A
|
|
> has exploded
|
|
in popularity. It is not just an archive and distribution site, though
|
|
you can use it that way. It is an entire free project-hosting service that
|
|
tries to offer a complete set of tools for open-source development groups —
|
|
web and archive space, mailing lists, bug-tracking, chat forums, CVS
|
|
repositories, and other services.</P
|
|
><P
|
|
>Other important locations include:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
>the <A
|
|
HREF="http://www.python.org"
|
|
TARGET="_top"
|
|
>Python Software Activity</A
|
|
>
|
|
site (for software written in Python).</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>the <A
|
|
HREF="http://language.perl.com/CPAN"
|
|
TARGET="_top"
|
|
>CPAN</A
|
|
>, the
|
|
Comprehensive Perl Archive Network, (for software written in Perl).</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
><A
|
|
HREF="https://github.com/"
|
|
TARGET="_top"
|
|
>github</A
|
|
>, and
|
|
<A
|
|
HREF="https://gitorious.org/"
|
|
TARGET="_top"
|
|
>gitorious</A
|
|
>, two very popular
|
|
sites hiosting free git repository access.</P
|
|
></LI
|
|
></UL
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect1"
|
|
><HR><H1
|
|
CLASS="sect1"
|
|
><A
|
|
NAME="management"
|
|
></A
|
|
>10. Good project-management practice</H1
|
|
><P
|
|
>Managing a project well when all the participants are volunteers presents
|
|
some unique challenges. This is too large a topic to cover in a HOWTO.
|
|
Fortunately, there are some useful white papers available that will help you
|
|
understand the major issues.</P
|
|
><P
|
|
>For discussion of basic development organization and the
|
|
release-early-release-often `bazaar mode', see <A
|
|
HREF="http://www.catb.org/~esr//writings/cathedral-bazaar/"
|
|
TARGET="_top"
|
|
>The Cathedral and the
|
|
Bazaar</A
|
|
>.</P
|
|
><P
|
|
>For discussion of motivational psychology, community customs,
|
|
and conflict resolution, see <A
|
|
HREF="http://www.catb.org/~esr//writings/homesteading/"
|
|
TARGET="_top"
|
|
>Homesteading
|
|
the Noosphere</A
|
|
>.</P
|
|
><P
|
|
>For discussion of economics and appropriate business models, see
|
|
<A
|
|
HREF="http://www.catb.org/~esr//writings/magic-cauldron/"
|
|
TARGET="_top"
|
|
>The Magic
|
|
Cauldron</A
|
|
>.</P
|
|
><P
|
|
>These papers are not the last word on open-source development. But they
|
|
were the first serious analyses to be written, and have yet to be
|
|
superseded (though the author hopes they will be someday).</P
|
|
></DIV
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |