[documentation] A would-be developer requests "CVS for Dummies"

[puregin]

On 19-Jan-2006, at 4:26 PM, Laura Scott wrote:

> I try to be as much a part of the Drupal community as I can. I've  
> been contributing php snippets, offering support comments in the  
> forums and filing issues whenever I discover them. I've commented  
> on handbook pages to clarify things or answer questions when I could.
>
> Now I'd really like to get my CVS account working so that I can  
> actually contribute themes. However, CVS completely mystifies me.

     Hi Laura,

    Love the washing machine size
printer picture.  Brings back some
memories of hacking code on a teletype.
Yes, I kid you not.  Surprisingly, CVS
is not much younger :)

    I think that documenting how to work with
CVS is outside of the scope of Drupal
documentation.   However, here's a crack
at de-mystification.

(There's a number of good
tutorials on the web.   I've included
a pointer to one which I hope will
apply to your situation.)

       CVS seems complicated at first, but it boils
down to just a couple of basic commands:

checkout  - get a working copy of the code from the
                      repository

update - update your working
         copy with changes posted
         to the CVS repository.  Do this
         periodically to 'keep up with head'.
         Note: if your server is
         running from Drupal CVS Head code,
         you need to 'update' your Drupal site
         each time you do a CVS 'update'.

diff - display the difference between the
          working copy and the repository copy
          (usually after you've modified the working
          copy).   This is how you create patches

patch - not part of CVS, but is used to take
         other people's patches (for testing, e.g.)
         and use them to modify (patch) files.

The idea is that you have a working (scratch)
copy of the code (because you've checked
it out of the repository).  You periodically
run 'update' to bring changes to the repository
down to your working copy.   You can hack
on your working copy, knowing that you can
always delete everything to get back to
your starting point.   Suppose you manage
to fix a bug (say a one-line change
caused by incorrect use of quotes) in file
foo.php.

      You then do

cvs diff -u -F^f foo.php > foo.patch

This computes the difference between
your working version of foo and the
'head' version on the repository, and
sends the output to a file foo.patch,
that you can upload to drupal.org
in your resolution of an issue.

If you look at the file foo.patch with
a text editor, you'll see it's basically
the line you changed, with a couple of
lines of context to let the patch program
(and human readers) figure out what
changes to make to head to get
your fixed version of foo.php.



Since Drupal CVS is read-only (until you get a
CVS contributions account), many of the other
commands don't apply.

     Since you're working on MacOS X, the following
may help

    http://developer.apple.com/internet/opensource/cvsoverview.html

     Ignore the first section, up to the heading
"Creating working copies of a project".

     When you read the section on "Using CVS
across a network", see also

     http://drupal.org/node/320

which has the details for Drupal.org's repositories.

Note - this assumes you're happy with the command
line. Personally, IMO, it's easier than using a GUI.
I think it's better for learning, because you can see
what's going on. YMMV :)

     The  following Wiki is probably as good a source
of documentation as any for in-depth coverage,
after you get through the basics.

http://ximbiot.com/cvs/wiki/index.php?title=Main_Page



>
> My story: Before my iMac crashed, I managed to follow the handbook  
> instructions for CVL and log in and download about 10% of the CVS  
> projects before it all just stopped. (I got projects from A-C.) I  
> had no idea what went wrong. And while I could point my BBEdit to  
> the local CVS folder I had set up, I had no idea how it all  
> integrated.
>
> Now, with the iMac in the shop getting a brain transplant, I'm on  
> my powerbook, starting over. I have OSX Tiger. I have CVL  
> installed. I'm not sure about the developer tools requirements, but  
> I can figure that out.
>
> Back to the point: But what I need -- and what I am asking for here  
> with great humility and earnestness -- is a good, basic overview of  
> what the hell CVS is and how it works. I don't want just nuts-and- 
> bolts, though that would help. But what I need is the big picture  
> -- a flow chart, an introduction to the concepts that makes it all  
> fit together.
>
> Aside: I never understood geometry until I took calculus, where my  
> professor took us through the circle diagrams of what sine, cosine  
> and tangent were about. Suddenly all the "rules of thumb" added up  
> and it made sense. This is the kind of big picture I'm asking for  
> here.
>
> The request: If someone who feels up to the task could devote an  
> hour or two to composing a good, basic overview of CVS and its  
> concepts, I believe not only would I benefit, but many many people  
> who have been blocked by the CVS requirement, and thus are not  
> contributing as much as they might, could benefit as well.
>
> And thus the Drupal development community would benefit.
>
> Not all of us took computer programming when CVS existed. (For me,  
> I took computer programming when printers smaller than washing  
> machines were dot-matrix, when it was when it was a radical act to  
> write a paper on computer -- the university mainframe where you had  
> to code all your page formatting in-line like hand-coding html  
> today. I won't volunteer a year, thank you.) Just a good clear  
> picture that could help the grokking of how CVS works would be  
> immensely helpful to me and, I suspect, many others.
>
> A humble suggestion/request from Laura. Thank you.
>
> -- 
> Laura Scott
> laura at pingv.com
> pingVision
> rare pattern
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/