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

[dww]

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:   dww
 Status:       active

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.




dww