HOWTO: Accessing re-organized Fedora Docs CVS

[Paul W. Frields]

On Tue, 2005-05-10 at 14:17 -0700, Karsten Wade wrote:
> On Tue, 2005-05-10 at 15:56 -0500, Tommy Reynolds wrote:
> > Greetings, Folks!
> > 
> > To make life simpler, we have reorganized the CVS setup for Fedora
> > Docs.  Previously, there was one big "module" called "fedora-docs".
> 
> s/\"module\"/module/
> 
> As per style guidelines, putting quotes around it removes confidence
> 
> > You checked that out of CVS and you had the all the documents from
> > the entire project.  While you could check out just the part you were
> > interested in, doing so was clumsy.  Adding a new document was
> > equally awkward.
> > 
> > With the CVS changes now in place, each document forms its own CVS
> > module and can be checked out individually.  Everything that used to
> > be in the "fedora-docs/" directory is now a top-level module.
> > 
> > 1) To see which modules exist (assuming that your $CVSROOT
> >    environment variable is properly set): 
> > 
> > 	cvs co -c
> > 
> > 2) How do you access an existing document?
> > 
> >    First, create a working directory.  A "fedora-docs/" directory
> >    isn't created automatically, so make:
> >    
> >    	a) yourself a playpen; and then
> > 	b) get the overhead doc modules; and then
> > 	c) and then get the document you want.
> s/c) and then/c)/
> 
> >    Here is now it goes together:
> > 
> >    	$ mkdir my-docs
> > 	$ cd my-docs
> > 	$ cvs co docs-setup
> > 	$ cvs co developer-guide
> > 
> >    Note that the "docs-setup" actually gets three modules for you:
> >    "common", "stylesheet-images", and "xsl".  You need these for any
> >    document you visit.
> 
> How can we make it so that doing a 'cvs up' to a module will make also
> grab the latest from the docs-setup group?

This is my only beef with the current setup.  Look at the
CVSROOT/modules file for Extras and you will see one way to solve this
problem.  Their way grabs common code and moves it *under* the module
directory using a line like this:

module-name		module-dir &common-module

We probably don't want that since it would mean having to re-code all
the docs.  We want the common stuff to sit on the same directory level
as the checked out dir.  That would mean doing something like this:

xsl			xsl
common			common
stylesheet-images	stylesheet-images
css			css
scripts			scripts

shared			xsl common stylesheet-images css scripts

my-module		my-module shared


Let's keep in mind the usability aspect.  When someone does a "cvs up,"
they should receive any updates to css, xsl, etc.  The method above
assures that, and knocks out the requirement to separately download
supporting stuff.  By diverting all the supporting modules into
"shared," any changes to anything *in* "shared" (including adding
another dir later) will automatically come down to people running "cvs
up".  Is there a reason this is not acceptable?

> >    Since each document you get from CVS can share a single "common/",
> >    "stylesheet-images/" and "xsl/" directory, you only need to do
> >    this once regardless of how many documents you work on
> >    simultaneously.
> 
> If it's automagically included, can we drop even the first cvs co docs-
> setup?

Yes, see above.

> > 3) How do I begin a new document?
> > 
> >    Much the same was as you do an existing document.  You still need
> >    the "docs-setup" module, described in the previous section.
> >    Create a new directory for your new document and away you go.  A
> >    good technique is to use an existing document as a model:
> > 
> >    	$ mkdir my-new-document
> >    	$ cd my-new-document
> >    	$ cvs co docs-setup
> >    	$ cvs co -d my-material example-tutorial
> >    	$ rm -rf my-material/CVS
> > 
> >    Be sure to remove the CVS directory from your new document's
> >    working area ("my-material/CVS" in our example) because your
> >    document has not been added to the Fedora CVS system yet.
> 
> Ideally, we want a docs-skel module.  Maybe note that we are working on
> that.

We should be able to accomplish this with a script included in the
shared stuff.

> > 4) How do I get my document into the Fedora CVS system?
> > 
> >    Sign up for CVS access!
> > 
> >    If you have followed the instructions above, you can add your
> >    document to the Fedora CVS easily. Rename your working directory,
> >    just to be safe, import your document into CVS, and the check out
> >    the "official" verion of your document.
> > 
> >    Continuing our previous example:
> > 
> > 	$ mv my-material my-material-orig
> > 	$ cd my-material-orig
> > 	$ cvs import my-material <my-name> "initial"
> > 	$ cd ..
> > 	$ cvs co my-material
> > 
> >    Notice that we renamed the working copy to "my-material-orig", and
> >    then imported that using the "real" name of "my-material": this is
> >    the new module name for your document.  Compare its contents with
> >    that of your original "my-material-orig" directory to ensure its
> >    correctness.  Feel free to delete your "my-material-orig"
> >    directory whenever you wish or keep it forever - your choice.
> > 
> >    The Fedora CVS administrator will add an entry into the official
> >    "modules" listing for you, so you should be see your new document
> >    in the "cvs co -c" listing very soon.
> 
> Okay, that sounds good.  I'm personally OK with there being a final
> check with the CVS admin(s) before it goes live.


-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-dsco-list/attachments/20050510/b168ff2f/attachment.sig>