Problem With One of the Main CVS Pages

[Shai Gluskin]

Hi gang,

This is about http://drupal.org/node/320

The title of the page is: *Checking out from the main repository

*The assumption on that page is that you want to check out HEAD. There is
one small section which says, "If you want to check out a specific version
of Drupal..."

I believe the assumption of the page should be opposite, that you want to
check out a specific version of Drupal. That is how you can check out the
latest stable release.

The use-case for checking out HEAD is for core committers or folks testing
patches to core. That is very important. However, I think the vast majority
of people wanting to get their feet wet in CVS (and therefore coming to this
handbook page) want to check out the latest *stable release* in order to
make it easier to upgrade the next time an updated stable release is
deployed.

I'd like to edit the page so that the primary instructions are for checking
out a specific version and the secondary instructions are for folks wanting
to checkout HEAD.

I thought this was a big enough change that I wanted to run it by others.

Thanks,

Shai

[Ryan Cross]

Disagree.

it is very standard practice for people jumping into a new open source
project to want to see HEAD (or trunk or whatever) or for people's first
interest in CVS is to see "what's coming". Most people that are interested
in checking out a specific version (like a stable version) are more advanced
or experienced with CVS already. Someone's first jump into CVS is not going
to be doing so in an effort to make upgrading easier.

My 2 cents at least.

Post by Shai Gluskin
Hi gang,
This is about http://drupal.org/node/320
The title of the page is: *Checking out from the main repository
*The assumption on that page is that you want to check out HEAD. There is
one small section which says, "If you want to check out a specific version
of Drupal..."
I believe the assumption of the page should be opposite, that you want to
check out a specific version of Drupal. That is how you can check out the
latest stable release.
The use-case for checking out HEAD is for core committers or folks testing
patches to core. That is very important. However, I think the vast majority
of people wanting to get their feet wet in CVS (and therefore coming to this
handbook page) want to check out the latest *stable release* in order to
make it easier to upgrade the next time an updated stable release is
deployed.
I'd like to edit the page so that the primary instructions are for checking
out a specific version and the secondary instructions are for folks wanting
to checkout HEAD.
I thought this was a big enough change that I wanted to run it by others.
Thanks,
Shai
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Greg Knaddison - GVS]

Post by Ryan Cross
Disagree.

Disagree.

Post by Ryan Cross
it is very standard practice for people jumping into a new open source
project to want to see HEAD (or trunk or whatever) or for people's first
interest in CVS is to see "what's coming". Most people that are interested
in checking out a specific version (like a stable version) are more advanced
or experienced with CVS already. Someone's first jump into CVS is not going
to be doing so in an effort to make upgrading easier.

Maybe, but this is Drupal. The installer in Drupal7 gets completely
broken on a pretty regular basis, and that's not a new thing - things
like that often happen in HEAD. I agreed with Shai's proposal. I
think it should primarily explain how to check out DRUPAL-6. The only
drawback I can think of for doing that is it will require us to update
that page whenever a new version is released.

Regards,
Greg
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Angela Byron]

Post by Greg Knaddison - GVS

Post by Ryan Cross
it is very standard practice for people jumping into a new open source
project to want to see HEAD (or trunk or whatever) or for people's first
interest in CVS is to see "what's coming". Most people that are interested
in checking out a specific version (like a stable version) are more advanced
or experienced with CVS already. Someone's first jump into CVS is not going
to be doing so in an effort to make upgrading easier.

Maybe, but this is Drupal. The installer in Drupal7 gets completely
broken on a pretty regular basis, and that's not a new thing - things
like that often happen in HEAD.

Hey, hey, hey! Quit spreading FUD! :P

Yes, the installer was broken for four hours last weekend. That's the
first time the installer (or anything else on the major "critical
path", for that matter) has been broken in HEAD since... a really long
time. Thanks to automated testing, anything we have tests for is
guaranteed to continue to stay working, and testing.drupal.org now
ensures that even installer breakage never happens again. :)

That said, I agree with you on everything else. ;) +1 for making this
page conform to user expectations.

-Angie

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Ryan Cross]

Post by Angela Byron

Post by Greg Knaddison - GVS
Maybe, but this is Drupal.

I'm not sure why we feel that Drupal has to be different from any other open
source project

Post by Angela Byron
Hey, hey, hey! Quit spreading FUD! :P
Yes, the installer was broken for four hours last weekend. That's the
first time the installer (or anything else on the major "critical
path", for that matter) has been broken in HEAD since... a really long
time. Thanks to automated testing, anything we have tests for is
guaranteed to continue to stay working, and testing.drupal.org now
ensures that even installer breakage never happens again. :)

As Angie points out, with all the new testing available, I'm not sure why we
*wouldn't* want people focusing on HEAD.

Post by Angela Byron
That said, I agree with you on everything else. ;) +1 for making this
page conform to user expectations.

I'm not sure which side Angie falls on with this comment. I think most
people would expect instructions to check out HEAD. Plus, it is the more
natural first step in terms of CVS (less command parameters, etc).
Additionally, with the instructions for a specific version already available
I would not see any added benefit from reorganizing that page. I think this
is where our non-newbie/non-drupal-outsider bias is coming in.

[Shai Gluskin]

Greg, Ryan, and Documentors,

After reading Ryan and Greg's responses, the solution seems obvious... the
page shouldn't make *any* assumptions or determine priorities for use-cases.
It should be verbose with sections clearly labeled.

-- this is *how* you check out HEAD and this is *why* you'd want to check
out HEAD
-- this is *how* you check out a specific version and this is *why* you'd
want to check out a specific version

The only drawback I can think of for doing that is it will require us to
update that page whenever a new version is released.

I think as long as it is clear that the text you are providing as a sample
is a variable (replace "Drupal-6-6" with the most recent stable release.").

*Point of clarification needed:*
Greg, what you wrote makes me ask a further clarification. It has been my
experience that if you specify "DRUPAL-6" you'll get HEAD for Drupal 6. In
order to get the most recent stable release of Drupal 6, you'd have to
specify like this: DRUPAL-6-6.

Since D-6 is not under active development, it is true that the differences
between the latest stable release and HEAD will be minimal. However,it is
still better to use the stable release rather than HEAD, in my opinion. My
experience has been that if I checkout "DRUPAL-6" --- the admin pages,
update status etc. will show the version as "6.7" when the latest stable
release is 6.6. I find that disconcerting. Also, I don't know how Update
Status would respond when 6.7 actually does get released.

Greg -- am I missing something here?

*Another Point of clarification needed:*
The docs page in question mentions that there might be times when you'd want
to check out a release of Drupal (presumably HEAD) for a *specific date*. It
mentions no use-case. This is my guess: you are testing a patch and the
patch command requires that it be applied to the precise version that the
patch was created against. Given the sometimes slow work of volunteers, it
can easily happen that new versions of HEAD are created before folks have
had a chance to test a patch. Instead of requiring the patch-creater to keep
rolling against a new HEAD, testers can simply patch against a precise
version of HEAD that existed in the past. *Please confirm (or reject) that
I've got the use-case correct here.*

Thanks much,

Shai

On Wed, Nov 19, 2008 at 7:04 PM, Greg Knaddison - GVS <

Post by Ryan Cross
Disagree.

Disagree.

Post by Ryan Cross
it is very standard practice for people jumping into a new open source
project to want to see HEAD (or trunk or whatever) or for people's first
interest in CVS is to see "what's coming". Most people that are

interested

Post by Ryan Cross
in checking out a specific version (like a stable version) are more

advanced

Post by Ryan Cross
or experienced with CVS already. Someone's first jump into CVS is not

going

Post by Ryan Cross
to be doing so in an effort to make upgrading easier.

Maybe, but this is Drupal. The installer in Drupal7 gets completely
broken on a pretty regular basis, and that's not a new thing - things
like that often happen in HEAD. I agreed with Shai's proposal. I
think it should primarily explain how to check out DRUPAL-6. The only
drawback I can think of for doing that is it will require us to update
that page whenever a new version is released.
Regards,
Greg
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Steven Peck]

Why not add all three use cases and examples? One for the HEAD
version of a release (Drupal 6) and another for a specific version
(Drupal 6.6) with the use cases you've just outlined?

That gives three use cases and examples

Development on the next generation
Drupal 7

Testing/bug fix on existing mainline stable branches (which is still
ongoing - see bug tracker)
Drupal 6 HEAD

CVS Pull of current production release for whatever
Drupal 6-6

These are not uncommon use case scenarios in our community and it does
no harm for people to be introduced and grow accustomed to such things
they may not have encountered before.

Steven

Post by Shai Gluskin
Greg, Ryan, and Documentors,
After reading Ryan and Greg's responses, the solution seems obvious... the
page shouldn't make any assumptions or determine priorities for use-cases.
It should be verbose with sections clearly labeled.
-- this is how you check out HEAD and this is why you'd want to check out
HEAD
-- this is how you check out a specific version and this is why you'd want
to check out a specific version

The only drawback I can think of for doing that is it will require us to
update that page whenever a new version is released.

I think as long as it is clear that the text you are providing as a sample
is a variable (replace "Drupal-6-6" with the most recent stable release.").
Greg, what you wrote makes me ask a further clarification. It has been my
experience that if you specify "DRUPAL-6" you'll get HEAD for Drupal 6. In
order to get the most recent stable release of Drupal 6, you'd have to
specify like this: DRUPAL-6-6.
Since D-6 is not under active development, it is true that the differences
between the latest stable release and HEAD will be minimal. However,it is
still better to use the stable release rather than HEAD, in my opinion. My
experience has been that if I checkout "DRUPAL-6" --- the admin pages,
update status etc. will show the version as "6.7" when the latest stable
release is 6.6. I find that disconcerting. Also, I don't know how Update
Status would respond when 6.7 actually does get released.
Greg -- am I missing something here?
The docs page in question mentions that there might be times when you'd want
to check out a release of Drupal (presumably HEAD) for a specific date. It
mentions no use-case. This is my guess: you are testing a patch and the
patch command requires that it be applied to the precise version that the
patch was created against. Given the sometimes slow work of volunteers, it
can easily happen that new versions of HEAD are created before folks have
had a chance to test a patch. Instead of requiring the patch-creater to keep
rolling against a new HEAD, testers can simply patch against a precise
version of HEAD that existed in the past. Please confirm (or reject) that
I've got the use-case correct here.
Thanks much,
Shai
On Wed, Nov 19, 2008 at 7:04 PM, Greg Knaddison - GVS

Post by Ryan Cross
Disagree.

Disagree.

Post by Ryan Cross
it is very standard practice for people jumping into a new open source
project to want to see HEAD (or trunk or whatever) or for people's first
interest in CVS is to see "what's coming". Most people that are interested
in checking out a specific version (like a stable version) are more advanced
or experienced with CVS already. Someone's first jump into CVS is not going
to be doing so in an effort to make upgrading easier.

Maybe, but this is Drupal. The installer in Drupal7 gets completely
broken on a pretty regular basis, and that's not a new thing - things
like that often happen in HEAD. I agreed with Shai's proposal. I
think it should primarily explain how to check out DRUPAL-6. The only
drawback I can think of for doing that is it will require us to update
that page whenever a new version is released.
Regards,
Greg
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Shai Gluskin]

Okay Louie,

I've signed you up for the Haftarah for this Shabbat.

Thanks,

Shai

Steve,
Yes, you've summarized exactly what I intend to do.
Shai

Post by Steven Peck
Why not add all three use cases and examples? One for the HEAD
version of a release (Drupal 6) and another for a specific version
(Drupal 6.6) with the use cases you've just outlined?
That gives three use cases and examples
Development on the next generation
Drupal 7
Testing/bug fix on existing mainline stable branches (which is still
ongoing - see bug tracker)
Drupal 6 HEAD
CVS Pull of current production release for whatever
Drupal 6-6
These are not uncommon use case scenarios in our community and it does
no harm for people to be introduced and grow accustomed to such things
they may not have encountered before.
Steven

Post by Shai Gluskin
Greg, Ryan, and Documentors,
After reading Ryan and Greg's responses, the solution seems obvious...

the

Post by Shai Gluskin
page shouldn't make any assumptions or determine priorities for

use-cases.

Post by Shai Gluskin
It should be verbose with sections clearly labeled.
-- this is how you check out HEAD and this is why you'd want to check

out

Post by Shai Gluskin
HEAD
-- this is how you check out a specific version and this is why you'd

want

Post by Shai Gluskin
to check out a specific version

The only drawback I can think of for doing that is it will require us

to

Post by Shai Gluskin

update that page whenever a new version is released.

I think as long as it is clear that the text you are providing as a

sample

Post by Shai Gluskin
is a variable (replace "Drupal-6-6" with the most recent stable

release.").

Post by Shai Gluskin
Greg, what you wrote makes me ask a further clarification. It has been

my

Post by Shai Gluskin
experience that if you specify "DRUPAL-6" you'll get HEAD for Drupal 6.

In

Post by Shai Gluskin
order to get the most recent stable release of Drupal 6, you'd have to
specify like this: DRUPAL-6-6.
Since D-6 is not under active development, it is true that the

differences

Post by Shai Gluskin
between the latest stable release and HEAD will be minimal. However,it

is

Post by Shai Gluskin
still better to use the stable release rather than HEAD, in my opinion.

My

Post by Shai Gluskin
experience has been that if I checkout "DRUPAL-6" --- the admin pages,
update status etc. will show the version as "6.7" when the latest stable
release is 6.6. I find that disconcerting. Also, I don't know how Update
Status would respond when 6.7 actually does get released.
Greg -- am I missing something here?
The docs page in question mentions that there might be times when you'd

want

Post by Shai Gluskin
to check out a release of Drupal (presumably HEAD) for a specific date.

It

Post by Shai Gluskin
mentions no use-case. This is my guess: you are testing a patch and the
patch command requires that it be applied to the precise version that

the

Post by Shai Gluskin
patch was created against. Given the sometimes slow work of volunteers,

it

Post by Shai Gluskin
can easily happen that new versions of HEAD are created before folks

have

Post by Shai Gluskin
had a chance to test a patch. Instead of requiring the patch-creater to

keep

Post by Shai Gluskin
rolling against a new HEAD, testers can simply patch against a precise
version of HEAD that existed in the past. Please confirm (or reject)

that

Post by Shai Gluskin
I've got the use-case correct here.
Thanks much,
Shai
On Wed, Nov 19, 2008 at 7:04 PM, Greg Knaddison - GVS

Post by Ryan Cross
Disagree.

Disagree.

Post by Ryan Cross
it is very standard practice for people jumping into a new open

source

Post by Shai Gluskin

Post by Ryan Cross
project to want to see HEAD (or trunk or whatever) or for people's

first

Post by Shai Gluskin

Post by Ryan Cross
interest in CVS is to see "what's coming". Most people that are interested
in checking out a specific version (like a stable version) are more advanced
or experienced with CVS already. Someone's first jump into CVS is not going
to be doing so in an effort to make upgrading easier.

Maybe, but this is Drupal. The installer in Drupal7 gets completely
broken on a pretty regular basis, and that's not a new thing - things
like that often happen in HEAD. I agreed with Shai's proposal. I
think it should primarily explain how to check out DRUPAL-6. The only
drawback I can think of for doing that is it will require us to update
that page whenever a new version is released.
Regards,
Greg
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Shai Gluskin]

Steve,

Yes, you've summarized exactly what I intend to do.

Shai

Post by Steven Peck
Why not add all three use cases and examples? One for the HEAD
version of a release (Drupal 6) and another for a specific version
(Drupal 6.6) with the use cases you've just outlined?
That gives three use cases and examples
Development on the next generation
Drupal 7
Testing/bug fix on existing mainline stable branches (which is still
ongoing - see bug tracker)
Drupal 6 HEAD
CVS Pull of current production release for whatever
Drupal 6-6
These are not uncommon use case scenarios in our community and it does
no harm for people to be introduced and grow accustomed to such things
they may not have encountered before.
Steven

Post by Shai Gluskin
Greg, Ryan, and Documentors,
After reading Ryan and Greg's responses, the solution seems obvious...

the

Post by Shai Gluskin
page shouldn't make any assumptions or determine priorities for

use-cases.

Post by Shai Gluskin
It should be verbose with sections clearly labeled.
-- this is how you check out HEAD and this is why you'd want to check out
HEAD
-- this is how you check out a specific version and this is why you'd

want

Post by Shai Gluskin
to check out a specific version

The only drawback I can think of for doing that is it will require us to
update that page whenever a new version is released.

I think as long as it is clear that the text you are providing as a

sample

Post by Shai Gluskin
is a variable (replace "Drupal-6-6" with the most recent stable

release.").

Post by Shai Gluskin
Greg, what you wrote makes me ask a further clarification. It has been my
experience that if you specify "DRUPAL-6" you'll get HEAD for Drupal 6.

In

Post by Shai Gluskin
order to get the most recent stable release of Drupal 6, you'd have to
specify like this: DRUPAL-6-6.
Since D-6 is not under active development, it is true that the

differences

Post by Shai Gluskin
between the latest stable release and HEAD will be minimal. However,it is
still better to use the stable release rather than HEAD, in my opinion.

My

Post by Shai Gluskin
experience has been that if I checkout "DRUPAL-6" --- the admin pages,
update status etc. will show the version as "6.7" when the latest stable
release is 6.6. I find that disconcerting. Also, I don't know how Update
Status would respond when 6.7 actually does get released.
Greg -- am I missing something here?
The docs page in question mentions that there might be times when you'd

want

Post by Shai Gluskin
to check out a release of Drupal (presumably HEAD) for a specific date.

It

Post by Shai Gluskin
mentions no use-case. This is my guess: you are testing a patch and the
patch command requires that it be applied to the precise version that the
patch was created against. Given the sometimes slow work of volunteers,

it

Post by Shai Gluskin
can easily happen that new versions of HEAD are created before folks have
had a chance to test a patch. Instead of requiring the patch-creater to

keep

Post by Shai Gluskin
rolling against a new HEAD, testers can simply patch against a precise
version of HEAD that existed in the past. Please confirm (or reject) that
I've got the use-case correct here.
Thanks much,
Shai
On Wed, Nov 19, 2008 at 7:04 PM, Greg Knaddison - GVS

Post by Ryan Cross
Disagree.

Disagree.

Post by Ryan Cross
it is very standard practice for people jumping into a new open source
project to want to see HEAD (or trunk or whatever) or for people's

first

Post by Shai Gluskin

Post by Ryan Cross
interest in CVS is to see "what's coming". Most people that are interested
in checking out a specific version (like a stable version) are more advanced
or experienced with CVS already. Someone's first jump into CVS is not going
to be doing so in an effort to make upgrading easier.

Maybe, but this is Drupal. The installer in Drupal7 gets completely
broken on a pretty regular basis, and that's not a new thing - things
like that often happen in HEAD. I agreed with Shai's proposal. I
think it should primarily explain how to check out DRUPAL-6. The only
drawback I can think of for doing that is it will require us to update
that page whenever a new version is released.
Regards,
Greg
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Shari]

I thought I would add what someone who doesn't know anything about HEAD
or CVS thought when going to the page...

Reading what is there, I would have assumed it was talking about the
latest unstable release of version 6. Because I didn't know for sure
what HEAD referred to I moved backward, along the breadcrumb, to "Drupal
and CVS", I still wasn't sure if HEAD was referring to 6 or 7. So I
clicked on CVS FAQ it isn't answered there but there is a note: "-
What's "HEAD"? What should I use it for?" as something that needs to be
answered. So then I went back, and clicked on "Drupal CVS branches and
tags" to see if it was explained there. I found "The HEAD branch is
special and is used to refer to the latest development version.," still
doesn't answer if it's 6.7 or 7.x. There was a link for a more detailed
explanation, which I clicked on and got this:

"In /Drupal core/, HEAD is the name given to the version of Drupal core
being worked on by developers right now. Of course, now that core is
only using two digits for the version number (starting with the 5.0
release), there's no longer any ambiguity about what the next version of
core will be called, so the use of "HEAD" to identify a release is no
longer necessary. For example, now that the official 6.0 release of
Drupal core is out, everyone knows that the next version of core under
development will eventually become the 7.x release series, so the
nightly snapshot releases are more properly called "7.x-dev", not "HEAD"."

The 1st part seems to be saying that it would be the next 2 digit core
version which would mean it would be 6.7, but then it says it's 7.x-dev,
so I'm still not sure what HEAD refers to. Is it 6.7 or 7.x?

Also the title, actually doesn't mean anything to me either. Checking
out from the main repository, wouldn't be something I would have any
idea of meaning, and would most likely ignore it. I would suggest
Getting files from the main repository, Downloading from..., Access the ...

I thought I would share my entire process, so you can see why some of
this does indeed need to be made clearer if the intention is for anyone
visiting and wanting to learn, to be able to understand. I know, I don't
know or understand some of the lingo, and am willing to move back, or
attempt to find the information, however as in this case even trying to
find the information left me still not understanding, and if I have to
work harder then this, it's likely to be something I just let go.

Now that I just typed all that, I reread the original post, and noticed
that Shai had placed stable release in italics, this leads me to believe
that 7 is what you get when you dl HEAD. If HEAD is indeed 7, I would
suggest something like this to explain it: Once a version has been
released e.g. 6.0, all further version release under the number 6, are
considered "Stable" releases and not "Development" releases. The HEAD or
development release would be the next /full /number e.g. 7.x

Shari

Post by Shai Gluskin
Hi gang,
This is about http://drupal.org/node/320
The title of the page is: /Checking out from the main repository
/The assumption on that page is that you want to check out HEAD. There
is one small section which says, "If you want to check out a specific
version of Drupal..."
I believe the assumption of the page should be opposite, that you want
to check out a specific version of Drupal. That is how you can check
out the latest stable release.
The use-case for checking out HEAD is for core committers or folks
testing patches to core. That is very important. However, I think the
vast majority of people wanting to get their feet wet in CVS (and
therefore coming to this handbook page) want to check out the latest
/stable release/ in order to make it easier to upgrade the next time
an updated stable release is deployed.
I'd like to edit the page so that the primary instructions are for
checking out a specific version and the secondary instructions are for
folks wanting to checkout HEAD.
I thought this was a big enough change that I wanted to run it by others.
Thanks,
Shai
------------------------------------------------------------------------
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/