cvs commit: LFS/editor-manual/chapter05 addingcomments.xml chapter05.xml enternewbugs.xml introduction.xml

gerard at linuxfromscratch.org gerard at linuxfromscratch.org
Tue May 28 14:41:13 PDT 2002


gerard      02/05/28 14:41:13

  Added:       editor-manual index.xml
               editor-manual/book book.xml
               editor-manual/bookinfo abstract.xml authorgroup.xml
                        bookinfo.xml copyright.xml legalnotice.xml
               editor-manual/chapter01 chapter01.xml
               editor-manual/chapter02 anoncvs.xml chapter02.xml cvsssh.xml
                        introduction.xml
               editor-manual/chapter03 add.xml chapter03.xml checkout.xml
                        commit.xml delete.xml diff.xml introduction.xml
                        moving.xml update.xml
               editor-manual/chapter04 bugzilla.xml chapter04.xml
                        checkfiles.xml checkrender.xml commit.xml
                        introduction.xml test.xml updatechangelog.xml
                        updatecredits.xml updateindex.xml
               editor-manual/chapter05 addingcomments.xml chapter05.xml
                        enternewbugs.xml introduction.xml
  Log:
  initial commit of lfs editor's manual
  
  Revision  Changes    Path
  1.1                  LFS/editor-manual/index.xml
  
  Index: index.xml
  ===================================================================
  <?xml version="1.0" encoding="ISO-8859-1"?>
  <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                          "/usr/share/docbook/docbookx.dtd" [
  
  
  <!ENTITY book SYSTEM "book/book.xml">
  
  <!ENTITY version "20020528">
  <!ENTITY releasedate "May 28th, 2002">
  
  <!ENTITY % bookinfo SYSTEM "entities/bookinfo.ent">
  <!ENTITY % dedication SYSTEM "entities/dedication.ent">
  <!ENTITY % preface SYSTEM "entities/preface.ent">
  <!ENTITY % chapter01 SYSTEM "entities/chapter01.ent">
  <!ENTITY % chapter02 SYSTEM "entities/chapter02.ent">
  <!ENTITY % chapter03 SYSTEM "entities/chapter03.ent">
  <!ENTITY % chapter04 SYSTEM "entities/chapter04.ent">
  <!ENTITY % chapter05 SYSTEM "entities/chapter05.ent">
  
  %bookinfo;
  %dedication;
  %preface;
  %chapter01;
  %chapter02;
  %chapter03;
  %chapter04;
  %chapter05;
  
  
  ]>
  
  <book>
  
  &book;
  
  </book>
  
  
  
  1.1                  LFS/editor-manual/book/book.xml
  
  Index: book.xml
  ===================================================================
  &bookinfo;
  &dedication;
  &preface;
  
  &chapter01;
  &chapter02;
  &chapter03;
  &chapter04;
  &chapter05;
  
  
  
  1.1                  LFS/editor-manual/bookinfo/abstract.xml
  
  Index: abstract.xml
  ===================================================================
  <abstract>
  <para>This manual teaches you how to properly edit the LFS-Book.</para>
  </abstract>
  
  
  
  1.1                  LFS/editor-manual/bookinfo/authorgroup.xml
  
  Index: authorgroup.xml
  ===================================================================
  <authorgroup>
  
  <author><firstname>Gerard</firstname><surname>Beekmans</surname></author>
  
  </authorgroup>
  
  
  
  
  1.1                  LFS/editor-manual/bookinfo/bookinfo.xml
  
  Index: bookinfo.xml
  ===================================================================
  <bookinfo>
  <title>Linux From Scratch Editor's Manual</title>
  <subtitle>Version &version;</subtitle>
  
  &bi-authorgroup;
  &bi-copyright;
  &bi-legalnotice;
  &bi-abstract;
  
  </bookinfo>
  
  
  
  1.1                  LFS/editor-manual/bookinfo/copyright.xml
  
  Index: copyright.xml
  ===================================================================
  <copyright id="copyright">
  
  	<year>2002</year>
  	<holder>Gerard Beekmans</holder>
  
  </copyright>
  
  
  
  1.1                  LFS/editor-manual/bookinfo/legalnotice.xml
  
  Index: legalnotice.xml
  ===================================================================
  <legalnotice>
  
  <para>Copyright (c) 2002, Gerard Beekmans</para>
  
  <para>All rights reserved.</para>
  
  <para>Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions are
  met:</para>
  
  <itemizedlist>
  
  <listitem><para>Redistributions in any form must retain the above copyright 
  notice, this list of conditions and the following disclaimer.</para></listitem>
  
  <listitem><para>Neither the name of "Linux From Scratch" nor the names of 
  its contributors may be used to endorse or promote products derived from 
  this material without specific prior written permission.</para></listitem>
  
  <listitem><para>Any material derived from Linux From Scratch must contain 
  a reference to the "Linux From Scratch" project.</para></listitem>
  
  </itemizedlist>
  
  <para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
  IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</para>
  
  </legalnotice>
  
  
  
  
  1.1                  LFS/editor-manual/chapter01/chapter01.xml
  
  Index: chapter01.xml
  ===================================================================
  <chapter id="chapter01">
  <title>LFS Development</title>
  <?dbhtml filename="chapter01.html" dir="chapter01"?>
  
  <para>LFS development takes place using three main systems. Firstly,
  the mailing lists <userinput>lfs-book</userinput>,
  <userinput>lfs-dev</userinput> and (to a lesser extent) 
  <userinput>lfs-support</userinput>. Secondly the Bugzilla tracking
  system, and thirdly the CVS server where the book itself is
  stored. All of these services are provided by the server
  <userinput>linuxfromscratch.org</userinput> also known as
  <userinput>shadowfax.linuxfromscratch.org</userinput> or more usually,
  <userinput>shadowfax</userinput>. This single server provides mailing
  lists, web hosting, CVS hosting, ftp hosting, the Bugzilla system and
  basically everything we use to work on the LFS project.</para>
  
  <para>The actual LFS book itself is written using Docbook-XML and at
  first can seem to be a daunting tangle of files. If you're confused, start
  by looking at <filename>index.xml</filename>. At the bottom, you will
  notice that it will reference the entity &book;. Look up the entity
  &book; and you will see that it points to the file
  <filename>book/book.xml</filename>. Continue in this way and you'll find
  your way around the book soon enough.</para>
  
  <para>The Bugzilla bug-tracking system for LFS can be found at <ulink
  url="http://bugs.linuxfromscratch.org"/>. In order to be able to
  add, remove and edit bugs, you need to add an account and make sure you
  are logged in whenever you wish to perform such an action.  You can
  query and read the bug database without logging in or creating a user.
  Note that all bugzilla messages are copied to the
  <userinput>lfs-book</userinput> mailing list and that all editors
  should be subscribed to this and the <userinput>lfs-dev</userinput>
  list at a minimum.</para>
  
  <para>Finally, there is the CVS server which will be discussed in the
  following chapters.</para>
  
  </chapter>
  
  
  
  1.1                  LFS/editor-manual/chapter02/anoncvs.xml
  
  Index: anoncvs.xml
  ===================================================================
  <sect1 id="ch02-anoncvs">
  <title>Anonymous Access</title>
  <?dbhtml filename="anoncvs.html" dir="chapter02"?>
  
  <para>To get anonymous access, simply use the following commands (note
  that these assume you are using bash or a similar shell:</para>
  
  <para><screen><userinput>export CVSROOT=:pserver:anonymous at cvs.linuxfromscratch.org:/home/cvsroot &&
  cvs login &&
  cvs checkout BLFS</userinput></screen></para>
  
  <para>When prompted for a password, just hit enter.</para>
  
  <para>This will create the LFS directory and copy the current working
  tree into it.  When you wish to update your local copy (often called a
  sandbox), simply cd into the directory and run:
  <screen><userinput>cvs update</userinput></screen></para>
  
  </sect1>
  
  
  
  
  1.1                  LFS/editor-manual/chapter02/chapter02.xml
  
  Index: chapter02.xml
  ===================================================================
  <chapter id="chapter02">
  <title>CVS Access</title>
  <?dbhtml filename="chapter02.html" dir="chapter02"?>
  
  &c2-introduction;
  &c2-anoncvs;
  &c2-cvsssh;
  
  </chapter>
  
  
  
  1.1                  LFS/editor-manual/chapter02/cvsssh.xml
  
  Index: cvsssh.xml
  ===================================================================
  <sect1 id="ch02-cvsssh">
  <title>CVS SSH Access (for editors)</title>
  <?dbhtml filename="cvsssh.html" dir="chapter02"?>
  
  <para>For editors, access is slightly more complicated. You first of
  all need to generate yourself an ssh key-pair. You then need to upload
  your public key into your <filename>~/.ssh</filename> directory on
  shadowfax. To generate the keys run:</para>
  
  <para><screen><userinput>ssh-keygen -t dsa</userinput></screen></para>
  
  <para>When prompted as to where to save them, it's probably best to leave
  them in .ssh (as <filename>id_dsa</filename> and
  <filename>id_dsa.pub</filename>) unless you already have ssh keys there.
  When prompted for a passphrase just press enter (unless you want to have
  to give the phrase <emphasis>every</emphasis> time you perform a cvs
  operation.  Having generated your keys, upload
  <filename>~/.ssh/id_dsa.pub</filename> to shadowfax and move it to
  <filename>~/.ssh/authorized_keys2</filename> <emphasis>on
  shadowfax</emphasis>.  (Your local copy of <filename>id_dsa</filename>
  and <filename>id_dsa.pub</filename> should remain untouched by
  this.)</para>
  
  <para>Once you've done this, you need to set environment variables like
  this:</para>
  
  <para><screen><userinput>export CVS_RSH=ssh &&
  export CVSROOT=:ext:USERNAME at cvs.linuxfromscratch.org:/home/cvsroot</userinput></screen></para>
  
  <para>Replace <emphasis>USERNAME</emphasis> with your shadowfax username.</para>
  
  <para>Once you have this setup, try to checkout the LFS tree by
  running:</para>
  
  <para><screen><userinput>cvs checkout BLFS</userinput></screen></para>
  
  <para>If this works, you'll get the LFS directory listing and you have
  your own sandbox.  You also have write access so from now on be extra
  careful but note that <emphasis>no</emphasis> changes will be made until
  you use a <userinput>cvs commit</userinput> command.</para>
  
  <para>As with anonymous access, you can update your local copy by simply
  cd'ing into the LFS directory and running:</para>
  
  <para><screen><userinput>cvs update</userinput></screen></para>
  
  </sect1>
  
  
  
  
  1.1                  LFS/editor-manual/chapter02/introduction.xml
  
  Index: introduction.xml
  ===================================================================
  <sect1 id="ch02-introduction">
  <title>Introduction</title>
  <?dbhtml filename="introduction.html" dir="chapter02"?>
  
  <para>The shadowfax CVS server provides services for all of the *LFS
  projects (and some others). The tree which we are interested in for
  LFS editing is (unsurprisingly) the LFS tree.  A complete list of the
  modules which are available can be found using the cvsweb interface at
  <ulink url="http://cvs.linuxfromscratch.org/index.cgi/"/>.</para> 
  
  <para>There are two types of CVS access provided to the LFS tree.
  Firstly, there is anonymous read-only access which anyone can use.
  Secondly, there is read-write access granted to active editors who have
  shadowfax accounts.</para>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter03/add.xml
  
  Index: add.xml
  ===================================================================
  <sect1 id="ch03-add">
  <title>cvs add</title>
  <?dbhtml filename="add.html" dir="chapter03"?>
  
  <para><userinput>cvs add</userinput>. When you created a new file,
  you need to tell the CVS server about it. Note that the file won't appear in
  the repository on shadowfax until you do a <userinput>cvs commit</userinput>
  (see below).</para>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter03/chapter03.xml
  
  Index: chapter03.xml
  ===================================================================
  <chapter id="chapter03">
  <title>Basic CVS Commands</title>
  <?dbhtml filename="chapter03.html" dir="chapter03"?>
  
  &c3-introduction;
  &c3-checkout;
  &c3-add;
  &c3-delete;
  &c3-update;
  &c3-commit;
  &c3-diff;
  &c3-moving;
  
  </chapter>
  
  
  
  1.1                  LFS/editor-manual/chapter03/checkout.xml
  
  Index: checkout.xml
  ===================================================================
  <sect1 id="ch03-checkout">
  <title>cvs checkout/co</title>
  <?dbhtml filename="checkout.html" dir="chapter03"?>
  
  <para><userinput>cvs checkout</userinput> or <userinput>cvs
  co</userinput>. This command is used to pull a CVS tree such as
  <filename>LFS/BOOK</filename> (the LFS book) or
  <filename>BLFS</filename> (the BLFS book) from the server.  You
  should only need to do this once. If we mess around with the directory
  structure (as sometimes is necessary), you may occasionally need to
  delete your local sandbox and re-check it out. If this is going to be
  needed, it will usually be because the Editor will have made a
  <emphasis>large</emphasis> change and it'll be announced at least on the
  <filename>lfs-book</filename> list.</para>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter03/commit.xml
  
  Index: commit.xml
  ===================================================================
  <sect1 id="ch03-commit">
  <title>cvs commit/ci</title>
  <?dbhtml filename="commit.html" dir="chapter03"?>
  
  <para><userinput>cvs commit</userinput> or <userinput>cvs ci</userinput>.
  This command recursively sends your changes to the CVS server. It will
  commit changed files, added files and deleted files. The -m option can be
  used to pass a log message to the command. If you don't specify a
  <emphasis>-m "MESSAGE"</emphasis>, then it will open the default editor and
  ask you to type in a log. Please don't use empty log messages (see later in
  this document on the policy which governs them).</para>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter03/delete.xml
  
  Index: delete.xml
  ===================================================================
  <sect1 id="ch03-delete">
  <title>cvs delete/remove</title>
  <?dbhtml filename="delete.html" dir="chapter03"?>
  
  <para><userinput>cvs delete</userinput> or <userinput>cvs
  remove</userinput>. This does what it says: remove (a) file(s) from the
  repository on shadowfax. Note that you have to have deleted the file
  locally before you can run this. Again, the file will not be deleted from
  the server until you do a <userinput>cvs commit</userinput>.</para>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter03/diff.xml
  
  Index: diff.xml
  ===================================================================
  <sect1 id="ch03-diff">
  <title>cvs diff</title>
  <?dbhtml filename="diff.html" dir="chapter03"?>
  
  <para><userinput>cvs diff</userinput>. This is useful for three different
  purposes.</para>
  
  <para>Firstly, those without write access to the LFS CVS server can use it
  to generate patches to send to <userinput>lfs-dev</userinput>. To do this,
  simply edit the files in your local sandbox then run
  <userinput>cvs diff -u > FILE.patch</userinput> from the root of your
  LFS directory. You can then attach this file to a message to the
  <userinput>lfs-dev</userinput> list where someone with editing rights will
  pick it up and apply it to the book.</para>
  
  <para>The second use is to find out what has changed between two revisions
  of a file by running:</para>
  
  <para><screen><userinput>cvs diff -u -r revision1 -r revision2 FILENAME</userinput></screen></para>
  
  <para>For example:
  <userinput>cvs diff -u -r 1.68 -r 1.69 index.xml</userinput> will output a
  unified diff showing the changes between revisions 1.68 and 1.69 of
  <filename>index.xml</filename>.</para>
  
  <para>Remember that when using cvs diff, you nearly
  <emphasis>always</emphasis> want to output a unified diff and so either
  use the <userinput>-u</userinput> switch or add it to your
  <filename>~/.cvsrc</filename> file.</para>
  
  <para>A third use it to recursive request all the changes between your
  local copy and the copy on the CVS server. This is handy to do before
  running <userinput>cvs update</userinput> to see what exactly has changed
  since the last time you ran the update command.</para>
  
  </sect1>
  
  
  
  
  1.1                  LFS/editor-manual/chapter03/introduction.xml
  
  Index: introduction.xml
  ===================================================================
  <sect1 id="ch03-introduction">
  <title>Introduction</title>
  <?dbhtml filename="introduction.html" dir="chapter03"?>
  
  <para>The man and info pages of CVS are fairly good, but let's list a basic
  set of commands which all editors will use on an almost daily basis. There
  are many more options available than the ones listed here, so you will want
  to read the CVS documentation at some point, and run the
  <userinput>cvs --help</userinput> command. You can also get a basic list
  of CVS commands by running <userinput>cvs --help-commands</userinput></para>
  
  <para>Some commands have two forms, the long and the short. We'll
  list both in the descriptions.</para>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter03/moving.xml
  
  Index: moving.xml
  ===================================================================
  <sect1 id="ch03-moving">
  <title>Moving files</title>
  <?dbhtml filename="moving.html" dir="chapter03"?>
  
  <para>Moving files: One of the (many) complaints against cvs is that
  it has no concept of 1) moving files or 2) versioning directories.  If
  you need to move a file, it's generally better to do it on the server
  manually. The alternative is remove a file using <userinput>cvs
  delete</userinput> then add the new version in the new place with
  <userinput>cvs add</userinput> The downside using this method is that you
  will lose the revision history for that file. However, moving it on the
  server itself won't cause a loss of revision history.</para>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter03/update.xml
  
  Index: update.xml
  ===================================================================
  <sect1 id="ch03-update">
  <title>cvs update/up</title>
  <?dbhtml filename="update.html" dir="chapter04"?>
  
  <para><userinput>cvs update</userinput> or <userinput>cvs
  up</userinput>. This command syncs your local sandbox with the server and
  is probably, along with <userinput>cvs commit</userinput> the command you
  will use most frequently. If you have made local changes, it'll try and merge
  any changes on the server with your changes
  <emphasis>on your machine</emphasis>. You should always do a manual
  <userinput>cvs update</userinput> before trying to commit changes in order
  to check that everything is alright and ready to go (although when you do a
  <userinput>cvs commit</userinput>, it will warn you if there is a
  problem).</para>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter04/bugzilla.xml
  
  Index: bugzilla.xml
  ===================================================================
  <sect1 id="ch04-bugzilla">
  <title>Update bugzilla</title>
  <?dbhtml filename="bugzilla.html" dir="chapter04"?>
  
  <para>The final part of updating the book is to update bugzilla. This is
  usually as easy as going to LFS Bugzilla (<ulink
  url="http://bugs.linuxfromscratch.org"/>), going to the bug and
  choosing Resolve bug, changing resolution to FIXED.  Note that you
  should <emphasis>not</emphasis> then go back and CLOSE the bug.  The
  person who closes the bug should be a different editor who has tested
  that what the bug is about has been fixed. Basically, it's our QA
  process.</para>
  
  <para>A more detailed explanation on how to use Bugzilla can be found
  later. This is just the check-list (ie: don't forget to finish off with
  Bugzilla assuming you already know how to use it).</para>
  
  </sect1>
  
  
  
  
  1.1                  LFS/editor-manual/chapter04/chapter04.xml
  
  Index: chapter04.xml
  ===================================================================
  <chapter id="chapter04">
  <title>Committing Changes - Policy</title>
  <?dbhtml filename="chapter04.html" dir="chapter04"?>
  
  &c4-introduction;
  &c4-test;
  &c4-updateindex;
  &c4-updatechangelog;
  &c4-checkfiles;
  &c4-checkrender;
  &c4-commit;
  &c4-bugzilla;
  
  </chapter>
  
  
  
  
  1.1                  LFS/editor-manual/chapter04/checkfiles.xml
  
  Index: checkfiles.xml
  ===================================================================
  <sect1 id="ch04-checkfiles">
  <title>Check all relevant files have been added and removed</title>
  <?dbhtml filename="checkfiles.html" dir="chapter04"?>
  
  <para>If you are adding files, you need to run a
  <userinput>cvs add</userinput> command on each of them (something like
  <userinput>cvs add chapter06/kernel*.xml</userinput> will work).  A good
  trick if you've only added files (not taken any away) is to run a
  <userinput>cvs up</userinput> which will give an output something like 
  this:</para>
  
  <para><screen>gerard:~/lfs-book$ cvs up
  ? temp/thisfileneedstobeadded
  cvs server: Updating .
  cvs server: Updating appendixa
  [snip]
  cvs server: Updating temp
  A temp/thisfileadded
  R temp/thisfilehasbeendeleted
  M temp/thisfilehasbeenmodified
  U temp/thisfilehasbeenupdatedfromtheserver
  RCS file: /home/cvsroot/LFS/BOOK/temp/thisfilehasconflicts,v
  retrieving revision 1.1
  retrieving revision 1.2
  Merging differences between 1.1 and 1.2 into thisfilehasconflicts
  rcsmerge: warning: conflicts during merge
  cvs server: conflicts found in temp/thisfilehasconflicts
  C temp/thisfilehasconflicts
  RCS file: /home/cvsroot/LFS/BOOK/temp/thisfilehashadchangesmergedin,v
  retrieving revision 1.1
  retrieving revision 1.2
  Merging differences between 1.1 and 1.2 into
  thisfilehashadchangesmergedin
  M temp/thisfilehashadchangesmergedin
  cvs server: Updating template</screen></para>
  
  <para>([snip]'s were added by me, not the server). If you look at the first
  column, you will see various different letters which all mean different
  things.</para>
  
  <para><userinput>?</userinput>: This is what CVS reports when it doesn't
  know what to do with a file.  Generally it means that you've forgotten
  to <userinput>cvs add</userinput> a file to the repository but can also
  just be temporary editor files which CVS doesn't know what to do with.
  If it's just temporary files, don't worry, it won't try and commit them
  when you do a <userinput>cvs ci</userinput> because you haven't added
  them. Instead it'll just leave them alone.</para>
  
  <para><userinput>A</userinput>: This is a file which has been added to
  CVS using <userinput>cvs add</userinput> but has not yet been committed.
  When you're ready to commit it, simply do a
  <userinput>cvs ci</userinput> on it (and don't forget that nearly all cvs
  operations can be performed on as many files at once as you like; indeed,
  if you specify no file, it'll either give you an error (if it doesn't make
  sense; like with <userinput>cvs add</userinput> or
  <userinput>delete</userinput>) or simply perform the action on all files
  from that directory downwards in the tree; for example with
  <userinput>cvs ci</userinput>).</para>
  
  <para><userinput>R</userinput>: This is a file which has been removed
  from CVS using <userinput>cvs delete</userinput> but has not yet been
  committed. The equivalent of 'A' for added files.</para>
  
  <para><userinput>M</userinput>: This is a file which has been modified
  in your local repository and hasn't been checked in. If there have also
  been changes in the remote copy, it means that CVS successfully merged
  them. Even so, if (as in the file thisfilehashadchangesmergedin above)
  changes have been automatically merged, you should look them over to
  check that they make sense. Then, when you're ready, commit.</para>
  
  <para><userinput>U</userinput>: This is a file which was unchanged
  locally but changed remotely. The changes were successfully applied to
  your local copy.  You don't need to commit on this message as you
  haven't made any local changes.</para>
  
  <para><userinput>C</userinput>: This one can be a nasty one to resolve. It
  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 (usually named with .'s and version numbers) and
  sort the conflict out yourself. Due to the nature of the LFS book,
  this doesn't happen very often. But if you make local changes and wait a
  long time to commit them, somebody else may eventually edit that same file
  and commit it before you do. When that happens, these conflicts
  happen.</para>
  
  <para>Once you know why you're getting each symbol, and they're all
  correct, you can proceed to the next step.</para>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter04/checkrender.xml
  
  Index: checkrender.xml
  ===================================================================
  <sect1 id="ch04-checkrender">
  <title>Check that the book renders properly</title>
  <?dbhtml filename="checkrender.html" dir="chapter04"?>
  
  <para>Before commiting any changes, it's important to check that you
  have all the syntax correct and that the book can actually pass through
  <userinput>openjade</userinput> without making it belch.  Instructions
  on how to render the book can be obtained by reading the
  <filename>INSTALL</filename> and <filename>README</filename> files that are
  in the LFS CVS repository. It's generally best to have a script which
  automatically does it all for you. If not better, at least it's easier as
  you don't have to type out the long openjade command all the time.</para>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter04/commit.xml
  
  Index: commit.xml
  ===================================================================
  <sect1 id="ch04-commit">
  <title>Commit it!</title>
  <?dbhtml filename="commit.html" dir="chapter04"?>
  
  <para>Once you are sure that everything renders and that you know which
  files you wish to commit, you're ready. A transaction log of the CVS commit
  will be emailed to the <userinput>lfs-book</userinput> mailinglist so we
  all can see right away what you did. The commit emails contain some basic
  info (log, changes to which files) including a <emphasis>diff -u</emphasis>
  format output.</para>
  
  <para>Before you actually commit, spend two seconds thinking about the
  log you are going to add. As mentioned in the section on CVS
  commands, comments should <emphasis>always</emphasis> be used when
  commiting to CVS. Even if the comment is just 'small typo fix', that'll
  do. Other usual comments are 'update to package-x.y.z' or 'fixed
  installation instructions of package foo'.</para>
  
  <para>To commit, you use the <userinput>cvs commit</userinput> or
  <userinput>cvs ci</userinput> command. A good example of a commit
  command could be:</para>
  
  <para><screen><userinput>cvs ci -m "Fixed typo in chapter 05/bash-inst.xml" \
  index.xml chapter01/changelog.xml chapter05/bash-inst.xml</userinput></screen></para>
  
  <para>If you have only made the changes regarding this package to your tree,
  then you can save time by simply running the following from the root of
  your local LFS sandbox:</para>
  
  <para><screen><userinput>cvs ci -m "Fixed typo in chapter05/bash-inst.xml"</userinput></screen></para>
  
  <para>The first command is more useful when you've modified files you don't
  want to commit at this time, or which require a different log message (for
  example a fix to chapter05/binutils-exp.xml).</para>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter04/introduction.xml
  
  Index: introduction.xml
  ===================================================================
  <sect1 id="ch04-introduction">
  <title>Introduction</title>
  <?dbhtml filename="introduction.html" dir="chapter04"?>
  
  <para>Here is a summary list of things to do before committing changes:</para>
  
  <itemizedlist>
  <listitem><para>Test the instructions you are adding</para></listitem>
  <listitem><para>Update <filename>index.xml</filename> with the new date
  and / or updated entities if necessary.</para></listitem>
  <listitem><para>Update <filename>chapter01/changelog.xml</filename></para></listitem>
  <listitem><para>Check that all relevant files have been <userinput>cvs
  add</userinput>'d or <userinput>remove</userinput>'d.</para></listitem>
  <listitem><para>Check that the book renders properly.</para></listitem>
  <listitem><para>Commit it</para></listitem>
  <listitem><para>Update bugzilla to reflect the changes</para></listitem>
  </itemizedlist>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter04/test.xml
  
  Index: test.xml
  ===================================================================
  <sect1 id="ch04-test">
  <title>Test the instructions</title>
  <?dbhtml filename="test.html" dir="chapter04"?>
  
  <para>This may seem <emphasis>really</emphasis> obvious but it's very easy
  to make a typo in installation command changes which causes the
  installation to break. We've all done it, you'll probably do it too
  eventually. But double check to minimize the chance.</para>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter04/updatechangelog.xml
  
  Index: updatechangelog.xml
  ===================================================================
  <sect1 id="ch04-updatechangelog">
  <title>Update chapter01/changelog.xml</title>
  <?dbhtml filename="updatechangelog.html" dir="chapter04"?>
  
  <para>Changelog updates should <emphasis>always</emphasis> 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'd grow like topsy.</para>
  
  <para>Changelog updates need to be in the following format:
  <screen><listitem><para>Month Day, Year [username]: Chapter -
  Section: What you changed.</para></listitem></screen></para>
  
  <para>Example:
  <screen><listitem><para>May 27th, 2002 [gerard]: Chapter 06 -
  Ncurses: upgraded to ncurses-5.2-2.patch which is smaller than the previous
  one.</para></listitem></screen></para>
  
  <para>Changelog entries are always on top of the previously added changelog
  entry.
  </para>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter04/updatecredits.xml
  
  Index: updatecredits.xml
  ===================================================================
  <sect1 id="ch04-updatecredits">
  <title>Update chapter01/credits.xml</title>
  <?dbhtml filename="updatecredits.html" dir="chapter04"?>
  
  <para>This file contains the list of who wrote what.  We should try and
  keep it up-to-date to be fair to everyone.  Generally this only needs
  altering if new instructions are being added or a new contributor is
  taking over an old set of instructions.  It should be fairly
  self-explanatory as to how it is laid out.  If it isn't, ask!</para>
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter04/updateindex.xml
  
  Index: updateindex.xml
  ===================================================================
  <sect1 id="ch04-updateindex">
  <title>Updating index.xml</title>
  <?dbhtml filename="updateindex.html" dir="chapter04"?>
  
  <para>The following elements should be updated in the
  <filename>index.xml</filename> file whenever <emphasis>any</emphasis> change
  (including small typo fixes) is made:</para>
  
  <para><screen><!ENTITY version "20020429">
  <!ENTITY releasedate "April 29th, 2002"></screen></para>
  
  <para>The two dates must be the same, and the first is in the YYYYMMDD
  format.</para>
  
  <para>Effectively, you'll only do this if you happen to be the first person
  on a particular day who made a change.</para>
  
  </sect1>
  
  
  
  1.1                  LFS/editor-manual/chapter05/addingcomments.xml
  
  Index: addingcomments.xml
  ===================================================================
  <sect1 id="ch05-addingcomments">
  <title>Adding comments</title>
  <?dbhtml filename="addingcomments.html" dir="chapter05"?>
  
  <itemizedlist>
  
  <listitem><para>Go to the bug you want add comments to</para></listitem>
  
  <listitem><para>Add your additional information in the
  <emphasis>Additional Comments</emphasis> text field.</para></listitem>
  
  <listitem><para>As the last step, click on the <emphasis>Commit</emphasis>
  button to commit your changes to the database. A log of this will be sent
  to the lfs-book mailinglist.</para></listitem>
  
  </itemizedlist>
  
  </sect1>
  
  
  
  
  1.1                  LFS/editor-manual/chapter05/chapter05.xml
  
  Index: chapter05.xml
  ===================================================================
  <chapter id="chapter05">
  <title>Using Bugzilla</title>
  <?dbhtml filename="chapter05" dir="chapter05"?>
  
  &c5-introduction;
  &c5-addingcomments;
  &c5-enternewbugs;
  
  </chapter>
  
  
  
  1.1                  LFS/editor-manual/chapter05/enternewbugs.xml
  
  Index: enternewbugs.xml
  ===================================================================
  <sect1 id="ch05-filingbug">
  <title>Enter a new bug</title>
  <?dbhtml filename="enternewbug.html" dir="chapter05"?>
  
  <para>You found a bug, or somebody else found a bug and you decided to add
  it to Bugzilla.</para>
  
  <itemizedlist>
  
  <listitem><para>Go to <ulink
  url="http://bugs.linuxfromscratch.org/enter_bug.cgi"/></para></listitem>
  
  <listitem><para>Select the proper <emphasis>Version</emphasis>. You most
  always will choose the <emphasis>CVS</emphasis> version. It doesn't make
  sense to report a bug against an old version if it's no longer in CVS. If
  it is, then CVS is newer than a previously released stable book version.
  The versions are basically there only for people who don't edit the book
  and who want to report a bug against the book version they
  have.</para></listitem>
  
  <listitem><para>Don't worry about <emphasis>Component, Platform, OS and
  Severity</emphasis> Those aren't used at the moment.</para></listitem>
  
  <listitem><para>Select the <emphasis>Resolution Priority</emphasis>. Use
  your own judgement on how important fixing this bug is. If you're not sure
  just leave the default. Priorities are periodically re-evaluated and
  changed anyways (what may be P5 a month ago may be changed to a P1 now
  because it's finally time to fix it).</para></listitem>
  
  <listitem><para>Select the <emphasis>Initial state</emphasis>. Only select
  <emphasis>UNCONFIRMED</emphasis> if you haven't checked the matter out yet
  and are only suspecting a bug. Otherwise, leave it as
  <emphasis>NEW</emphasis></para></listitem>
  
  <listitem><para>If you don't want to assign yourself to it right away,
  leave the <emphasis>Assigned To</emphasis> field blank. It'll be assigned
  to <emphasis>lfs-book at linuxfromscratch.org</emphasis> then, until a real
  editor changes that to himself.</para></listitem>
  
  <listitem><para>Fill in the other fields as appropriate,
  <emphasis>Summary</emphasis> and <emphasis>Description</emphasis> are
  mandatory.</para></listitem>
  
  <listitem><para>As the last step, click on the <emphasis>Commit</emphasis>
  button to commit your changes to the database. A log of this will be sent
  to the lfs-book mailinglist.</para></listitem>
  
  </itemizedlist>
  
  </sect1>
  
  
  
  
  1.1                  LFS/editor-manual/chapter05/introduction.xml
  
  Index: introduction.xml
  ===================================================================
  <sect1 id="ch05-introduction">
  <title>Introduction</title>
  <?dbhtml filename="introduction.html" dir="chapter05"?>
  
  <para>This chapter covers the things you need to do when you are using
  Bugzilla for entering new bugs into the system, and fixing/updating
  outstanding bugs.</para>
  
  <para>We assume you have already logged into Bugzilla before doing anything
  outlined in the following sections.</para>
  
  </sect1>
  
  
  
-- 
Unsubscribe: send email to listar at linuxfromscratch.org
and put 'unsubscribe lfs-book' in the subject header of the message



More information about the lfs-book mailing list