Table of Contents
Here is a summary list of things to do before committing changes:
Test the instructions you are adding or changing
general.ent with the new
Check that all relevant files have been svn added or removed
Check that any new files have had the property settings updated with svn propset
Check that the book validates
Check that the book renders properly
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
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.
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>
[markh] with your belgarath
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
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
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
without errors. Instructions on how to render the book can be found
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.
Last updated by randy on 2007-04-03 14:00:09 -0600