Improve release management process + docs, and spread the support load.

I think it's a fine idea in principle - in fact, why not revoke and re-license annually. Since (for example) each of the last couple years have seen changes in the appropriate allowed tags, etc.

The downside is that someone needs to make and maintain the test and deal with additional logistical difficulties. Are you allowed to try it more than once? Will the questions change for each person taking the test? What will you do if someone posts publicly an answer key?

Is there an alternative? For example - grant initial CVS access only to the sandbox area - in order to get additional access you must correctly add, branch, and tag some code in the sandbox? Or even a new "sandbox" repo for this purpose that can get "rm -rf *" regularly. That might be handy even for more-experienced users who want to make sure they are doing the right thing.

dww: There's really no law that says that you have to help everybody who has a problem. I suggest being a bit slower about it and let other people try to pick up some of the load.

I very much like the sandbox idea. I am willing to lend a hand coding the challenge code. I imagine we would have a sandbox repo and a sandbox Drupal install too. The challenge looks like this: "commit code, create the Drupal 6 and release beta 1 of your module for Drupal 6". Once done, you submit the release node URL as an answer and via multi db capabilities, your cvs account gets re-approved.

@dww - as chx commented, a new user's ability to correctly commit, branch, tag, and create a release node on the scratch site is a practical test that is probably easier to administer than a "quiz". Then also the appeal/retry policy becomes easier - something like "RTFM, try again next month, and create 2 releases on 2 different branches". i.e. the test becomes a little harder if you botch it the first time.

I like the idea of a practical test, but I also think there should be a practice area that one could use before the test (or at other times, also).

A practice area would be awesome so we can run people through the ropes before they create a mess in the real system. It would be easier to help people and walk them through learning if we know they are only playing on a practice area.

I generally like the idea but I also really don't want to keep people out of Drupal.org. That will promote more "get the files form this alternate repository" which seems like a bad thing to me.

I feel the same way about the security problems. While people who are ignorant of how to write secure code (and I including myself in that group, sometimes) create extra work for the security team it would be a worse situation for some module to end up on a person's personal blog, have that blog's server get hacked and insecure code added to the module which is then downloaded without any md5 fingerprint system.

How about a middle ground: we allow people to upload code as tar.gz files to their project pages and we allow people who fail the security test to get accounts - BUT - the project pages for their projects get a "scarlet letter" on them saying "watch out, this user doesn't know CVS and didn't pass the security test. This may indicate a redcuced ability to provide a high quality module/theme" or something like that. It has the added bonus of letting people who hate CVS to provide modules (/me looks at the themers).

This solution gets rid of the CVS pain for you without creating a great spread of modules to far-flung (and less secure) locations.

I also like the idea for a sandbox-test that gets wiped occasionally. For a lot of people this is their first experience with CVS - they need a practice area.

Revoking everyone's cvs status is a *bad* idea.

Creating a cvs sandbox where people can get walked through the ropes when they demonstrate they need help (ie, they make a mess someone else needs to clean up) is a *great* idea. This way, you could support people who need it, and leave everybody else alone. When the people needing support have received it, then they can have their rights reinstated.

The cvs playpen could also be offered as an option for developers signing up for a cvs account -- perhaps a check box: "Would you like someone from the infrastructure team to go through cvs procedures with you?"

@add1sun: perhaps the dojo could be used as a place to train cvs mentors?

As I see it, it gets down to whether we want to offer support or punishment.

@dww --

What percentage of people with cvs access currently require your personal attention? Is this a policy to address misdeeds by 5% of the people with cvs access? Less? More?

I'd say there's a 4th class of people here: those who aren't intimately familiar with cvs, but who know enough not to make a mess.

I'm all for revoking access for those who cause you extra work. I also think that as long as this is seen as something that is seen as *your* responsibility that you will be stuck fixing the mess. Getting more people familiar with cvs conventions (and one way of doing this is via dojo-led cvs tours, if the dojo is up for it) will mean that there are more people around to fix issues/answer questions as they arise, and that you wouldn't be stuck doing it.

Unfortunately, a quiz/test won't stop people from doing stupid things. If you don't believe me, just think back to how many bad drivers you see on an almost daily basis :)

dww:

When I get like that, I find someone to help out, I let them take care of the day to day stuff, so I can focus on what I want to focus on.

Maybe we should find you someone to help with cvs issues and user issues, let them be the first line and if they can't deal with it, push it up to you.

mlhess are you volunteering then? ;-)

Well, I guess I walked into that one, I could give about 10-15 hours a week, However, I will talk to dww, about it and see his thoughts, I might have some extra people around that I can task with dealing with users issues.

Michael

I'm in support of Derek's (dww) intentions here. As the number of CVS developers grows, the problem will only get worse. I'd prefer to have Derek spend his volunteer time on things that really can't be handled in a simpler way. He has a lot of expertise; let's let him make best use of it. It's to our benefit, as well.

Some anecdotal evidence from someone who contributes, but isn't familiar with CVS (me):

A) "But we don't want to create barriers to people contributing!"
In this case, I think we do. If they can't be bothered to read the existing docs, start "contributing", and then generate a big mess that's difficult to clean up and requires a bunch of extra work from the (already over-strained) d.o admins, did we really gain anything?

(emphasis mine)

I've read the Drupal CVS docs multiple times, they're very useful. Still don't know what I'm doing though. Haven't broken my module CVS repositories yet, but am scared of doing so (or even asking questions) because of this assumption that I'm stupid and didn't 'bother' to read the documentation. Being frightened of a process does not make someone want to learn, it makes them want to run away!

Some more thoughts:

• It's a slippery slope. Next time I'm in #drupal-support and someone appears asking a newbie question, Should I say: why haven't you bothered to read the manual you n00b?! Perhaps we should introduce a test about the concepts behind Drupal before allowing anyone to download it?
• If the users are having problems with a system it's not the users fault. Perhaps energies could be better spent on implementing a system that is better suited to people's needs?
• How is anyone going to learn if they aren't allowed to make mistakes?
• This test might put-off some great coders, it's like the agent that turned-down the Beatles. :)
• Personally, if this goes ahead I'll take the projects I maintain, grab a version control system of my choice (SVN, Bazaar or Git) and maintain the repo myself. Not sure how typical a Drupal contributor I am though! :)

no one is being punished here (except me, for agreeing to answer all these support questions in the first place). everyone is being asked to demonstrate they know WTF they're doing before being given access.

That is a punishment in my opinion. It's very elitist, very Us vs. Them. You are the inner circle, whilst us contributors are just the plebs and peasants!

If CVS is not a viable solution, why not drop it? Instead have a list of modules, with the files hosted on contributor's own Web servers. Then the only maintenance is to unpublish the project node if a link is dead, or the code is not what it purports to be. Either way, if you don't personally feel that you can help any more: don't. Just stop, drop it and have a rest. Is the world going to end because CVS questions don't get answered?

Liam: You make some very valid points, right up until:

If CVS is not a viable solution, why not drop it?

It's not that CVS is not a viable solution; it's that we're currently failing on the 'train CVS users properly'.

Maybe we need a GHOP task to write a tutorial on getting started with Drupal CVS that explains some of the important nuances of CVS. We can learn a lot from a teenager.

There are several things here: CVS itself, how CVS interfaces with the release system, and the transitional nature of the system prior to Drupal 6.

CVS itself has a learning curve, but it was sort of manageable before the release system differentiated between tags and branches, ...etc. This is what creates support issues: how it all ties together and the transition we are in.

So based on that:

The following are bad ideas:
- Revoking access for people who already have it (will delay projects, cause bad feelings, disrupt work, ...etc.)
- Requiring a quiz (that can be gamed, an aftermarket for answers will be on eBay in no time, yes, you can keep changing it, but it is an arms race situation, which is unwinnable)

Good ideas:
- A 10 minute screencast/video, preferrably with different versions (e.g. command line, Eclipse, WinCVS)
- Recruiting more people to help with CVS/release system support issues
- Sandbox for practice on
- Sending a quarterly reminder by email to all CVS commiters with links on how everything works (quickstarts and videos at the top, then the detailed stuff below it)

RE:

Maybe we need a GHOP task to write a tutorial on getting started with Drupal CVS that explains some of the important nuances of CVS. We can learn a lot from a teenager.

http://drupal.org/node/203430 -- looks like it's about done.

This thread points to a real issue, though. Better docs will help, and possibly there could be a bar/hurdle/test/quiz/selfimprovementwidget put in place here, but no matter what structure is set in place, there will always be people who need additional support, and that's okay.

What's broken about the current system is that it seems to lack additional hands to help clean up the mess.

Maybe a process could help; something like:

1. Identify a contrib repo (and in all likelihood, a cvs contributor) who has gotten themselves into a hole.
2. Create an issue for the cleanup;
3. Create an issue for contacting the cvs contributor -- this is similar to what we currently do when a user is engaging in questionable behavior on the forums; ie, zealous postings that border on spam -- this issue could lead to a brief training session, and could possibly be tied to a brief revocation of cvs access

This way, these issues get documented, and more people can help out.

Just wanted to hop in and point out that we do already have a growing library of videos about getting and using CVS (as well as patch) and they are linked to from the appropriate documentation in the handbook. Specifically we do have two videos, one cli, one Tortoise CVS, that show how to do project maintenance. Still room to fill things out more of course but just wanted to point them out in case folks were not aware.

http://drupal.org/node/128758

We can improve the tools and documentation, but I don't think we should put more hurdles in place. We should focus on removing barriers, not on introducing barriers.

The only way to make Drupal scale, is (a) to remove barriers and (b) to avoid fixing problems with human resources. Things should be fault-tolerant and straightforward by design.

The only way to make Drupal scale, is (a) to remove barriers and (b) to avoid fixing problems with human resources.

the problem is, i don't know if those two will really play well together in this scenario.

as one of the few other folks besides dww to spend time cleaning up other people's CVS messes, i believe i have a fairly decent perspective on the amount of valuable admin time that's wasted here.

i'm also afraid i don't see a test as a barrier. people are tested on their qualifications all the time in life. i'm guessing the widespread use of testing to determine a person's qualifications indicates that it is somehow effective ;)

sure, the proposed solutions won't address a), but i do believe they'll address b) to some degree -- and that we need.

It's not that CVS is not a viable solution; it's that we're currently failing on the 'train CVS users properly'.

I don't know, the documentation is pretty good. Maybe it's the way that the whole thing hangs together as kbahey mentioned in #20. Are there ways to simplify (or automate) the causes of the most common requests to the CVS queue?

Looking to the future: perhaps a distributed version control system might be easier to maintain? I was just reading up on a couple of methodologies, in particular the Lieutenant style and Patch Queue style (shown just beneath) look interesting. What I'm hoping (but don't know for sure, perhaps someone could clarify) is that people could be given total power within their own branches, if they mess things up they can also fix them (or even wipe it and start again). There will be no more need for a 'please fix CVS for me' queue, just some documentation explaining how to fix it themselves. If they get really stuck there's the #drupal-support channel. Using a patch queue could be good too: contributors fiddle around with a local branch as much as they like, then they merge via e-mail to a bot which can run some tests on the code. People can't go far wrong with submitting a .patch file via e-mail, and if it's invalid the bot throws it back!

Sorry if I'm going over old ground, or thinking distributed version control is something it's not: just trying to help. :)

At the outset, I want to emphasize/rephrase one of my earlier points: cleaning up the CVS contrib repo is a difficult, and often thankless task, and dww and hunmonk have both done great work supporting this -- both through the ongoing project* work, and through supporting users getting started in CVS.

As Dries and others have pointed out, barriers are a Bad Thing (tm). A test is a barrier; it requires time, for some people -- myself included -- it would require preparation, which involves time. It also involves person hours -- to write, to administer, to maintain.

And with that said, we get to:

people are tested on their qualifications all the time in life. i'm guessing the widespread use of testing to determine a person's qualifications indicates that it is somehow effective ;)

This does not hold true. Most forms of standardized tests have no predictive validity wrt future success, or even an ability to master the subject being tested. The most telling example is the SAT, which has no value as a predictor of success in college, or really anywhere except the SAT. For those with time on your hands, this article from the New Yorker gives an overview. Moreover, recent studies looking at tests as learning tools suggest that practice tests (aka training) can have a connection to better recall on the "real" test when the practice tests were "free recall" -- ie, a test that is time consuming to design and administer. Other forms of practice tests were of limited/no value in improving recall.

So, I'd say that the widespread use of testing has more to do with the convenience of a data point as opposed to an objective measure of learning -- and that's a mistake we should not replicate within the context of an open source project.

@Liam -- there have been a series of discussions re other forms of versioning. Search the development list. We don't need to go there. Please, can we not go there :)

With all that said, here is what I propose:

1. a sandbox for practicing -- this gets wiped clean periodically.
2. a link to the handbook page add1sun linked to ( http://drupal.org/node/128758 ) featured on the cvs app -- perhaps include a link to the cvs cheat sheet as well
3. regular (4x a year?) emails to those with cvs access with links to the docs listed in # 2
4. Create issues for cvs problems -- use the issue queue to connect mentors with people needing support -- I suspect that most people needing help want to do it correctly, but they don't know how, and they don't know who to ask/are afraid to ask
5. More people to help with 4 -- and yes, I'll volunteer to help on this, although admittedly I'll need to hone up on my minimal cvs skills.
6. (and this is a long term goal) automate the entire process so cvs commits/project nodes get created via brain scans :)

I hope in my response here I have made it clear that the time dww and hunmonk have spent cleaning up these issues is valued, and probably un(der)appreciated by large segments of the community -- I think/hope if we create a process where the work required to clean up cvs/train new devs is shared more equitably (or at all) then we can eliminate some of the strain/frustration expressed in this thread.

there have been a series of discussions re other forms of versioning. Search the development list. We don't need to go there. Please, can we not go there :)

I had a funny feeling that might be the case. Searching around I see that there are many other priorities, it is a shame support is taking up so much of important people's time, that would be better spent on making the contributions system better. But surely if these people are already stretched, is the added administration of writing and maintaining a test worth it? Particularly if it has the potential to annoy large numbers of the community.

What are the priorities after Drupal 6 is released? Maybe the top one on the list could be: 'get the version control procedure sorted once and for all', whether that means switching to git, Bazaar, Subversion, or just streamlining the current process so support requests are cut right down can be decided at that time. Then at least there'd be some light at the end of the tunnel for the poor guys doing support work. My apologies if this is presumptuous. :)

Otherwise +1 for bonobo's suggestions.

- Almost none of the problems people have are with CVS per se (although many CVS GUIs tend to hide error messages that the tools I've written generate, which makes things more confusing for end users -- but that's a problem with the GUIs, not CVS itself). Overwhelmingly, people have little or no experience with release management at all or the concept of revision control branches. That's what a quiz would be testing for, and it'd be just as valid in svn, git, bzr, you name it. If anything, switching to git or bzr would make this problem 10 times worse, since distributed version control is 10 time more complicated for people who are new to revision control to understand.

My feeling (totally unsupported by facts, however) is that people are more likely to be familiar with subversion than CVS, unless they have been Drupal contributors who have been using CVS for a while. So a switch to subversion *might* decrease problems to some extent, at least with new contributors, but then there would be the retraining of everyone who's already figured out how to do things with CVS. This decrease in problems might be so small as to be undetectable, however.

And of course, knowing how to use a RCS and knowing how to use it in the way in which d.o expects it to be used are two different things. On my site, which uses subversion, people who are familiar with subversion still have a difficult time at first learning how to use branches and tags in a way that allows them to be used with the project_release.module.

Anyone have anything else concrete to suggest? In what ways can the underlying process or design be made more "fault tolerant and straightforward"?

Actually, now I think about it the CVS integration is impressive, when first committing and creating a release I did think, 'cool!' on more than one occassion. :) There are a few things on the list of future work that will help, allowing people delete their own releases (clean up some of their own messes), for a start.

When a new CVS support request is created, are there directions saying that they should provide the name of the project that's having problems? Maybe a field on the issue creation page? I noticed that you have to ask that almost every time. There could also be a 'before you ask a question: make sure the answer isn't in the FAQ' notice, with a link to the CVS FAQ (when it's completed).

Discourage the use of graphical clients, four reasons:

• developers should be able to do things using textual commands, if times are so bad that you're thinking of introducing quizzes on version control concepts it might be easier to push the idea of using the command line instead;
• hides error messages, therefore only those who make no mistakes should use a graphical client;
• it's actually easier for contributors to use the command line (see below);
• it restricts the choice of version control systems available to the Drupal project as a whole;

@Liam: Again, it's not CVS per se that people are confused about. It's often just as simple a question as "what branch(es) should I commit this code to?". It's not "how do I invoke CVS command foo"? It's "how does revision control work?".

Looking back to what I found useful, this shows the documentation's strength and weakness. There is good information on getting started with CVS, in fact that's almost the only thing I really used in the CVS book. It's great because of being task based, it shows the exact commands entered to get stuff done. Merlin's article (particularly the howto) is also exactly the sort of thing I needed to know: it sums up how a real contributor uses the CVS system. There needs to be more of this sort of thing in my opinion.

In fact, that 'Getting started' page could be split into a book and expanded a little, make it even more task orientated. It should be a step-by-step guide to how a project is created and maintained, with copy and paste CVS commands (hence why it's easier for contributors to use the command line). Maybe, in the fullness of time, instructions for graphical clients could be given, but the ones that suppress error messages could be named and shamed. The rest of the docs are a great theoretical reference, but relating them to an actual project is difficult, so they should be moved to another book and used as a 'learn more' reference.

The FAQ should contain all the questions asked most: 'My changes are going into the wrong version' and such, with step by step instructions on how to fix the problem. For the support request dww linked to for example, there could be a FAQ entry saying:

Why are my changes going to the wrong version?

Every directory you checkout from CVS remembers the branch it was checked out from (called a "sticky tag"). When you're doing CVS operations, you have to be aware of what branch the directory your working in is pointing to. Using the command line, cd to the directory containing the code you're trying to check in, then paste the following into the command line (replacing <insertmodulename> with the name of your module):

cvs status <insertmodulename>.module | grep 'Sticky Tag'

This will output something similar to:

   Sticky Tag:          DRUPAL-5 (branch: 1.74.2)

This means the code in the directory belongs to the DRUPAL-5 branch, however if it shows:

   Sticky Tag:          (none)

Then the code belongs to the HEAD. Note that whenever you make changes to this code, and check them in, the changes will be saved to the the branch shown by the Sticky Tag.

** Link to HOWTO on checking out multiple branches **

All I did here was extract bits of your explanation, even learnt something myself. This surely would have made the support request you linked to a lot easier to answer, if it would have been asked at all. I really believe practical examples are the way forward (based on your own experience of the questions people ask). It could be argued that this won't lead to a full understanding of CVS but: 1. people seem to learn best by accident; 2. the theoretical documentation will remain available; 3. who cares: let's just get people releasing code without breaking everything! :)

Documentation should be tied-in with the CVS test area, in a 'try it yourself' style. Perhaps it could be based around creating and managing an example project. Giving contributors practical experience before uploading their projects to CVS. It's one thing to have a test area, but contributors need to be guided in what to do there; otherwise they'll ignore--or won't know what to do with--it.

What all of this is trying to say is: everything has to obviously link back to the practical realities of managing an actual project, and any learning resources need to be strongly linked together.

I too stand in awe at your answers in that thread, amazing stuff. It's insane that you're spending that amount of time answering questions. I'll be honest about my own ability to contribute documentation up-front: I just don't have the time at the moment. Haven't even documented my own modules, so am not even going to start on Drupal stuff. Hopefully this post disrupts the deafening silence on CVS documentation. I hope it's useful, not contrary. :)

Forgot to answer this earlier:

- If you read the docs, found them very useful, and still don't know what you're doing, why didn't you either a) add comments to the pages you thought weren't clear enough,

Because I prefer to work things out myself. Don't like asking questions unless I have to either, am also not used to being able to comment on documentation. Michelle wrote a good comment though.

b) submit a documentation issue about it

Because I didn't really know that the documentation was at fault, nor did I know there was a documentation queue! Until now I haven't really thought about: 'what is lacking in the documentation?' as I was too busy thinking, 'How do I learn this CVS thingy?' :)

or c) reply to my recent thread on the devel list begging for input on exactly this question: http://lists.drupal.org/pipermail/development/2008-January/028204.html ? It's the deafening silence on threads like that which help make me feel embattled about this topic. :(

Am not signed-up to the developers list, perhaps I should be. :)

I know exactly where you're coming from and exactly how it feels to ask people's opinions and get nothing back. You're not the only one it's happened: ever been at a talk, the speaker says: 'any questions?' and the whole room goes pin-drop silent? :)

And now for something completely different. Here's an example of what I meant by tying the documentation to the CVS test area: http://tryruby.hobix.com/ obviously ours wouldn't need to be that flashy, contributors can use their own terminals, but the premise is the same: the tutorial tells the user what commands to enter and they get a good, practical overview of using CVS.

This is an old issue, and this has been discussed several times already. Closing.