[development] Docs about Drupal + CVS: reminder and call for help

[Alan Dixon]

Here's my experience, as a module developer who thought he knew CVS
and now uses an unnamed alternative.

1. I don't find the general 'About CVS' stuff helpful, maybe because I
think I understand it. For someone new to revision control systems,
all in all it's a steep learning curve (which is not necessarily a bad
thing). To be clear: I don't think you should remove it, it's just my
experience.

2. I do find the quickstart essential and reread it every time I have
to do anything in CVS with my module(s). Thanks to whoever
wrote/maintains this!

3. I didn't know about the update status page, thanks for pointing out that one.

4. I used to get lost, but now I see all the relevant pages nicely
organized in the handbook.

All in all, it's a brilliant, finely crafted, creative system, and I
congratulate dww and the rest of the folks who have created and
documented this infrastructure for collaboration.

To me, it feels somewhat baroque, or maybe medieval is the right word
- like I'm joining the Knights Templar with a secret handshake. I can
see that it may drive away potential contributors, and maybe that's a
good thing sometimes. My only off-the-cuff suggestion would be maybe
some kind of 'streaming' approach that encourages alternatives when
the going gets rough (hey it's okay if you can't figure it out, maybe
you should use joomla [joke]).

Next time I try to upgrade a module I'll keep better notes - I do
remember some funny CVS messages that I ended up ignoring and hope
weren't fatal. And maybe I'll write up a page called "Notes for people
who use <unnamed alternative>" about all the things that are different
about CVS that keep messing me up (am I going to get away with that?).

 - Alan

On Jan 7, 2008 2:10 PM, Derek Wright <drupal at dwwright.net> wrote:
> Hello world,
>
> I've had a bunch of conversations recently where I had to (re)explain
> aspects of Drupal's usage of CVS, how it fits in with projects and
> releases, etc.  This message is for 2 things: 1) to remind the
> developer community about the existing resources, and 2) to solicit
> input for improvement.
>
> 1) What's there now:
>
> http://drupal.org/handbook/cvs
> The root of the d.o CVS handbooks.  Tons (probably too much) of great
> info.
>
> http://drupal.org/handbook/cvs/quickstart
> An attempt at a very concise summary of the main things you need to
> know to get up to speed quickly.  Lots of even senior Drupal
> developers apparently don't know this page exists, so everyone should
> check it out.
>
> http://drupal.org/node/197584
> "Releases and Update Status" -- a page about how the release system
> interacts with update_status (thanks, GHOP!), including links to the
> talk I gave at BADCamp about this topic.  No, it's not a Lullabot
> podcast, but it's almost as good. ;)
>
>
> 2) Call for help:
>
> I'll be the first to admit that what we have is confusing, and the
> docs aren't ideal.  The problem is that I know all this stuff, so
> it's hard for me to document it well from the perspective of someone
> who doesn't. ;)  So, now's your chance to help make it better:
>
> - What do you think the docs need to be more clear?
>
> - I just started http://drupal.org/handbook/cvs/faq -- what should be
> in it?  See what's there already, and add comments to the page if you
> have other suggestions.
>
> - Other than documentation, what could be done to make all this more
> smooth and effortless?
>
>
> My deepest thanks go out to nancyw and add1sun, who've agreed to
> watch this thread and help wrangle suggestions into concrete
> progress.  My hands are very full getting project* ported to D6 so we
> can upgrade d.o, and other related tasks.
>
> Thanks,
> -Derek (dww)
>
>
> p.s. Warning: if someone replies to this thread with "svn", "git", or
> "bzr", you'll be very sorry. ;) This isn't confusing because of CVS
> itself, it's because revision control in general is confusing if
> you're not used to it.  Drupal's choice of revision control system is
> not up for discussion now (believe me, you'll know when it is).
> Thanks in advance for not wasting everyone's time.
>
>
>



-- 
Alan Dixon, Web Developer
http://alan.g.dixon.googlepages.com/