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:

  1. 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.
  2. remove duplication of info
  3. 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:

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.

Comments

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

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)
Zen’s picture

Zen commented

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

dww’s picture

dww
we/he/they
commented

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!

Zen’s picture

Zen commented

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

add1sun’s picture

add1sun commented

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

dokumori’s picture

dokumori commented
Project: Documentation » Drupal core
Version: » 7.x-dev
Component: Developer Guide » documentation

Changed the component to reflect the new component categorization. See http://drupal.org/node/301443
-dokumori

dokumori’s picture

dokumori commented
Project: Drupal core » Documentation
Version: 7.x-dev »
Component: documentation » Placement and navigation
add1sun’s picture

add1sun commented
Status: Active » Fixed

closing this as finished from that time. new reorgs and docs happening now. :-)

Anonymous’s picture

Anonymous (not verified) commented
Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for two weeks with no activity.