lfs-book/HOWTO_EDIT

How to edit the LFS-BOOK
------------------------

This document explains the necessary steps to be taken in order to make
changes to the LFS-BOOK. Not every single aspect is detailed, just the
more tricky ones.

* No matter what, always make the following changes whenever you do
  something:

Whenever you make a change, no matter how small, update the book's version 
number:

1) Open the index.xml file.

2) Find <!ENTITY version "yyyymmdd"> and make sure it contains the date on 
which you are making the change. If today is June 11th, 2001, change it 
to <!ENTITY version "20010611".

3) Find <ENTITY releasedate "Month, day, year"> and make sure it contains 
the same date as the 'version' entity. If today is June 11th, 2001, change 
it to: <!ENTITY releasedate "June 11th, 2001">


* Updating a package's version

Follow these steps in order to change a package (for example when you tested 
a newer version and want to include it in the book). Let's assume you're
upgrading to bash-2.05.

1) Download bash-2.05 to the linuxfromscratch.org server in the 
/home/ftp/conglomeration directory. If the file isn't compressed with bzip2, 
but with gzip for example, ungzip it, then bzip2 it.

2) Enter the /home/ftp/cvs directory.

3) Remove the symlink that points to the previous version of the
package.

4) You can remove the real file from the /home/ftp/conglomeration
directory only is you are absolutely sure that there are no other books
currently online that use that package version. If you don't remember
which book versions are online right now, check the LFS website.

5) Make a new symlink by running the following command:
ln -s ../conglomeration/bash-2.05.tar.bz2

6) Obtain the file size of the new package (run ls -l
/home/ftp/conglomeration/packagename). Divide this number by 1024 and
remember the result.

7) Enter the /home/ftp directory and create a new lfs-packages tarball.
If today is June 11th, 2001 1:09 PM, run the following:
tar cvfh lfs-packages-intel-cvs-20010611-1309.tar cvs
mv lfs-packages-intel-cvs-20010611-1309.tar cvs

The reason for adding the hour and minute is that one may end up
creating more than one tarball a day and it's easier this way to find
out which packages file was being used in case there are a lot of
updates.

8) Obtain the file size of the newly created tarball by running ls -l,
divide the number by 1024 and remeber the result.

9) Open the index.xml file.

10) At the bottom of the file find the ENTITY that belongs to the package. 
You'll find it as <!ENTITY package-version "version">. Change the 
bash-version entity as follows: <!ENTITY bash-version "2.05">

11) Edit the <!ENTITY all-version> entity and update the file name to
match the name of the tarball you just created.

12) Edit the <!ENTITY all-version> entity and update the file name to
match the name of the new tarball you just created.

13) Open the chapter3/bash.xml file.

14) Enter the new size that you calculated in step 6.

15) Open the chapter3/all.xml file.

16) Update the file size to match the value you calculated in step 8.

17) Open the chapter3/packages.xml file, scroll to the bottom of the
file and enter the same size as you entered in the previous step. Also
divide this number by 1024 and enter the result as the MB value between
brackets.

Please don't use the "du -h" command to obtain the file size. The result
of du is not acurate enough (it doesn't report the actual file size, but
the size of clusters the file is using).

If you are updating more than one package at the same time, don't
re-create the tarball every time. Just update all the symlinks and
create a new tarball once that includes all your updated packages.


* Adding a new package update to Bugzilla

1) Login to bugzilla

2) Open bug #30

3) Check if the package is listed from a previous update

4) If so, reopen it and change the version number to match the new one

5) If not, add a new bug and fill it out as usual

6) When added, go back to the new bug and under "Bug xx depends on"
enter "30" so that this new bug is added to the parent bug #30

7) Click on "Commit" to commit this change