mangavalk/lcdproc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Restructure chapters in the developer guide. Add chapter about programming and

Browse Source 
making releases. Add driver acceptance guideline.
This commit is contained in:
mmdolze
2010-11-20 16:45:22 +00:00
parent 29adfa40db
commit ca7ed773f1
8 changed files with 851 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/lcdproc-dev/Makefile.am
+7 -6
View File
@@ -1,15 +1,16 @@
## Process this file with automake to produce Makefile.in
EXTRA_DIST = lcdproc-dev.docbook \
EXTRA_DIST = add-your-driver.docbook \
bookinfo.docbook \
introduction.docbook \
shared-files.docbook \
make-driver.docbook \
add-your-driver.docbook \
driver-api.docbook \
introduction.docbook \
language.docbook \
lcdproc-dev.docbook \
license.docbook \
README.docbook
make-driver.docbook \
programming.docbook \
README.docbook \
shared-files.docbook
## convenience targets
docs/lcdproc-dev/add-your-driver.docbook
+93 -10
View File
@@ -5,33 +5,105 @@
<title>Introduction</title>
<para>
LCDproc is meant to be modular, it is relatively easy to add new input and output drivers to LCDproc.
LCDproc is meant to be modular, it is relatively easy to add new input and
output drivers to LCDproc.
</para>
<para>
This chapter will explain you the major steps and few gotchas of adding your own driver to LCDproc. Enjoy!
This chapter will explain you the major steps and few gotchas of adding your
own driver to LCDproc. Enjoy!
</para>
<para>
Be sure to read <xref linkend="programming"/> and <xref linkend="driver-api"/>
as well.
</para>
</sect1>
<sect1 id="driverrules">
<title>Rules for accepting new drivers</title>
<para>LCDproc is open source software. Anyone is free to take LCDproc's code, write
his own driver and publish the modified sources somewhere again. If you want your
driver to be included in LCDproc's code some conditions have to be met:</para>
<orderedlist>
<listitem>
<para>The hardware (display or enclosing product) is publicly sold
<emphasis>OR</emphasis> the schematics and firmware (if required) are publicy
available.
<footnote><para>Therefore I will not commit drivers for displays ripped out
from an old telephone for your private hardware project and are not
available otherwise.</para></footnote>
</para>
</listitem>
<listitem>
<para>The driver is released under (L)GPL and has an appropriate
copyright notice.</para>
</listitem>
<listitem>
<para>The submitter is or is acting on behalf of the original driver
developer.
<footnote><para>I will not submit drivers found somewhere on the internet and
submitted without the original developer's acknowledgement.</para></footnote>
</para>
</listitem>
<listitem>
<para>The driver describtion contains a valid email address for contacting
the submitter or developer.</para>
</listitem>
<listitem>
<para>The code is commented <emphasis>AND</emphasis> includes appropriate
Doxygen comments, especially for private / non-API functions.</para>
</listitem>
<listitem>
<para>End user documentation (updates to man pages <emphasis>AND</emphasis>
user-guide in docbook) is available.</para>
</listitem>
<listitem>
<para>Driver options are described in the end user documentation
<emphasis>AND</emphasis> <filename>LCDd.conf</filename>.</para>
</listitem>
<listitem>
<para>The driver adhere the style guide as described in <xref linkend="code-style"/>.</para>
</listitem>
</orderedlist>
</sect1>
<sect1 id="autoconfautomake">
<title>Autoconf, automake, and Everything!</title>
<para>How I Learned to Stop Worrying and Love the Configure Script</para>
<para>
It was decided pretty early in LCDproc's life to use GNU autoconf and GNU automake. This allows LCDproc to be ported to several platforms with much less effort. It can be quite daunting to understand how autoconf &amp; automake interact with each others and with your code, but don't be discouraged. We have taken great care in making this as simple as possible for programers to add their own driver to LCDproc. Hopefully, you'll only have to modify two files, one for autoconf and one for automake.
It was decided pretty early in LCDproc's life to use GNU autoconf and GNU
automake. This allows LCDproc to be ported to several platforms with much
less effort. It can be quite daunting to understand how autoconf &amp;
automake interact with each others and with your code, but don't be
discouraged. We have taken great care in making this as simple as possible
for programers to add their own driver to LCDproc. Hopefully, you'll only
have to modify two files, one for autoconf and one for automake.
</para>
<para>
The first thing you need to do is to find a name for your driver, it should be as descriptive as possible; most drivers are named after their respective chipset, for example hd44780, mtc_s16209x, sed1330 and stv5730, others are named after the company that makes that particular LCD display, for example CFontz and MtxOrb. Remember that these names are case sensitive. In this chapter, we'll use myDriver (which is an absolute non-descriptive name).
The first thing you need to do is to find a name for your driver, it should
be as descriptive as possible; most drivers are named after their respective
chipset, for example hd44780, mtc_s16209x, sed1330 and stv5730, others are
named after the company that makes that particular LCD display, for example
CFontz and MtxOrb. Remember that these names are case sensitive. In this
chapter, we'll use myDriver (which is an absolute non-descriptive name).
</para>
<sect2 id="autoconf">
<title>Autoconf and its friend, acinclude.m4</title>
<para>
You need to add your driver to function LCD_DRIVERS_SELECT of file acinclude.m4. This can be done in three steps.
You need to add your driver to function LCD_DRIVERS_SELECT of file
acinclude.m4. This can be done in three steps.
</para>
<sect3 id="autoconf-step1">
@@ -101,7 +173,10 @@ allDrivers=[bayrad,CFontz,CFontz633,...(big list)...,tyan,ula200,xosd,<emphasis>
</screen>
<para>
If your driver only works in some platform or requires a particular library or header, you can add your autoconf test here. You can see how other drivers do it, but if you're not sure on how to do this, just send an email to the mailing list and we'll make it for you.
If your driver only works in some platform or requires a particular library
or header, you can add your autoconf test here. You can see how other drivers
do it, but if you're not sure on how to do this, just send an email to the
mailing list and we'll make it for you.
</para>
</sect3>
@@ -111,12 +186,16 @@ If your driver only works in some platform or requires a particular library or h
<sect2 id="automake">
<title>Automake and its friend, Makefile.am</title>
<para>Allready half of the job is done! Not to bad, wasn't it? The rest should be just as easy. In this section, you'll be adding your driver to the file server/drivers/Makefile.am. As you can guess, it's the Makefile for the drivers. This can be done in three (or two) simple steps.</para>
<para>Allready half of the job is done! Not to bad, wasn't it? The rest
should be just as easy. In this section, you'll be adding your driver to the
file server/drivers/Makefile.am. As you can guess, it's the Makefile for the
drivers. This can be done in three (or two) simple steps.</para>
<sect3 id="automake-step1">
<title>Step 1</title>
<para>First, you need to add your driver to the list of drivers in this file, this list is called EXTRA_PROGRAMS.</para>
<para>First, you need to add your driver to the list of drivers in this file,
this list is called EXTRA_PROGRAMS.</para>
<para>This</para>
<screen>
@@ -132,9 +211,13 @@ EXTRA_PROGRAMS = bayrad CFontz ...(big list)... ula200 xosd <emphasis>myDriver</
<sect3 id="automake-step2">
<title>Step 2</title>
<para>This second step is only needed if your driver needs a particular library. If it doesn't, you can skip to step 3.</para>
<para>This second step is only needed if your driver needs a particular
library. If it doesn't, you can skip to step 3.</para>
<para>You basically need to put you driver name followed by _LDADD and egal this to the name of the library that you need. Usually, these library are substituted by a autoconf variable, if you're not comfortable with this, you send an email to the mailing list and we'll set this up for you.</para>
<para>You basically need to put you driver name followed by _LDADD and egal
this to the name of the library that you need. Usually, these library are
substituted by a autoconf variable, if you're not comfortable with this, you
send an email to the mailing list and we'll set this up for you.</para>
<para>For example, we would put this for our fictional driver</para>
<screen>
docs/lcdproc-dev/bookinfo.docbook
+10 -3
View File
@@ -5,21 +5,24 @@
<authorgroup>
<author>
<firstname>Markus</firstname>
<surname>Dolze</surname>
</author>
<author>
<firstname>Peter</firstname>
<surname>Marschall</surname>
<affiliation><address><email>peter@adpm.de</email></address></affiliation>
</author>
<author>
<firstname>Guillaume</firstname>
<surname>Filion</surname>
<affiliation><address><email>gfk@logidac.com</email></address></affiliation>
</author>
</authorgroup>
<date>2009-05-21</date>
<date>2010-11-20</date>
<releaseinfo>0.0.3</releaseinfo>
<abstract>
@@ -29,6 +32,10 @@ It covers LCDproc 0.5.x. Users should read the user guide.
</para>
</abstract>
<copyright>
<year>2010</year>
<holder>Markus Dolze</holder>
</copyright>
<copyright>
<year>2006</year>
<holder>Peter Marschall</holder>
docs/lcdproc-dev/lcdproc-dev.docbook
+4 -1
View File
@@ -3,11 +3,13 @@
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY bookinfo SYSTEM "bookinfo.docbook">
<!ENTITY introduction SYSTEM "introduction.docbook">
<!ENTITY programming SYSTEM "programming.docbook">
<!ENTITY shared-files SYSTEM "shared-files.docbook">
<!ENTITY language SYSTEM "language.docbook">
<!ENTITY driver-api SYSTEM "driver-api.docbook">
<!ENTITY make-driver SYSTEM "make-driver.docbook">
<!ENTITY add-your-driver SYSTEM "add-your-driver.docbook">
<!ENTITY releasing SYSTEM "releasing.docbook">
<!ENTITY license SYSTEM "license.docbook">
]>
@@ -17,10 +19,11 @@
&introduction;
&language;
&programming;
&shared-files;
&driver-api;
&add-your-driver;
&make-driver;
&releasing;
&license;
</book>
docs/lcdproc-dev/make-driver.docbook
-21
View File
@@ -1,22 +1,3 @@
<chapter id="make-driver">
<title>Making a LCDproc driver</title>
<sect1 id="make-driver-intro">
<title>Introduction</title>
<para>
LCDproc is meant to be modular, it is relatively easy to add new input and
output drivers to LCDproc. Actually, there are a few things that you can do
to make your life easier, they are listed here.
</para>
<para>
This chapter will explain you the major steps and few gotchas of adding your
own driver to LCDproc. Enjoy!
</para>
</sect1>
<sect1 id="driver-shared-files">
<title>Shared files specific for drivers</title>
@@ -443,5 +424,3 @@ myDriver_SOURCES: lcd.h lcd_lib.h myDriver.c myDriver.h report.h <emphasis>adv_b
</sect2>
</sect1>
</chapter>
docs/lcdproc-dev/programming.docbook
+436
View File
@@ -0,0 +1,436 @@
<chapter id="programming">
<title>Programming for LCDproc</title>
<sect1 id="getting-source">
<title>Get the source</title>
<para>If you want to start programming for LCDproc you will need the have
the most current source code available. You can get it several ways:</para>
<orderedlist>
<listitem>
<para>Download yesterday's CVS version of as a tarball (prefered).</para>
</listitem>
<listitem>
<para>Download the latest version from CVS.</para>
</listitem>
<listitem>
<para>Download the last stable release from Sourceforge. (This is not
recommended as stable release may be months behind the current version.)
</para>
</listitem>
</orderedlist>
<sect2 id="downloadtar">
<title>Download Yesterday's CVS Version of LCDproc as a Tarball</title>
<para>
There are nightly distributions of the CVS branches of LCDproc. You can
download them from <ulink url="http://lcdproc.sourceforge.net/nightly/"></ulink>.
For development we recommended to use the 'current' branch.
</para>
<para>
To extract the files run
</para>
<screen>
<prompt>$</prompt> <userinput>tar xvfz lcdproc-CVS-current.tar.gz</userinput>
</screen>
</sect2>
<sect2 id="downloadcvs">
<title>Download The Latest Version of LCDproc from CVS</title>
<para>
Of course you can download the latest stuff from CVS via anonymous login.
For more information on how to use CVS see
<ulink url="http://sourceforge.net/scm/?type=cvs&amp;group_id=119">About CVS</ulink>
on Sourceforge.
</para>
<para>
Login to CVS:
</para>
<screen>
<prompt>$</prompt> <userinput>cvs -d:pserver:anonymous@lcdproc.cvs.sourceforge.net:/cvsroot/lcdproc login</userinput>
</screen>
<para>
(Hit enter when prompted for a password.)
</para>
<para>
Get the files from CVS:
</para>
<screen>
<prompt>$</prompt> <userinput>cvs -d:pserver:anonymous@lcdproc.cvs.sourceforge.net:/cvsroot/lcdproc checkout -P lcdproc</userinput>
</screen>
<para>
Once you've done that and want to update the downloaded files to the latest stuff
you can use the "update" command of CVS (make sure to be in the lcdproc directory!):
</para>
<screen>
<prompt>$</prompt> <userinput>cvs update -d</userinput>
</screen>
<para>
Now that once you have downloaded the files you can prepare them for
compiling, but first you should (you don't have to) copy them to another
place on your machine.
</para>
</sect2>
</sect1>
<sect1 id="code-style">
<title>Code style guideline</title>
<para>
LCDproc has been developed by many contributors over many years. You may find
different programming styles (naming, indention, etc) in the source code.
</para>
<para>
When modifying an existing file, please take a careful look at its style and
program continueing that style instead of mixing it up with another one even
if it does not comply with the guidelines written below.
</para>
<para>
For newly added files the following guideline describes how source code
should look like.
</para>
<note>
<para>
All new submitted files will be passed through BSD <command>indent</command>
to enforce the style described below.
</para>
</note>
<sect2>
<title>File format and indention</title>
<itemizedlist mark="opencircle">
<listitem>
<para>
<emphasis>Language: </emphasis>The programming language used for LCDd
(server core), drivers and the lcdproc client is <literal>C</literal>.
No other programming lanuage will be accepted.
</para>
</listitem>
<listitem>
<para>
<emphasis>File encoding: </emphasis>Files shall either encoded as UTF-8 or
ISO-8859-1 and line endings shall be Unix type.
</para>
</listitem>
<listitem>
<para>
<emphasis>Line length: </emphasis>Lines of source code should be wrapped
at column 80.
</para>
</listitem>
<listitem>
<para>
<emphasis>Indention: </emphasis>Tab indention shall be used (with tab
width set to 8 characters). Only exception are switch labels which are
indented a half tab (4 characters).
</para>
</listitem>
<listitem>
<para>
<emphasis>License: </emphasis>LCDproc is released under GNU General Public
License version 2 (GPL v2) and every file shall have a standard copyright
notice.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Naming conventions</title>
<itemizedlist mark="opencircle">
<listitem>
<para>
<emphasis>Function names:</emphasis>
Function names shall be lowercase. We do not use CamelCase. Multiple words
are separated by underscore.
</para>
</listitem>
<listitem>
<para>
<emphasis>Variable names:</emphasis>
We do not use Hungarian Notation. CamelCase may be used,
but names shall beginn with a lowercase letter.
</para>
</listitem>
<listitem>
<para>
<emphasis>Constants:</emphasis>
Constants shall be written in uppercase using underscore to
separate multiple words.
</para>
</listitem>
</itemizedlist>
<example>
<title>Names of constants, variables and functions</title>
<screen>
/* Constants */
#define KEYPAD_AUTOREPEAT_DELAY 500
#define KEYPAD_AUTOREPEAT_FREQ 15
/* Variable names */
MODULE_EXPORT char * api_version = API_VERSION;
MODULE_EXPORT int stay_in_foreground = 0;
MODULE_EXPORT int supports_multiple = 1;
/* Function names */
void HD44780_position(Driver *drvthis, int x, int y);
static void uPause(PrivateData *p, int usecs);
unsigned char HD44780_scankeypad(PrivateData *p);
</screen>
</example>
</sect2>
<sect2>
<title>Comments</title>
<itemizedlist mark="opencircle">
<listitem>
<para>
All code comments shall be <literal>C</literal>-style comments (/* */).
Comments spanning multiple lines shall have a star at the beginning of
each line.
</para>
</listitem>
<listitem>
<para>
<literal>C++</literal>-style comments (//) may be used to comment out
single lines of code to disable these lines. Larger blocks of code which
shall be disabled should be wrapped within <literal>C</literal>-style
comments or using pre-processor directives (#if ... #endif).
</para>
<para>
<literal>C++</literal>-style comments shall not be used in general.
</para>
</listitem>
<listitem>
<para>
We use Doxygen to document our source code. Functions shall be documented
using Doxygen-style comments (/** *).
See <ulink url="http://www.stack.nl/~dimitri/doxygen/manual.html">Doxygen Manual</ulink>
for more information and how to use it.
</para>
</listitem>
<listitem>
<para>
If you carefully formatted a comment, you may use the special comment
/*- */ (comment start is <quote>star minus</quote>) to prevent automatic
reformatting. This usually applies to the standard copyright notice.
</para>
<example>
<title>Standard copyright notice</title>
<screen>
/*-
* Copyright (C) 2010 Your Name &lt;your_email_address&gt;
*
* This file is released under the GNU General Public License.
* Refer to the COPYING file distributed with this package.
*/
</screen>
</example>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Statement style</title>
<itemizedlist mark="opencircle">
<listitem>
<para><emphasis>Function declarations:</emphasis></para>
<para>
Function declarations have their declaration and
opening brace split accross two lines.
</para>
<para>
Function names start in column one. The return type is placed on the
previous line.
</para>
<para>
There is no space between the function name and '('.
</para>
<example>
<title>A function declaration</title>
<screen>
/**
* This is a Doxygen function description.
*
* \param y The number of years
* \param str Pointer to a string containing X
* \return 0 on success; -1 on error
*/
int
this_is_a_function(int y, char *str)
{
code
}
</screen>
</example>
</listitem>
<listitem>
<para><emphasis>Operators:</emphasis></para>
<para>
There shall be a space characters before/after an operator or assignment,
except for increment (<quote>++</quote>) or decrement (<quote>--</quote>)
operators.
</para>
<example>
<title>Space around operators</title>
<screen>
if (p->dispSizes[dispID - 1] == 1 &amp;&amp; p->width == 16) {
if (x >= 8) {
x -= 8;
relY = 1;
}
}
x--; /* Convert 1-based coords to 0-based */
y--;
</screen>
</example>
</listitem>
<listitem>
<para><emphasis>Function calls:</emphasis></para>
<para>
There shall be no space between the function call and the opening '(' of
the parameter list. Within the parameter list a space shall be after each
parameter.
</para>
<example>
<title>Function call</title>
<screen>
lib_vbar_static(drvthis, x, y, len, promille, options, p->cellheight, 0);
</screen>
</example>
</listitem>
<listitem>
<para><emphasis>Compound statements:</emphasis></para>
<para>
Opening braces occur on the same line as the
statement.
</para>
<para>
Else statements: Else statements are placed on a line of their own, even
is there is a previous closing brace.
</para>
<para>
Opening and closing braces may be ommited on single line compound
statements. However, if one part of an if-else-statement requires braces
the other part shall have braces as well.
</para>
<example>
<title>If-else with braces</title>
<screen>
if (...) {
code
}
else {
code
}
</screen>
</example>
<example>
<title>If-else with single statements</title>
<screen>
if (...)
print();
else
err = 1;
</screen>
</example>
<example>
<title>Other compound statements</title>
<screen>
while (...) {
code
}
for (a = 0; a &lt; max; a++) {
code
}
/* case labels are indented one half tab stop (4 spaces) */
switch (icon) {
case ICON_BLOCK_FILLED:
HD44780_set_char(drvthis, 6, block_filled);
break;
case ICON_HEART_FILLED:
HD44780_set_char(drvthis, 0, heart_filled);
break;
case ICON_HEART_OPEN:
HD44780_set_char(drvthis, 0, heart_open);
break;
default:
return -1; /* Let the core do other icons */
}
</screen>
</example>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="submitting-code">
<title>Submitting code</title>
<para>When you have finished modifying the code you may decide to submit it to
the LCDproc project. You usually do this by submitting a patch for review to the
mailing list.</para>
<para>To create a patch you need the unmodified files and the files containing
your modificatiosn. Usually you do this by storing an unmodified copy of the
sources in one directory and another copy with your modifications in another
one. You then run <command>diff</command> like this:</para>
<para><command>diff</command><option>-urN</option>
<option>-X <replaceable>unmodified-dir</replaceable>/diff_ignore</option>
<option><replaceable>unmodified-dir</replaceable></option>
<option><replaceable>your-source-dir</replaceable></option>
&gt; <replaceable>mymodifications.patch</replaceable></para>
<important>
<para>Please use unified diff format (<option>-u</option> option) only!</para>
<para>When running <command>diff</command> using <option>-X diff_ignore</option>
is strongly recommended. The file <filename>diff_ignore</filename> contains an
exclusion list which makes <command>cvs</command> ignore all generated files
(Makefiles, log files, object files, etc.)</para>
</important>
<para>If you have modified files in a source tree you checked out from CVS
you can also run <command>cvs diff</command> from the working directory:</para>
<para><command>cvs diff</command><option>-u</option>
&gt; <replaceable>mymodifications.patch</replaceable></para>
<note>
<para>Some versions of <command>cvs diff</command> will not handle new files
because these are unkown to the repository. There are ways to make cvs believe
the files existed previously (fake add) but this is not recommended. You will
need to submit new files 'as-is' in this case.</para>
</note>
</sect1>
</chapter>
docs/lcdproc-dev/releasing.docbook
+299
View File
@@ -0,0 +1,299 @@
<chapter id="releasing">
<title>Making a release</title>
<para>
This chapter describes the steps necessary to create a software release of
LCDproc. It is intended to guide the release manager when creating a new
release.
</para>
<sect1 id="releasing-software">
<title>Creating a source code release</title>
<procedure><title>Steps to create a new software release of LCDproc</title>
<step>
<para>
Update year of release in HEAD. The following files need to be updated:
<itemizedlist spacing="compact">
<listitem><para><filename>server/main.c</filename></para></listitem>
<listitem><para><filename>clients/lcdproc/main.c</filename></para></listitem>
<listitem><para><filename>docs/lcdproc-user/bookinfo.docbook</filename></para></listitem>
<listitem><para><filename>docs/lcdproc-dev/bookinfo.docbook</filename></para></listitem>
</itemizedlist>
</para>
</step>
<step>
<para>
Make a backup of the CVS repository to the local disk. This is needed if
something goes wrong. Run:
<userinput>rsync -av 'lcdproc.cvs.sourceforge.net::cvsroot/lcdproc/*' .</userinput>
</para>
</step>
<step>
<para>
Check out the CVS stable release branch. Run:
<userinput>
cvs -d:ext:<replaceable>&lt;your_sf_userid&gt;</replaceable>@lcdproc.cvs.sourceforge.net:/cvsroot/lcdproc checkout -r stable-0-5-x -d lcdproc-0-5-x lcdproc
</userinput> and change into the <filename>stable-0-5-x</filename> directory.
</para>
</step>
<step performance="optional">
<para>
Merge HEAD to stable. This step is only required if the release
will be done from HEAD.
</para>
<substeps>
<step>
<para>
Run:
<userinput>cvs -q update -j stable-0-5-x -j HEAD</userinput>
</para>
</step>
<step>
<para>
Revert files that need to retain their version number after merge. Due to
some wired import of external files, some files always get their $Id$ tag
updated, even if there has been no change. The following files should be
reverted to their previous version (given that there has really no change
happened):
<itemizedlist spacing="compact">
<listitem><para><filename>clients/examples/lcdident.pl</filename></para></listitem>
<listitem><para><filename>clients/metar/lcdmetar.pl</filename></para></listitem>
<listitem><para><filename>contrib/interface-demo2/interface.c</filename></para></listitem>
<listitem><para><filename>contrib/interface-demo2/nstrcmp.c</filename></para></listitem>
</itemizedlist>
Run <userinput>cvs update -C</userinput> on these files.
</para>
</step>
<step>
<para>
Update version numbers for stable branch. See <xref linkend="files-with-version-numbers"/>
for the list of affected files.
</para>
</step>
<step>
<para>
Commit everything. Run: <userinput>cvs commit -m "Sync with HEAD"</userinput>
</para>
</step>
</substeps>
</step>
<step>
<substeps>
<step>
<para>
Create a release branch in CVS. Run:
<userinput>cvs tag -b lcdproc-0-5-<replaceable>A</replaceable></userinput> where
<replaceable>A</replaceable> is the version number of the next release.
</para>
<note>
<para>Release branch names are all lowercase with hypens to separate
elements!</para>
</note>
</step>
<step>
<para>
Now you have created a branch from which the new release will done. Before
continuing either checkout this new branch to a new workding directory
or update the current one by running:
<userinput>cvs update -r lcdproc-0-5-<replaceable>A</replaceable></userinput>
</para>
</step>
</substeps>
</step>
<step>
<para>
Update version numbers for release and commit the changes. See
<xref linkend="files-with-version-numbers"/> for the list of affected files.
</para>
</step>
<step>
<para>
Set a CVS tag for the release. Run: <userinput>cvs tag LCDPROC_0_5_<replaceable>A</replaceable>_RELEASE</userinput>
where <replaceable>A</replaceable> is the version number of the next release.
</para>
<note>
<para>Release tag names are all uppercase with underscores to separate
elements!</para>
</note>
</step>
<step>
<para>
Export the release source tree as anonymous. This step is intended to check
if all files are correctly tagged with the new release in the source tree.
</para>
<para>
Run: <userinput>cvs -d :pserver:anonymous@lcdproc.cvs.sourceforge.net:/cvsroot/lcdproc
-z3 export -r LCDPROC_0_5_<replaceable>A</replaceable>_RELEASE lcdproc</userinput>
</para>
</step>
<step>
<para>
Create the release tarball by running:
</para>
<screen>
<userinput>
sh autogen.sh
./configure
make distcheck
</userinput>
</screen>
</step>
<step>
<para>
Test the newly created release tarball at least once. Try to build and
install it with all drivers enabled. Better: Try to build and install with
several library options turned on and off.
</para>
</step>
<step>
<para>
Create the release notes. The release notes should be an easy to read
summary of changes in this release. The <filename>ChangeLog</filename>
file is not very good as release notes as it is just a chronological
list of things that happen.
</para>
<para>
The release notes should talk about:
<itemizedlist>
<listitem><para>Fingerprint (SHA-1) of the release tarball</para></listitem>
<listitem><para>Known bugs</para></listitem>
<listitem><para>New drivers</para></listitem>
<listitem><para>Other important changes within drivers, the server core and
clients</para></listitem>
<listitem><para>Everything else the user has to now for upgrading his
installed version</para></listitem>
</itemizedlist>
grouped by topics of interest.
</para>
</step>
<step>
<para>
Upload the new release and release notes to Sourceforge.
</para>
</step>
<step>
<para>
Announce the new release.
</para>
<para>
Send notice about the new release to the LCDproc mailing list
(<email>lcdproc@lists.omnipotent.net</email>) and the lcdproc-announce
mailing list on Sourceforge (<email>lcdproc-announce@lists.sourceforge.net</email>).
Also mention the new release on the LCDproc website download and front page.
</para>
</step>
</procedure>
<itemizedlist id="files-with-version-numbers">
<title>Files that need version numbers updated</title>
<listitem><para><filename>BUGS</filename></para></listitem>
<listitem><para><filename>ChangeLog</filename></para></listitem>
<listitem><para><filename>configure.in</filename></para></listitem>
<listitem><para><filename>server/menuscreens.c</filename></para></listitem>
<listitem><para><filename>docs/lcdproc-dev/bookinfo.docbook</filename></para></listitem>
<listitem><para><filename>docs/lcdproc-dev/driver-api.docbook</filename></para></listitem>
<listitem><para><filename>docs/lcdproc-dev/introduction.docbook</filename></para></listitem>
<listitem><para><filename>docs/lcdproc-user/bookinfo.docbook</filename></para></listitem>
<listitem><para><filename>docs/lcdproc-user/how-to-obtain.docbook</filename></para></listitem>
</itemizedlist>
</sect1>
<sect1 id="releasing-documentation">
<title>Creating a documentation release</title>
<para>
Any release of LCDproc is accompanied the the user guide and developer guide.
Here is how to create these documentation packages.
</para>
<procedure><title>Steps to create the documentation package</title>
<step>
<para>
Get the release tarball and extract it (or change to the CVS directory
exported in <xref linkend="releasing-software"/> and change to <filename>docs/lcdproc-user</filename>.
</para>
</step>
<step>
<para>
Create the documentation package by running:
<userinput>xmlto -o lcdproc-0-5-<replaceable>A</replaceable>-user-html xhtml lcdproc-user.docbook</userinput>
</para>
</step>
<step>
<para>
Create a tarfile of the documentation package:
<userinput>tar -czf lcdproc-0-5-<replaceable>A</replaceable>-user-html.tar.gz
lcdproc-0-5-<replaceable>A</replaceable>-user-html</userinput>
</para>
</step>
<step>
<para>
Repeat the above steps for the developers guide, replacing <quote>-user</quote>
with <quote>-dev</quote> where appropriate.
</para>
</step>
<step>
<para>
Upload the files to the Sourceforge file release system.
</para>
</step>
</procedure>
<para>
The online documenation consists of the user and developer guide, each
converted to a single file for viewing online.
</para>
<procedure><title>Steps to create the online documentation</title>
<step>
<para>
Get the release tarball and extract it (or change to the CVS directory
exported exported in <xref linkend="releasing-software"/> and change to <filename>docs/lcdproc-user</filename>.
</para>
</step>
<step>
<para>
Create the documentation file by running:
<userinput>xmlto xhtml-nochunks lcdproc-user.docbook</userinput>
</para>
</step>
<step>
<para>
Rename the file: <userinput>mv lcdproc-user.html lcdproc-0-5-<replaceable>A</replaceable>-user.html</userinput>
</para>
</step>
<step>
<para>
Repeat the above steps for the developers guide, replacing <quote>-user</quote>
with <quote>-dev</quote> where appropriate.
</para>
</step><step>
<para>
Upload the files to our Sourceforge web site (not the file release system!)
and change <filename>htdocs/docs/index.html</filename> to point to the new
files.
</para>
</step>
</procedure>
</sect1>
</chapter>
docs/lcdproc-dev/shared-files.docbook
+2
View File
@@ -272,4 +272,6 @@ LL_MoveNode(list, amount); // Slides a node to another spot in the list
</sect1>
&make-driver;
</chapter>