port cvs.module to releases-as-nodes

new patch with the following changes:

1. now use -- as the delimiter between the core API part of branch/tag names, instead of the dreaded _
2. we call the 2 module-specifc digits of the version number major.patch to make core.
3. added some more //TODO comments
4. if we're selecting a tag, we shouldn't present the option to upload the file, since we'll want the tarball automatically attached to the node once the packaging script completes.

new patch:

• moves d.o-specific hacks into cvs_local.inc
• fixed some bugs in cvs_get_version_from_tag():
  • need to pass in the $project object for core-specific logic
  • have to tell the diff between DRUPAL-4-7 branch and DRUPAL-5-0 release tag
  • a little bit more empty() vs. isset() badness dealing with 0 values...
• branches and tags are now sorted nicely and grouped together in the drop-down when selecting the tag on the release node form.

TODO:

1. need to actually populate the version # fields correctly based on the tag (not just print out the right thing in the drop-down to select the tag). ;)
2. really need to make the release node add form a multi-page, so you select project on the 1st page (if not already in the URL), then select the tag on page 2, then fill in everything else (where you can see but not edit the version #s, etc) on page 3...

i took a 1st stab at 2-page form for first selecting the tag, then everything else, when adding a release. that failed. then i got a lot of help from eaton and chx, and i got closer, but it's still broken. however, i'm putting a patch here so others (namely merlinofchaos) can play with this and try to help me get it working...

yay! fixed the 2-page form badness (thanks to chx, with additional help from merlin and eaton)

new patch:

• 2-page form is working. ;)
• 'disabled' form elements don't show up in $_POST, we need 'readonly', instead...
• removed the cvs_project_release_form_validate() function we're not using at all
• on page 2, the version string is now only 30 chars wide (in anticipation of having it on the same line with the tag, but that can wait).
• other minor changes to match the latest releases-as-nodes patch (http://drupal.org/files/issues/release_as_node.patch_12.txt)

TODO:

1. still need to handle the 2nd page for if you select TRUNK as the tag
2. if you edit an existing release node, the form still needs lots of help
3. need to properly set the "rebuild" flag when a branch is selected...
4. we're currently using 'x' as the patch level version when we're building from from a branch. however, patch is a number in the DB schema, not a string, so even though the version string and title are right, the patch is actually stored as a 0 in this case. maybe we should set it to NULL in this case...

new patch:

• renamed all occurances of "super" with "API" to be more reasonable and clear. so, it's now the "API major version", "version_api_major", etc.
• inside project_release_db_save() if we've got a non-numeric value for version_patch, just unset it and leave it as a NULL in the DB (e.g. for "4.7.x-dev" core releases).

new patch that handles the TRUNK special case. if you select 'TRUNK' as the tag on page 1, you go to another page to fill in the version info before you get to the final page to actually submit. sounds simple, but it's a big diff in the code. ;)

TODO:

1. the validation stuff isn't quite working right -- if you leave all fields blank on the TRUNK version page, you get sent back to the same page without any good feedback as to why.
2. the required property on the body field isn't really working correctly -- it's marked as requried but that's only in pre_render(), so it's not *really* required. :(
3. still haven't worked on the version of the form if you edit an existing release

new patch:

• fix validation weirdness with the body field, so that it really is required at the right times
• changes to keep up with http://drupal.org/files/issues/release_as_node.patch_16.txt from http://drupal.org/node/83339#comment-143685 in terms of the fieldset and new version-number validation goodness
• added a few more doxygen comments about some of the treachery with this form.

• during release node edits, give project admins the ability to change the branch (if it's a branch in the first place). for non admins, we at least show the value of the branch...
• slight cleanup of the form_alter() code: $release was basically dead code, and we don't set pre_render() unless we have to.
• removed some now-stale TODO comments and code
• changes to keep up with the version element fieldset's current location in $form.

new patch with massively improved UI for drupal.org (all in cvs_local.inc, so it's not polluting the regular case for non-d.o sites). a few general features:

• after further investigation of cvs docs, "HEAD" really is a magical "branch name" you can use to refer to the trunk. there's only 1, and that's the common, expected use. i give up on this semantic thing, and admit i was basically wrong (cvs therefore has no consistent, good name for refering to the "end of a branch", but whatever). so, all occurances of "TRUNK" have been replaced with "HEAD".
• sets the system weight for cvs.module to be 3, so it comes after project and everything else and can therefore definitely clean up anything that's been inserted into the form until we're ready for it.

now, for the d.o-specific goodness:

• if the user selected 'HEAD' on page 1, page 2 now hides the "API major" and "API minor" elements, and instead presents a "Drupal core compatibility" selector with pre-filled values.
• added some more callbacks for local customization (cvs_local_alter_project_release_form(), cvs_local_version_is_valid(), and cvs_local_project_release_form_pre_render()).
• fixed a bug in cvs_get_version_from_tag() that screwed up setting the version_extra field properly based on a cvs tag. also, added a _cvs_get_extra() method to help with this.

i'll post 3 screenshots in the next 3 followups so y'all can see the new UI in action... ;)

page 1: select the tag

page 2: (optional) if the tag you selected was 'HEAD', you have to fill in version info manually

page 3: once you've properly filled in page 2, or if you selected a tag with the release info already in it on page 1, you land on the final page, that you can actually preview/submit. the "version string" field is read-only, and the "CVS tag" only has 1 option, so you can't change those at this point. all you can do is fill in the description, and specify any other optional junk you can do on a node form.

thanks for the encouragement, webchick. ;)

however, after further testing, this "Drupal core compatibility" selector is still a little buggy. :(

TODO:
1) if you choose a tag on page 1 (not HEAD), the core-compat selector shows up on the final page, even though we don't need it. this is serious, since this is the common case...

2) if you select 'HEAD' on page 1, and on page 2 select a compatibility but then delete one of the pre-filled values (e.g. patch-level) and leave it blank, when you get sent back to page 2 to fix the patch-level, the core compatibility selector is gone and you just get the text fields for API major/minor again. this is worth fixing, but it's a pretty obscure case, so it's not as important as #1...

*sigh* it seems my work here is never done...

new patch with big changes (hopefully for the better). instead of all this hard-coded "API version" crap, i decided to just make that stuff an automatically-created taxonomy. see http://drupal.org/node/83339#comment-144908 for more info.

• remove all references to api_(major|minor)
• adds real N-page goodness to the autogenerated taxonomy (if in use).
• it's even smart enough to hide any *other* taxonomy selectors until the final page. ;)
• once you land on the final page, there's only the selected compatibility as an option (i.e., you can't change it once you land on the last page, since the version string has already been determined on page 2)
• rips out all the crufty, not-really-working api_selector stuff from the previous patch

forgot to mention that the previous patch fixes TODO #2 from comment #14, but TODO #1 is still a problem (though it should be easier to fix now). furthermore, the cvs_local.inc stuff is getting a little confused with tags like "DRUPAL-5--1-0", and it's not recognizing that should go with "5.x"...

new patch fixes both of the bugs mentioned in the previous comment:

• cvs_local.inc properly associates tag names to the right taxonomy term, for both "DRUPAL-4-7*" and "DRUPAL-5*" kinds of tags.
• if the api compatibility is known on page 1 via the tag, when we land on the final page, the compatibility selector only has that option and it's selected by default.

TODO: nothing? i think this one actually needs review. ;) however, it's totally dependent on http://drupal.org/node/83339 which still needs work, so i'm not changing the status just yet...

minor cosmetic changes to the release form UI: once we land on the final page, we group the cvs tag and version string fields into a fieldset that a) floats them together to take less space and b) adds a description about how they can't be modified at this stage. also works when editing an existing release. finally, set the weight of this fieldset to -4, not -10, so that the title (-5) is always at the top.

i realized that i had left some debugging behavior in here. the old version always added an option 'HEAD' under the tag selector, even if you already had a release pointing to HEAD. once i took that out, it revealed the lame usability of trying to add a release on a project without any available tags. so:

• only present 'HEAD' as a choice if there's no HEAD release already.
• if there are no available tags, print a more helpful message and turn the 'Next' button into 'Retry'
• also, fixed a bug where we were still trying to validate the version form elements when you submitted a release from a tag.

update to cvs_local_version_is_valid() that takes advantage of the new project_release_exists() method from http://drupal.org/node/83339#comment-145292 to prevent advancing past the version selection page (only shown if you selected HEAD) if you choose values that would lead to 2 releases with the same version identification.

fixed a weird bug for when project admins try to edit a release node that's from a tag, not a branch. previously, we ended up generating an empty array of options for the "CVS tag" field, but now we include any tags that don't have current releases. plus, we always re-include the existing tag as an option for the admin in this case. it's pretty obscure, but it'd sure screw things up on d.o for the project admins. ;)

new patch:

• always set the api compatibility taxonomy term, even for core releases.
• initial bugfix for cvs_local_alter_project_release_form(), which is trying to add site-specific default values for major, patch, and extra. we now only attempt to add a default if there's not already one there. however, this is still a little buggy, and things get saved with a "dev" as the extra, even if you clear it out yourself. :(

i emailed chx and eaton about it, but we haven't had a chance to conquer it just yet. but, that's the only thing holding this up...

the FAPI crap for trying to set defaults for major, patch and extra when we're adding a release from "HEAD" is just not working right, chx/eaton aren't around, and i don't care enough to spend infinite time on this. so, i ripped out the defaults, and just added a site-specific description for the fieldset when you're adding/editing a release pointing at HEAD. that's good enough for now...

so, i think this is hereby ready for review. of course, it depends on the latest patch from http://drupal.org/node/83339 (currently, http://drupal.org/files/issues/release_as_node.patch_27.txt) and all of the above should be applied against a fresh DRUPAL-4-7 checkout.

a few minor TODO items from IRC feedback:

1. the 1st page of the node/add/project_release form (once cvs-ified) should include more explaination/help on the difference between releases from tags and from branches. either as text on the page, or possibly even on the "Branches" and "Tags" label inside the drop-down.
2. on the last page, we should make the "Release identification" fieldset collapsible (but not collapsed) to be consistently formatted w/ the rest of the page.

a few more TODO items from IRC and #83339

1. the default choice for the compatibility selector shouldn't be "None", it should be "-----" or "[select one]" or something...
2. the version string shouldn't be a read-only textfield on the final page of the node add form. instead, we should store the real value we care about in a #type = hidden (so it shows up in POST), and then make display-only fields that can do anything we want visually with (#type = item, disabled select boxes, etc, etc).

new, possibly final version of this patch before it's RTBC:

• much more consistent formatting and use of fieldsets in the forms for adding and editing releases.
• renamed "CVS tag" on the first page to "CVS identifier", and thereafter, it's either "CVS tag" or "CVS branch" depending on what you picked.
• removed a final spot where we were automatically adding 'HEAD' as a choice to a list of possible branches -- we only want HEAD as an option if there are no releases already pointing to it.

1 minor item that needs fixing: we want to number from -1.0 on the default stable branch (e.g. DRUPAL-4-7), not -0.0. this has small implications for cvs_local.inc.

speaking of which, when i commit this to the repo, i'm going to rename cvs_local.inc to cvs_local_drupal_org.inc, so it's not used by default unless someone goes out of their way to move it into place...

just committed everything from this issue into the DRUPAL-4-7--2 branch of cvslog. new changes will either just be committed directly to that branch, or posted as patches against the end of that branch, not as complete patches against DRUPAL-4-7 anymore...

after a brief discussion on IRC, i decided to commit cvs_local.inc as cvs_local.example.inc, so that it's disabled by default, and sites have to go out of their way to rename it and edit it for their needs if they want to... however, this is trivial to use on d.o -- we just add a symlink in our local workspace and we're done.

just committed the fix for using 1.0-dev for the version on each stable branch as revision 1.1.2.10 of cvs_local.example.inc on the DRUPAL-4-7--2 branch. for example, if you add a new release pointing to the "DRUPAL-5" branch, it'll assume the version number you want is "5.x-1.0-dev"...

ideally, this would all be reviewed before it goes live on d.o:

cvs co -r DRUPAL-4-7 contributions/modules/cvslog
cd contributions/modules/cvslog
cvs diff -uN -r DRUPAL-4-7 -r DRUPAL-4-7--2 > full.dif

whoops, sorry, i pasted the wrong cvs checkout command above. should be:

cvs co -r DRUPAL-4-7--2 contributions/modules/cvslog
cd contributions/modules/cvslog
cvs diff -uN -r DRUPAL-4-7 -r DRUPAL-4-7--2 > full.dif

(you need to checkout a copy from DRUPAL-4-7--2 to get the cvs_local.example.inc file, too).

as with http://drupal.org/node/83339 everything is committed to DRUPAL-4-7--2 branch, and deployed on scratch.drupal.org (http://drupal.org/node/90436). at this point, it looks like this isn't really going to get any more reviews, so i'm marking it fixed. of course, installing on drupal.org is a separate question...