[documentation] [Documentation task] reorganize/fix CVS handbook

Mon Jan 15 13:15:09 UTC 2007

Issue status update for 
http://drupal.org/node/93946
Post a follow up: 
http://drupal.org/project/comments/add/93946

 Project:      Documentation
 Version:      <none>
 Component:    Developer Guide
 Category:     tasks
 Priority:     critical
 Assigned to:  dww
 Reported by:  dww
 Updated by:   add1sun
 Status:       active

Hi all, sepeck marked an issue on reorganizing the Patches section of
the handbook (http://drupal.org/node/109114) as a dup but I don't
believe it is.   Please take a look and let me know what you think.

Thanks
Addi

add1sun

Previous comments:
------------------------------------------------------------------------

Fri, 10 Nov 2006 00:18:43 +0000 : dww

webchick, hunmonk and i just finished fleshing out a fairly
comprehensive reorganization of the CVS-related sections of the
handbook.  this is critical for deploying the new release system ( )
since that makes such heavy use of CVS, and i desperately want our
CVS-docs to be in top-shape for a whole new round of "RTFM!" i'm about
to be shouting regularly. ;)

the guiding principles of this re-org were:

* there are 3 audiences for this book: a) drupal.org CVS account
holders, b) people trying to use CVS to help w/ testing, contribute
patches, etc, but who don't have d.o cvs accounts and c) people trying
to use CVS to deploy drupal code for real websites.
* remove duplication of info
* have everything flow nicely and make sense

there's a fancy editable copy of this outline here:
http://docs.google.com/View?docID=dd27wbzs_0hcztvc

however, just so all the work we just spent isn't lost (and in case
anyone else happens to care to comment) i'm pasting the current (mostly
fixed) draft of the outline here:

* CVS

* Introduction (these sub-bullets will just be parts of a single page,
not subpages):

* Link to good CVS overview tutorial
(http://ximbiot.com/cvs/cvshome/docs/blandy.html)
* Terms and how they apply to Drupal (dww - re-write of
http://drupal.org/node/20219)

* Recommended CVS clients

* Eclipse (all platforms)
* SmartCVS (all platforms)
* TortoiseCVS (Windows)
* ...

* Drupal Repositories

* Main (http://drupal.org/node/320)
* Contributions (http://drupal.org/node/321)

* Layout of contributions repository (modules, themes, translations,
sandbox)

* How Drupal uses branches and tags

* Core
* Contrib

* CVS accounts on drupal.org

* Applying for CVS account
* CVS best practices on drupal.org

* General guidelines for using contrib repo
(http://drupal.org/node/84256)
* Commit messages - history and credit (http://drupal.org/node/52287)
* Sandbox maintenance rules (http://drupal.org/node/773)

* Managing drupal.org project releases with CVS (these sub-bullets will
just be parts of a single page, not subpages):

* Official release tags
* Development snapshots
* Stable branches for a specific version of core
* Development branches
* Strategies for using HEAD effectively

* Troubleshooting (FAQ for whatever we often encounter w/ d.o devels)

* Resolving "sticky tag is not a branch" error
(http://drupal.org/node/57516)

* Using CVS to maintain a Drupal website

* Why you might want to do this (new page -- e.g. as a test site to
keep up with HEAD development, etc, etc)
* Setting up a local CVS repository for customizations to Drupal code
(http://drupal.org/node/5123)

* Other resources

* Infratructure mailing list
* CVS Book: http://cvsbook.red-bean.com
* CVS manual:
http://ximbiot.com/cvs/manual/cvs-1.11.18/cvs_toc.html#SEC_Contents

Orphaned ideas:

* Overview of becoming a Drupal contributor

* Creating a sandbox (show them how to commit basic code)

wherever possible, we're going to (sometimes massively) edit existing
pages instead of just making new ones, so that links from other places
still point to something reasonable.  since 95% of this cleanup doesn't
refer explicitly to the new release system, we're just doing it all on
the live drupal.org handbook, instead of messing with scratch.drupal.org
and duplicating the work.

------------------------------------------------------------------------

Fri, 10 Nov 2006 06:25:38 +0000 : webchick

As an update to this, the restructuring is now done. We've compiled a
TODO list for the remaining items. Here's where we currently stand:

    *   major items: 

          o http://drupal.org/node/20219 (CVS intro) [dww] (mostly
done)
          o http://drupal.org/node/17570 (managing d.o project
releases) 
          o http://drupal.org/node/1002 (how drupal uses branches and
tags)

    *   minor items: 
          o New child page on GUIs/Clients: Command-line CVS (Windows)
= Talking about Cygwin and/or GNUWinutils or whatever it's called.
          o http://drupal.org/node/93951 (CVS accounts landing page)
[webchick]
          o http://drupal.org/node/93958 (troubleshooting landing page)
[webchick]

pages that need comment clean-up:

    * http://drupal.org/node/22296 Eclipse (this whole section)
    * http://drupal.org/node/320 (Main repository)
    * http://drupal.org/node/1002 (How Drupal uses branches and tags)
-- lots of these here. :\
    * http://drupal.org/node/16784 (Adding/modifying a file to the CVS
repository)
    * http://drupal.org/node/17570 (Managing drupal.org project
releases )
    * http://drupal.org/node/57516 (Resolving a "sticky tag is not a
branch" error)

------------------------------------------------------------------------

Fri, 10 Nov 2006 09:23:23 +0000 : Zen

Just a few suggestions:

* Avoid gzip switches everywhere.. or stick all the fancy stuff on a
separate page. This can also apply to the -q switch on one of the pages.
* Avoid spaces between a switch and its argument.. e.g, it should be
"-rDRUPAL-4-6" rather than "-r DRUPAL-4-6". This keeps it consistent
with the -d:pserver switch and also prevents other issues.
* The link "CVS front ends for Windows" on http://drupal.org/node/320
is broken.
* Zilch "checkout from a specific date" on the same page. Rarely
required and another D switch to worry about.
* Move information on obtaining nightly tarballs etc. to a separate
page.
* While I think the switches themselves are reasonably straightforward
enough, what is always confusing is the *order*.. Some switches before
"checkout" and some after etc. etc.
* Publically acknowledge that CVS command line syntax was written by a
dyslexic delinquent on drugs and commiserate with the end user.

hth,
-K

------------------------------------------------------------------------

Fri, 10 Nov 2006 10:09:14 +0000 : dww

mostly good ideas that i support (and one of us will fix ASAP).  i agree
the gzip crap has no place in the default examples, and moving that
(along with the -D stuff) to an "Advanced" page somewhere is probably a
good idea (or just let the eager users RTFM in the main CVS manual if
they're so advanced...)

however...

-1 on the idea of -rDRUPAL-4-6 -- i think that makes it less readable
(especially since we use - for all our tag names, not _). "consistency"
with 1 other arg doesn't seem like a good enough reason for less
readable examples.  unless you elaborate on the "other issues" you're
talking about, i see no reason for this change.

thanks for the input!

------------------------------------------------------------------------

Fri, 10 Nov 2006 14:45:40 +0000 : Zen

I don't know why, but on some boxes, -r[space]branch always checks out
HEAD.. whereas removing the space doesn't.

Perhaps, -d:pserver: can be changed to -d :pserver:.. It appears to
work fine here.

Anyways, I'm not fussed; was just a thought.
-K