LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity

updated

This commit is contained in:
gferg 2001-08-20 13:40:54 +00:00
parent 55a431b7e6
commit 36df1ec022
2 changed files with 247 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
LDP/howto/docbook/Module-HOWTO.sgml
View File

@ -20,6 +20,16 @@
<pubdate>18 August 2001</pubdate>
<revhistory>
<revision>
<revnumber>v1.01</revnumber>
<date>2001-08-18</date>
<authorinitials>bjh</authorinitials>
<revremark>
Add material on various features created in the last few
years: kernel module loader, ksymoops symbols,
kernel-version-dependent LKM file location.
</revremark>
</revision>
<revision>
<revnumber>v1.00</revnumber>
<date>2001-06-14</date>
@ -28,16 +38,6 @@
Initial release.
</revremark>
</revision>
<revision>
<revnumber>v1.01</revnumber>
<date>2001-08-18</date>
<authorinitials>bjh</authorinitials>
<revremark>
Add material on various features created in the last few
years: kernel module loader, ksymoops symbols,
kernel-version-dependent LKM file location.
</revremark>
</revision>
</revhistory>
<abstract>

250
LDP/howto/docbook/Software-Release-Practice-HOWTO.sgml
View File

@ -2,7 +2,7 @@
<!-- Reference RFC 2026-2028? -->
<article>
<article id='index'>
<articleinfo>
<title>Software Release Practice HOWTO</title>
@ -24,6 +24,14 @@
</copyright>
<revhistory>
<revision>
<revnumber>3.3</revnumber>
<date>2001-08-16</date>
<authorinitials>esr</authorinitials>
<revremark>
New section about how to send good patches.
</revremark>
</revision>
<revision>
<revnumber>3.2</revnumber>
<date>2001-07-11</date>
@ -52,7 +60,7 @@
</revhistory>
<abstract>
<para>This HOWTO describes good release practices for Linux
<para>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
@ -76,9 +84,10 @@ world and predate Linux; others have developed recently in response to
particular new tools and technologies such as the World Wide
Web.</para>
<para>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 software distribution.</para>
<para>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.</para>
</sect2>
<sect2 id="newversions"><title>New versions of this document</title>
@ -94,6 +103,217 @@ http://www.linuxdoc.org/LDP/HOWTO/Software-Release-Practice.html</ulink>.
<para>Feel free to mail any questions or comments about this HOWTO to
Eric S. Raymond, <email>esr@snark.thyrsus.com</email>.</para>
</sect2>
</sect1>
<sect1 id="patching"><title>Good patching practice</title>
<para>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?</para>
<para>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 &mdash; indications that the person has been in their shoes and
understands what it's like to have to evaluate and merge an incoming patch.
</para>
<para>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 are very likely to actually
<emphasis>be</emphasis> bogus.</para>
<para>Here are some tips on how to get your patch accepted:</para>
<sect2><title>Do send patches, don't send whole archives or files</title>
<para>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
<citerefentry>
<refentrytitle>diff</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
command run to compare the baseline distributed version against your
modified version.</para>
<para>The diff command and its dual,
<citerefentry>
<refentrytitle>patch</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
(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.</para>
</sect2>
<sect2><title>Don't include patches for generated files.</title>
<para>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 <productname>Bison</productname>
or <productname>Flex</productname>.</para>
<para>These days the most common mistake of this kind is sending a diff
with a huge band that is nothing but changebars between your
<command>configure</command> script and his. This file is generated by
<command>autoconf</command>.</para>
<para>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 &mdash; but it will count against you.</para>
</sect2>
<sect2><title>Don't send patch bands that just tweak RCS or SCCS $-symbols.</title>
<para>Some people put special tokens in their source files that are
expanded by the version-control system when the file is checked in:
the <markup>$Id$</markup> construct used by RCS and CVS, for example.</para>
<para>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 <emphasis>his</emphasis> version-control status. But
those extra patch bands are noise. They're distracting. It's more
considerate not to send them.</para>
<para>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.</para>
</sect2>
<sect2><title>Do use -c or -u format, don't use the default (-e) format</title>
<para>The default (-e) format of
<citerefentry>
<refentrytitle>diff</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
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.</para>
<para>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.</para>
</sect2>
<sect2><title>Do include documentation with your patch</title>
<para>This is very important. If your patch makes a user-visible addition
or change to the software's features, <emphasis>include changes to the
appropriate man pages and other documentation files in your patch</emphasis>.
Do <emphasis>not</emphasis> assume that the recipient will be happy to
document your code for you, or else to have undocumented features lurking
in the code.</para>
<para>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.</para>
<para>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.</para>
</sect2>
<sect2><title>Do include an explanation with your patch</title>
<para>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.</para>
<para>The note can be short &mdash; 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.</para>
<para>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 tat 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:</para>
<para><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.
</quote></para>
<para><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?
</quote></para>
<para><quote>
Have you considered using the Foonly algorithm for this problem? There
is a good implementation at &lt;http://www.somesite.com/~jsmith/foonly.html&gt;.
</quote></para>
<para><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.
</quote></para>
<para><quote>
This may be featurititis, but I'm sending it anyway. Maybe you'll know a
cleaner way to implement the feature.
</quote></para>
</sect2>
<sect2><title>Do include useful comments in your code</title>
<para>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.</para>
<para>Good comments in your code help me understand it. Bad comments
don't.</para>
<para>Here's an example of a bad comment:</para>
<programlisting>
/* norman newbie fixed this 13 Aug 2001 */
</programlisting>
<para>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
<filename>NEWS</filename> or <filename>HISTORY</filename> file. I'll
probably take that.</para>
<para>Here's an example of a good comment:</para>
<programlisting>
/*
* This conditional needs to be guarded so that crunch_data()
* never gets passed a NULL pointer. (norman_newbie@foosite.com)
*/
</programlisting>
<para>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 <emphasis>gives</emphasis> me confidence in your
changes.</para>
</sect2>
</sect1>
<sect1 id="naming"><title>Good project- and archive- naming practice</title>
@ -215,7 +435,7 @@ 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 un this document in late 1999.)</para>
using the conventions described in this document in late 1999.)</para>
<para>Look for and respect the conventions of specialized
communities and developers; for general use, follow the above
@ -706,18 +926,22 @@ of interest across the entire collection.</para>
<term>man pages</term>
<listitem>
<para>The most most common format, inherited from Unix, a primitive form of
presentation markup. The <command>man(1)</command> 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.</para>
presentation markup.
<citerefentry>
<refentrytitle>man</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
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.</para>
<para>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 no support for
hyperlinks).</para>
with rich cross-references (the markup has only weak and normally unused
support for hyperlinks).</para>
</listitem>
</varlistentry>
<varlistentry>