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/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.
On Mon, 7 Jan 2008 11:10:10 -0800 Derek Wright <drupal@dwwright.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
2008/1/17, Ivan Sergio Borgonovo <mail@webthatworks.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/handbooks 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.dk@gmail.com> wrote:
2008/1/17, Ivan Sergio Borgonovo <mail@webthatworks.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/handbooks 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
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@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/
On Thu, 17 Jan 2008 10:23:49 -0500 "Alan Dixon" <alan.g.dixon@gmail.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
On Mon, Jan 07, 2008 at 11:10:10AM -0800, Derek Wright wrote:
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.
It would be even quicker if we could get this link in the "Dev references" section of the "Contributor links" block. Is that possible? Can someone put that in there? -c. -- Colan Schwartz Internet Consultant | Openject Consulting | http://www.openject.com/
On Jan 22, 2008, at 11:47 AM, Colan Schwartz wrote:
It would be even quicker if we could get this link in the "Dev references" section of the "Contributor links" block.
Good idea.
Is that possible?
Yes.
Can someone put that in there?
Done. Thanks, -Derek (dww)
participants (5)
-
Alan Dixon -
Colan Schwartz -
Derek Wright -
Frederik 'Freso' S. Olesen -
Ivan Sergio Borgonovo