Here is a summary list of things to do before committing changes:

You should now be ready to commit your changes and update the Trac ticket to reflect the changes.

This may seem really obvious but <confession mode> some have actually committed small changes without testing them first, and had to change them (in one case twice) very quickly when someone noticed</confession mode>. So learn from our mistakes — check everything.

It is also a good practice to check any installed man pages for encoding not supported by the LFS system. This can be checked by running the following script with the current package manpages as arguments:

#!/bin/sh
# Begin checkman.sh
# Usage: find /usr/share/man -type f | xargs checkman.sh
for a in "$@"
do
    # echo "Checking $a..."
    # Pure-ASCII manual page (possibly except comments) is OK
    grep -v '.\\"' "$a" | iconv -f US-ASCII -t US-ASCII >/dev/null \
      2>&1 && continue
    # Non-UTF-8 manual page is OK
    iconv -f UTF-8 -t UTF-8 "$a" >/dev/null 2>&1 || continue
    # If we got here, we found UTF-8 manual page, bad.
    echo "UTF-8 manual page: $a" >&2
done
# End checkman.sh

The general.ent file contains entities that are used in multiple XML files throughout the book. Normally, it will contain version numbers of each package as well as general information such as the book's version number and release date. When making an update, the day/month/year and releasedate entities should be updated. The version numbers of packages should be updated as appropriate.

<!ENTITY day "01">
<!ENTITY month "08">
<!ENTITY year "2005">
<!ENTITY releasedate "August &day;st, &year">

Changelog updates should always be provided with the exception of small typo fixes. You don't need to add "fixed small typo in XXX" to the changelog otherwise it would become too large and make picking out meaningful updates difficult.

Changelog updates should be in a standard format. Note that there is only one entry for each day that there are changes, however, there can be many entries for any particular day. Here is an example:

<listitem>
  <para>April 29th, 2002</para>
  <itemizedlist>
    <listitem>
      <para>[markh] - Add DHCP_STOP variable to DHCP scripts.</para>
    </listitem>
    <listitem>
      <para>[markh] - Added the Imlib package.</para>
    </listitem>
  </itemizedlist>
</listitem>

Replace [markh] with your belgarath userid.

Changelog entries are always added to the top of the file. They are cleaned out after major releases and consolidated in the credits section.

If you are adding files, you need to run a svn add command on each of them (something like svn add mypackage*.xml often does the trick. In most cases you will also need to set the property settings on each new file:

        svn propset svn:keywords "LastChangedBy Date" <mypackage*.xml>

This command tells svn to substitute the current timestamp and author name into the file where it see the construct:

$LastChangedBy: randy $
$Date: 2007-04-03 14:00:09 -0600 (Tue, 03 Apr 2007) $

A good method to use if you've only added files (not taken any away) is to run an svn status command which will produce output something like this:

mark:~/LFS/BLFS$ svn status --show-updates
?                   .chapter04.xml.swp
?                   goTidy
MM           2539   chapter01.xml
MM           2539   chapter02.xml
MM     *     2539   chapter03.xml
MM           2539   chapter04.xml
C            2539   chapter05.xml
MM           2539   chapter06.xml
M            2539   general.ent
MM           2539   preface.xml
MM           2539   bookinfo.xml
 M           2539   index.xml
A               0   edguide.xsl
D            2539   stylesheets
D            2539   stylesheets/edguide.xsl
M            2539   Makefile
Status against revision:   2539

If you look at the first column, you will see various different letters which all mean different things.

?: This is what SVN reports when it doesn't manage a file. Generally it means that you've forgotten to svn add a file to the repository but can also just be temporary editor files which SVN doesn't know what to do with. If it's just a temporary file, don't worry, it won't try and commit them when you do a svn commit because you haven't added them. Instead it will just leave them alone.

A: This is a file which has been scheduled to be added to the repository with an svn add but has not yet been committed. When you're ready to commit it, simply do a svn add on it (and don't forget that nearly all SVN operations can be performed on as many files at once as you like. If you specify no file, it will either give you an error (if it doesn't make sense; like with svn add or delete) or it will simply perform the action on all files from that directory downwards in the tree (for example with svn commit).

D: This is a file which has been removed from the repository using svn delete but has not yet been committed. The equivalent of “A” for added files.

C: This means that you have made local changes but at the same time someone has made remote changes which can't be automatically merged with yours. You will have to go through the files and sort out the conflict yourself. Due to the nature of the BLFS book, this doesn't happen very often. One way to fix this problem is to do a svn update (abbreviated as svn up) and check the file for conflict markers in the file.

*: An asterisk in column eight means that the file in the repository has been changed. The file will be updated in your local sand box when an svn update is issued.

Once you know why you're getting each symbol, and they're all correct, you can proceed to the next step. There are other symbols that are not normally encountered. They are explained in more detail at http://svnbook.red-bean.com/en/1.2/svn.tour.cycle.html#svn.tour.cycle.examine.status.

Before committing any changes, it's important to check that you have all the syntax correct and that the book can actually pass through xsltproc without errors. Instructions on how to render the book can be found in the INSTALL and README files in the BOOK directory, but generally you can just run make validate from the BOOK directory to do a complete syntax check and a simple make to render the book on your local system. Note that you must have the required dependency packages installed on your local system.

Before you actually commit, spend a few seconds thinking about the comment (log message) you are going to add. As mentioned in the section on SVN commands, comments should always be used when committing changes. Even if the comment is just 'small typo fix', that will do. Other usual comments are “Updated to package-x.y.z” or “Added new section BLAH”.

To commit, you use the svn commit or svn ci command. A good example of a commit command could be:

svn ci -m "Added new package baldrick" index.xml \
introduction/welcome/changelog.xml introduction/welcome/credits.xml \
postlfs/postlfs.xml postlfs/config/baldrick/baldrick*.xml

If you have only made the changes regarding this package to your local tree, then you can save time by simply running:

svn ci -m "Added new package baldrick"

from the root of your local BLFS sandbox. The first command is more useful when you've modified files you don't want to commit yet.

The final part of updating the book is to update the Trac ticket. This is usually as easy as going to BLFS Trac (http://wiki.linuxfromscratch.org/blfs), opening the ticket, adding a short note what was done and changing the resolution to “fixed”.

Having completed all of this, you can now go and have a rest. Well done, thank you and good night.