This HOWTO is designed for people with experience in programming
and some skills in managing a software project but who are new to
the world of Free Software. This document is meant to act as a
- guide to the non-technical aspects of programming and was written
- to act as a crash course in the people skills that aren't taught
- to commercial coders but that can make or break a free software
- project.
+ guide to the non-technical aspects of free software development
+ and was written to act as a crash course in the people skills
+ that aren't taught to commercial coders but that can make or
+ break a free software project.
</para>
</abstract>
This HOWTO tries to do a lot of thing (probably too many), but it
can't answer that question and won't attempt it. What this HOWTO
will attempt to do is give your Free Software project a fighting
- chance-an edge. If you write a piece of crap that no one is
- interested in, you can read this HOWTO until you recite it in your
- sleep and your project will probably fail. Then again, you can
+ chance--an edge. If you write a piece of crap that no one is
+ interested in, you can read this HOWTO until you can recite it in
+ your sleep and your project will probably fail. Then again, you can
write a beautiful, relevant piece of software and follow every
instruction in this HOWTO and your software may still not make
it. Sometimes life is like that. However, I'll go out a limb and
A lot of the information in this HOWTO is best called common
sense. Of course, as any debate on interfaces will prove, what is
common sense to some programmers proves totally unintuitive to
- others. After explaining bites and pieces of this HOWTO to Free
- Software developers on several occasions, I realized that that
- writing this HOWTO might provide a useful resource and a forum for
+ others. After explaining bits and pieces of this HOWTO to Free
+ Software developers on several occasions, I realized that writing
+ this HOWTO might provide a useful resource and a forum for
programmers to share ideas about what has and has not worked for
- them.
- </para>
-
- <para>
-
+ them.
</para>
<para>
</para>
<para>
- Unless otherwise stated, Linux HOWTO documents are
- copyrighted by their respective authors. Linux HOWTO documents may
- be reproduced and distributed in whole or in part, in any medium
- physical or electronic, as long as this copyright notice is
- retained on all copies. Commercial redistribution is allowed and
- encouraged; however, the author would like to be notified of any
- such distributions.
+ Unless otherwise stated, Linux HOWTO documents are copyrighted by
+ their respective authors. Linux HOWTO documents may be reproduced
+ and distributed in whole or in part, in any medium physical or
+ electronic, as long as this copyright notice is retained on all
+ copies. Commercial redistribution is allowed and encouraged;
+ however, the author would like to be notified of any such
+ distributions.
</para>
<para>
</para>
<para>
- In short, we wish to promote dissemination of this
- information through as many channels as possible. However, we do
- wish to retain copyright on the HOWTO documents, and would like to
- be notified of any plans to redistribute the HOWTOs.
+ In short, we wish to promote dissemination of this information
+ through as many channels as possible. However, we do wish to
+ retain copyright on the HOWTO documents, and would like to be
+ notified of any plans to redistribute the HOWTOs.
</para>
<para>
- If you have any questions, please contact
+ If you have any questions, please contact
<email>linux-howto@metalab.unc.edu</email>
</para>
</sect2>
<para>
No liability for the contents of this documents can be accepted.
- Use the concepts, examples and other content at your own risk.
- As this is a new edition of this document, there may be errors
- and inaccuracies, that may of course be damaging to your system.
- Proceed with caution, and although this is highly unlikely,
- the author(s) do not take any responsibility for that.
+ Use the concepts, examples and other content at your own risk. As
+ this is a new edition of this document, there may be errors and
+ inaccuracies, that may of course be damaging to your system.
+ Proceed with caution, and although this is highly unlikely, the
+ author(s) do not take any responsibility for that.
</para>
<para>
<title>New Versions</title>
<indexterm>
- <primary>(your index root)!news on</primary>
+ <primary>fswd!news on</primary>
</indexterm>
<para>
more. <ulink url="http://cvsbook.red-bean.com">The book's
website</ulink> has information on ordering the book and provides
several translations of the chapters on CVS. I you are seriously
- interested in running a Free Software project, you want this book.
+ interested in running a Free Software project, you want this
+ book. I tried to mention Fogel in sections of this HOWTO where I
+ knew I was borrowing directly from his ideas. If I missed any, I'm
+ sorry, and I'll try and have those fixed in future versions.
</para>
<para>
com</email>
</para>
<para>
- Also providing support and material, and inspiration for this
- HOWTO is Eric S. Raymond for his prolific, consistent, and
- carefully crafted arguments, to Lawrence Lessig for reminding me
- of the importance of Free Software and to every user and developer
+ Also providing support material, and inspiration for this HOWTO is
+ Eric S. Raymond for his prolific, consistent, and carefully
+ crafted arguments, Lawrence Lessig for reminding me of the
+ importance of Free Software and finally, every user and developer
involved with the <ulink url="http://www.debian.org">Debian
Project</ulink>. The project has provided me with a home, a place
- to practice Free Software advocacy and to make a difference, a
- place to learn from those how have been involved with the movement
- much longer than I, and an proof of a Free Software project that
- <emphasis>definitely, definitely works</emphasis>.
+ to practice Free Software advocacy, a place to make a difference,
+ a place to learn from those how have been involved with the
+ movement much longer than I, and proof of a Free Software project
+ that definitely, definitely works.
</para>
<para>
Above all, I want to thank <emphasis>Richard Stallman</emphasis>
for his work at the Free Software Foundation and for never giving
- up. Stallman provided the philosophical basis that attracts me to
- Free Software and that drives me towards writing a document to
- make sure it succeeds. RMS can always be emailed at <email>rms
- (at) gnu (dot) org</email>.
+ up. Stallman provides and articulates the philosophical basis that
+ attracts me to Free Software and that drives me towards writing a
+ document to make sure it succeeds. RMS can always be emailed at
+ <email>rms (at) gnu (dot) org</email>.
</para>
</sect2>
<para>
Feedback is most certainly welcome for this document. Without your
submissions and input, this document wouldn't exist. Something
- missing? Don't hesitate to contact me and to write a chapter. I
- want this document to be as much a product of the Free Software
- development process that it heralds and I think its ultimate
- success will be rooted in this fact. Please send your additions,
- comments and criticisms to the following email address :
- <email>mako@debian. org</email>.
+ missing? Don't hesitate to contact me and to write a chapter or
+ section, or subsection. I want this document to be a product of
+ the Free Software development process that it heralds and I think
+ its ultimate success will be rooted in this fact. Please send your
+ additions, comments and criticisms to the following email address
+ : <email>mako@debian. org</email>.
</para>
</sect2>
I'd love for this HOWTO to gain the kind of international reach
afforded by a translated version.
</para>
+
<para>
However, this HOWTO is still young and I have to yet to be
- contacted about a translation so English is all that is
+ contacted about a translation so English is all that is currently
available. If you would like to help with or do a translation, you
will gain my utmost respect and admiration and you'll get to be
part of a cool process. If you are at all interested, please don't
<term>README or Readme</term>
<listitem>
- <para>
- A document containing all the basic installation,
- compilation, and even basic use instructions that make up
- the bare minimum information needed to get the program up and
- running. A README is not your chance to be verbose but needs
- to be concise and effective. An ideal README is at least 30
- lines long and more no more than 250.
- </para>
+ <para>A document containing all the basic installation,
+ compilation, and even basic use instructions that make up the
+ bare minimum information needed to get the program up and
+ running. A README is not your chance to be verbose but needs
+ to be concise and effective. An ideal README is at least 30
+ lines long and more no more than 250.</para>
</listitem>
</varlistentry>
<term>INSTALL or Install</term>
<listitem>
- <para>
- The INSTALL file should be much shorter than the INSTALL file
- and should quickly and concisely describe how to build and
- install the program. Usually an install simply instructs the
- user to run ./configure; make; make install and touches on
- any unusual options that may be necessary. More advanced
- users can usually avoid them but it's good practice to at
- least glance at the file to understand what can be
- expected. For most relatively standard install procedures and
- for most programs, INSTALL files are as short as possible are
- rarely over 100 lines.
- </para>
+ <para>The INSTALL file should be much shorter than the INSTALL
+ file and should quickly and concisely describe how to build
+ and install the program. Usually an install simply instructs
+ the user to run ./configure; make; make install and touches on
+ any unusual options that may be necessary. More advanced users
+ can usually avoid them but it's good practice to at least
+ glance at the file to understand what can be expected. For
+ most relatively standard install procedures and for most
+ programs, INSTALL files are as short as possible are rarely
+ over 100 lines.</para>
</listitem>
</varlistentry>
<term>Changelog, ChangeLog, CHANGELOG, or changelog</term>
<listitem>
- <para>
- A changelog is a simple file that every well-managed free
- software project should include. A changelog is simple the
- file that, as its name would imply, logs or documents the
- changes to a program. The most simple way to do a changelog
- is to simply keep a file with the source code for your
- program and add a section to the top of the changelog with
- each release describing what has been, changed, fixed, or
- added to the program. It's a good idea to post the changelog
- onto the website as well because it can help people decide
- whether they want or need to upgrade to a newer version or
- wait for a more significant upgrade.
- </para>
+ <para>A changelog is a simple file that every well-managed
+ free software project should include. A changelog is simple
+ the file that, as its name would imply, logs or documents the
+ changes to a program. The most simple way to do a changelog is
+ to simply keep a file with the source code for your program
+ and add a section to the top of the changelog with each
+ release describing what has been, changed, fixed, or added to
+ the program. It's a good idea to post the changelog onto the
+ website as well because it can help people decide whether they
+ want or need to upgrade to a newer version or wait for a more
+ significant upgrade.</para>
</listitem>
</varlistentry>
<term><acronym>FAQ</acronym></term>
<listitem>
- <para>
- For those of you that don't already
- know. <acronym>FAQ</acronym> stands for Frequently Asked
- Questions and the file is a collection of exactly that. FAQs
- are not difficult to make. Simply make a policy that if you
- are asked a question or see a question on a mailing list two
- or more times, add it the question (and its answer) to your
- FAQs. FAQs are more optional than the files listed above but
- they can save your time, increase usability, and decrease
- headaches on all sides.
- </para>
+ <para>For those of you that don't already
+ know. <acronym>FAQ</acronym> stands for Frequently Asked
+ Questions and the file is a collection of exactly that. FAQs
+ are not difficult to make. Simply make a policy that if you
+ are asked a question or see a question on a mailing list two
+ or more times, add it the question (and its answer) to your
+ FAQs. FAQs are more optional than the files listed above but
+ they can save your time, increase usability, and decrease
+ headaches on all sides.</para>
</listitem>
</varlistentry>
</sect3>
<sect3>
- <title>Website</title>
+ <title>Website</title>
<para>
It's only a sort of an issue of documentation but a good website
is quickly becoming an essential part of any free software
<varlistentry>
<term>Minimize the number of branches</term>
<listitem>
- <para>
- Debian may be able to make good use of four or five branches
- but it contains gigabytes of software in over 5000 packages
- compiled for a 5-6 different architectures. Two is a good
- number. Too many branches will confuse your users (I can't
- count how many times I had to describe Debian's system when it
- only had 2 and sometimes 3 branches!), potential developers
- and even yourself. Branches can help but they come at a cost
- so use them very sparingly.
- </para>
+ <para>Debian may be able to make good use of four or five
+ branches but it contains gigabytes of software in over 5000
+ packages compiled for a 5-6 different architectures. Two is a
+ good number. Too many branches will confuse your users (I can't
+ count how many times I had to describe Debian's system when it
+ only had 2 and sometimes 3 branches!), potential developers and
+ even yourself. Branches can help but they come at a cost so use
+ them very sparingly.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Make sure that all your different branches are explained</term>
<listitem>
- <para>
- As I mentioned in the preceding paragraph, different branches
- <emphasis>will</emphasis> confuse your users. Do everything
- you can to avoid this by clearly explaining the different
- branches in a prominent page on your website and in a Readme
- file in the <acronym>FTP</acronym> or <acronym>HTTP</acronym>
- directory.
- </para>
+ <para>As I mentioned in the preceding paragraph, different
+ branches <emphasis>will</emphasis> confuse your users. Do
+ everything you can to avoid this by clearly explaining the
+ different branches in a prominent page on your website and in a
+ Readme file in the <acronym>FTP</acronym> or
+ <acronym>HTTP</acronym> directory.</para>
<para>
I might also recommend against a mistake that I think Debian
<varlistentry>
<term>Make sure all your branches are always available</term>
<listitem>
- <para>
- Like a lot of document, this should probably should go without
- saying but experience has taught me that it's not always
- obvious to people. It's a good idea to physically split up
- different branches in different directories or directory trees
- on your <acronym>FTP</acronym> or <acronym>HTTP</acronym>
- site. Linux accomplishes this by having all the v2.2 and a
- v2.3 subdirectory where it is immediately obvious (after you
- know their version numbering scheme) which directory is the
- most recent stable and the current development
- releases. Debian accomplishes this by naming all their
- distribution by name and then changing symlinks named
- <quote>stable,</quote> <quote>unstable</quote> and
- <quote>frozen</quote> to point to which ever distribution (by
- name) is in whatever stage. Both methods work and their are
- others. In any case, it is important that different branches
- are always available, are accessible from consistent
- locations, and that different branches are clearly
- distinguished from each other so your users know exactly what
- they want to be downloading and where to get it.
- </para>
+ <para>Like a lot of document, this should probably should go
+ without saying but experience has taught me that it's not
+ always obvious to people. It's a good idea to physically split
+ up different branches in different directories or directory
+ trees on your <acronym>FTP</acronym> or <acronym>HTTP</acronym>
+ site. Linux accomplishes this by having all the v2.2 and a v2.3
+ subdirectory where it is immediately obvious (after you know
+ their version numbering scheme) which directory is the most
+ recent stable and the current development releases. Debian
+ accomplishes this by naming all their distribution by name and
+ then changing symlinks named <quote>stable,</quote>
+ <quote>unstable</quote> and <quote>frozen</quote> to point to
+ which ever distribution (by name) is in whatever stage. Both
+ methods work and their are others. In any case, it is important
+ that different branches are always available, are accessible
+ from consistent locations, and that different branches are
+ clearly distinguished from each other so your users know
+ exactly what they want to be downloading and where to get
+ it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>alpha releases</term>
<listitem>
- <para>
- Alpha releases are expected to be unstable, perhaps a little
- unsafe, but definitely usable. Alpha versions should have
- full functionality and limited testing. They can have known
- bugs and kinks that have yet to be worked out. Before sure to
- keep in mind that <emphasis>alpha releases are still
- releases</emphasis> and people are not going to be expecting
- a nightly build from the CVS source. An alpha should work and
- have minimal testing and bug fixing already finished.
- </para>
+ <para>Alpha releases are expected to be unstable, perhaps a
+ little unsafe, but definitely usable. Alpha versions should
+ have full functionality and limited testing. They can have
+ known bugs and kinks that have yet to be worked out. Before
+ sure to keep in mind that <emphasis>alpha releases are still
+ releases</emphasis> and people are not going to be expecting a
+ nightly build from the CVS source. An alpha should work and
+ have minimal testing and bug fixing already finished.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>beta releases</term>
<listitem>
- <para>
- Beta releases are general expected to be usable and
- slightly unstable, although definitely
- <emphasis>not</emphasis> unsafe. Beta releases usually
- preclude a full release by under a month. They can contain
- small known bugs but no major ones. All major functionality
- should be fully implemented although the exact mechanics can
- still be worked out. Beta releases are great tool to whet the
- appetites of potential users by giving them a very
- realistic view of where your project is going in the very
- near future and can help keep interest by giving people
- <emphasis>something.</emphasis>
- </para>
+ <para>Beta releases are general expected to be usable and
+ slightly unstable, although definitely
+ <emphasis>not</emphasis> unsafe. Beta releases usually
+ preclude a full release by under a month. They can contain
+ small known bugs but no major ones. All major functionality
+ should be fully implemented although the exact mechanics can
+ still be worked out. Beta releases are great tool to whet the
+ appetites of potential users by giving them a very realistic
+ view of where your project is going in the very near future
+ and can help keep interest by giving people
+ <emphasis>something.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>development releases</term>
<listitem>
- <para>
- Development release is much more vague term than
- <quote>alpha</quote> or <quote>beta</quote>. I usually choose
- to reserve the term for discussion of a development
- branch. There are other ways to use the term. So many in
- fact, that I feel the term has been cheapened. The popular
- window manager <ulink
- url="http://www.enlightenment.org">Enlightenment</ulink> has
- released <emphasis>nothing but</emphasis> development
- releases. Most often, the term is used to describe releases
- that are not even to alpha or beta stages though and if I
- were to release a pre-alpha release in order to keep interest
- in my project live, this is probably how I would have to label
- it.
- </para>
+ <para>Development release is much more vague term than
+ <quote>alpha</quote> or <quote>beta</quote>. I usually choose
+ to reserve the term for discussion of a development
+ branch. There are other ways to use the term. So many in fact,
+ that I feel the term has been cheapened. The popular window
+ manager <ulink
+ url="http://www.enlightenment.org">Enlightenment</ulink> has
+ released <emphasis>nothing but</emphasis> development
+ releases. Most often, the term is used to describe releases
+ that are not even to alpha or beta stages though and if I were
+ to release a pre-alpha release in order to keep interest in my
+ project live, this is probably how I would have to label
+ it.</para>
</listitem>
</varlistentry>
</para>
<para>
- Congratulations. You've not the maintainer of an active free
+ Congratulations. You've now the maintainer of an active free
software project. Good luck and feel free to stay in touch with
me about your experiences. I'd love to incorporate them into this
HOWTO.
projects / fspm_howto / blobdiff