Docs about Drupal + CVS: reminder and call for help

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/hand
book/cvs
The root of the d.o CVS handbooks.  Tons (probably too much)
of great  
info.

http://drup
al.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.

On Mon, 7 Jan 2008 11:10:10 -0800
Derek Wright <drupaldwwright.net> wrote:

> - What do you think the docs need to be more clear?

I've read all the docs quickly... it may sound surprising
but what is
not clear is putting in order the steps of the whole
process.

This is my understanding of what you've to do:

* proposing a patch
- co cvs HEAD
- look around if something doesn't work or can be improved
(testing
on your local copy or picking up from queue issue)
- modify
- diff
- open an issue
- wait it is approved
- update your local copy checking for conflict
- check if your patch still work
- wait...

* reviewing a patch
- co cvs HEAD
- find something nice in the issue queue
- examine the patch, eventually modify it
- apply it
- check it
- comment on issue queue
- wait
- update your local copy
- check if patch still work
- wait...


Are there any other tools that can help in the process (on
drupal
website)?

What if you'd like to take care of several issues at the
same time
and you're even doing experiment with core?
Are there any more suggestions to build up a dev
environment?

What if I'd like to keep everything under *my* rcs (whatever
it
is) so you could have my own tag/branch/whatever over the
checkedout
HEAD? (I don't mean drupal have to use my rcs... just I'd
like to
keep using one on top where I can commit).

Any further good suggestion to streamline building up,
cleaning
patching?

thx

-- 
Ivan Sergio Borgonovo
http://www.webthatworks.it

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 <drupaldwwright.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/hand
book/cvs
> The root of the d.o CVS handbooks.  Tons (probably too
much) of great
> info.
>
> http://drup
al.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.di
xon.googlepages.com/

On Thu, 17 Jan 2008 10:23:49 -0500
"Alan Dixon" <alan.g.dixongmail.com> wrote:

> 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.

I think previous exposure to any rcs should be a
prerequisite to
anyone contributing to drupal code (core or contrib).

> 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!

a quickstart is useful to know where stuff are and where
they are
placed or to do the initial co.
In case someone doesn't know cvs but you know any other rcs
and you'd
like to have something to test on quickly, without learning
how to
build up its own cvs repo.

But I'd hide all the details so that the overall process is
clearer.
What I mean is that every dev should already know what a rcs
is but
not every developer may know how things are reviewed etc...
in drupal
and what are the characteristic tools drupal dev community
has.

> 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?).

As I wrote in previous post I'd be very interested in any
experience
about building up a dev environment to follow core dev and
that as
a bonus may work nicely with <unnamed alternative>.

-- 
Ivan Sergio Borgonovo
http://www.webthatworks.it

2008/1/17, Ivan Sergio Borgonovo <mailwebthatworks.it>:
>Are there any more suggestions to build up a dev
environment?

http://drupal.org/node/
147786 - can also be found as "Setting up a
development environment" on http://drupal.org/handboo
ks in the
"Developing for Drupal" section.

-- 
Frederik 'Freso' S. Olesen <http://freso.dk/>

On Fri, 18 Jan 2008 21:11:40 +0100
"Frederik 'Freso' S. Olesen" <freso.dkgmail.com> wrote:

> 2008/1/17, Ivan Sergio Borgonovo <mailwebthatworks.it>:
> >Are there any more suggestions to build up a dev
environment?
> 
> http://drupal.org/node/
147786 - can also be found as "Setting up a
> development environment" on http://drupal.org/handboo
ks in the
> "Developing for Drupal" section.

OK... more than the one that are in the handbook.

I'd like to streamline the patch review in core and be able
to have
an independent rcs. I'm not complaining about the fact that
drupal is
not using my rcs... I just would like to follow what I do to
core.

Then I'd like to know how others made it FAST to test
patches... not
the actual review, but the process of having a pool of patch
file and
decide which one have to be applied (to see if any
interaction for
example), deal with DB versions, testing (simpletest),
benchmarking... etc...

thx

-- 
Ivan Sergio Borgonovo
http://www.webthatworks.it