Improving the CVS Application documentation

This, http://drupal.org/node/974252#comment-3733746, gives me an idea for another item on the list of checks:

This one is actually 3 questions all on the same subject so would probably be bundled into one page:
i) Do you want to help with an existing module?
ii) Have you created an issue in the module's issue queue requesting co-maintainership?
iii) Has current maintainer has already accepted you as co-maintainer.

Note to self: there are a few more on this page:
http://drupal.org/node/539608

i.e.
Q. Is your code outputting user-submitted content without first passing it through check_plain(), or or theme('placeholder'), or check_markup(), or filter_xss()?

Q.
i) Does your code use the proper database access functions?
ii) Does your code make sure that it doesn't concatenate data directly into SQL queries?

Q. Does your code use t() for all the string literals?

Q. If your code allows users to enter PHP, does it provide a specific permission for users in order to do this?

etc. (there are quite a few more on the referenced page)

Actually, it seems that when Git replaces CVS, the CVS application process will change radically:
http://drupal.org/node/961144

Nonetheless, the validation of a module which conforms to all the good things CVS application checks for will continue:

To create a release you must go through a process basically equivalent to the current CVS application process.

My request to be able to make these changes myself has been declined (http://drupal.org/node/976546).

Please would you folks who do have the authority to change these pages make them.

Hang on one moment...

We are currently having to put resources into telling people to do basic things like run the Coder module against their code, because the documentation is not working. As long as the CVS application process does exist, it would be better to improve the documentation in the way I suggest than keep having to manually test people's modules only to find that they have not even performed a basic step. To fix the documentation is still a better use of resources than all this manual work.

I'd like to add too that I've been working very hard lately going through giving a first review of these applications. I was saying the same thing again and again (e.g. you need to run your module through Coder). I raised this issue because I want to fix the root of the problem. I don't want to waste my time any more on dealing continually with the symptom. Are you going to replace me in this job? I'm certainly not going to do it any more, because I think I've identified the right place to fix it, which is at the cause.

I'd like to ask too, when will Git have fully replaced CVS? If it'll all be done and dusted in 2 weeks, then your argument is a lot stronger than if it's in, say, 2 months.

And also, I'd like to ask, will the replacement of CVS mean the replacement of the versioning system Application Process (whether it's called the "CVS Application Process" or the "Git Application Process")?

Thanks.

I agree that the documentation already reports the points that need to be checked, including suggesting to check the code with the Coder module. I am not suggesting to change that documentation.

I am suggesting to change what happens when people decide they want to follow the application process (by adding intermediate pages to when they click on "Apply for a CVS Account").

So, all of the current carefully worded pages about what is required and needed would not change at all.

To repeat what I said in the original post:

I would propose to add a serious of pre-check pages, which people would go to when the click on "Apply for a CVS account". The first page would (for example) be a "Have you actually got a module ready to submit?" page with explanation of why this is wanted, . At the bottom of the page, would be a "No - please explain" link and a "Yes - Go to next application step" link. On the "No" page would be guidance where to find extra info etc.

The final page in the series would take the user to the current application form page.

To compare the 2 workflows, current and proposed:

Current:
1. User clicks on "Apply for a CVS account"
2. Busy expert has to go through and check and tell them all the basic things they have missed
3. User corrects and reposts
4. Busy expert gives more detailed feedback on more subtle mistakes
5. User corrects and reposts
6. Busy expert approves CVS account

Proposed:
1. User clicks on "Apply for a CVS account"
2. User is shown a serious of pages, each one trying to check that the user has properly read and understood all the requirements. 1 page = 1 common fault attempted to be corrected. For example:
2a. User is shown a "Have you ran Coder against your module?" page. The page includes explanation of why this should be done, where to find the module, etc. The page has at the bottom a "Yes, I have ran Coder against my module" link and a "No" link.
2b. If user clicked "Yes", they are shown a "Have you prepared a description of the features?" page. The page includes explanation, useful links, maybe examples of good descriptions etc.. The page has at the bottom "Yes, I have prepared a description which I will put in the post" and a "No" link.
2c. If user clicks "Yes", they are shown a "Have you prepared a comparison with the existing solutions?" page.
2d. Further pages which should help trap these basic errors can be added.
3. The last step takes the user to the current CVS application page.
4. Busy expert gives detailed feedback on hopefully only subtle mistakes
5. User corrects and reposts
6. Busy expert approves CVS account

Very interesting. There are differences in the detail of our suggestions, but I think that the core idea of what you propose (i.e. a wizard style pre-test to help people submit very well prepared CVS applications) is 100% identical to what I propose.

Some observations:

• the thread you reference was started to try and fix the scary page previously leading into the CVS application:
  

  The first is reading 11K of rules/regulations, most of which enumerates all of the reasons we won't give you a CVS account, rather than thanking people and making them feel good for wanting to contribute back to the project. And if you miss any of the 6-7 concrete guidelines buried in this 11K, BZZZT. Denied.

• your suggestion was considered by webchick as a good one:
  

  Wizard pages...would be nice...

• although wizard pages were seen to be a lot of work, the principal objection to doing the wizard pages was that it would be a distraction from the horrible application page which used to exist:
  

  ...an awful lot of work that will only prolong fixing this critical bug that is currently plaguing our community.

• it was considered as something to consider once the initial page was cleaned up:
  

  Perhaps as a follow-up, though.

It seems therefore that your suggestion was not considered bad at all, simply that it was, at the time, considered a distraction from the urgent and quickly fixed task of "CVS account application requirements are obtuse and discourage contributions".

I think that now that the initial CVS application page cleanup is done, it is a good time to reopen the push for wizard pages.

In terms of consensus, it looks like we already have 3 people who think it is a good idea:

• you, kiamlaluno (you proposed it first)
• me, drupalshrek (I proposed it independently of you)
• web-"Wizard pages...would be nice..."-chick

I think there are 3 steps:

1. gather a little more explicit support for the general principle of wizard pages (are you still in favour?)
2. discuss in rather more detail how they would be done (e.g. whether to use a wizard module to do the pages, what pages to build and in what order, what pages to label required step and what pages to label optional step, etc.)
3. do the work!

There is much to gain, including:

• people applying would be helped to produce a much better application, and also learn step-by-step what makes a good module
• CVS application admins would have less work to do (not needing to repeat for every application: you need to run Coder, use t(), use theme() functions etc.)
• the initial page can ultimately made wonderfully welcoming! e.g. "We are so pleased you want to contribute to Drupal. CLICK HERE to begin your CVS application process!".