We can't release Drupal 7 until this list is all green:


However, until then, having "Needs documentation" issues in the criticals queue makes it hard to filter down to things which are still outstanding in terms of actually being fixed at all. So, when you see a critical issue which is only open due to upgrade documentation, please downgrade it and point here.

NOTE[EDIT]: See below, the tag has changed!


webchick’s picture

If there was such a thing as a super-nuclear-critical status for an issue, this issue would be it. As long as these issues exist in that queue, they are completely invisible to 99.9999% of developers. If we want people to start porting en masse we need to make sure we have documentation to support them.

That said, I support tracking this with a single critical issue, so thanks for doing that.

catch’s picture

Cross-linking to #653074: Review test coverage / outstanding tests before release which is exactly the same thing for 'needs tests'.

webchick’s picture

Issue tags: +Needs Documentation

Just realized this doesn't have the right tag. :P

This is the most important issue in the entire queue to work on, for anyone looking for a high-impact task that as a nice side-benefit helps you learn APIs in advance.

jerdiggity’s picture

D7 pre-release [would-be] critical issues pertaining to documentation (now marked as "normal" instead -- see above).

Can 2 & 3 (and several others) be downgraded since they're either fixed or RTBC? Unless fixed doesn't count as a pending critical issue (though it does show as being "open")... Either way though, I'm sure that the RTBCs count:




(More to be added still...)

catch’s picture

There's no need to change 'fixed', but yes it's fine to knock down RTBC too - the main thing is to get http://drupal.org/project/issues/search/drupal?version[0]=156281&status[... to reflect actual major release blocking bugs as much as possible.

sun.core’s picture

If feel horribly guilty here. But hey, that's caused by an executive decision to either focus on docs or on *more* clean-ups + fixes. Realistically, which one do you choose? :P ;)

plach’s picture

idem :)

naught101’s picture

Would it be possible to make http://drupal.org/update/modules/6/7 editable by the documentation team? There are a bunch of grammatical things that could do with an edit, as well as linking to related issues.

catch’s picture

Someone had changed the format from "filtered HTML" to "documentation team", I changed it to "filtered HTML" so anyone can edit it.

catch’s picture

Priority: Critical » Normal

Per discussion with webchick, demoting this from critical in favour of the 7.0 release checklist: http://drupal.org/project/drupal

andypost’s picture

Really critical to document "presave" for triggers #585868: Triggers/actions need overhaul (part II) - Presave

plach’s picture

skessler’s picture

I will be at that code sprint Friday in Copenhagen and I will work on this.

Sheldon Rampton’s picture

I visited the upgrade documentation page today intending to use it as a guide to updating my D6 module to D7 and discovered that not only is the documentation incomplete, it is also confusing. Incomplete means that information may be is missing, which I can deal with by just making all of the indicated changes and hoping for the best. Confusing means that the documentation forces me to deal with information that is irrelevant and distracting from the actual needs of someone like myself who simply wants to know how to update modules.

For starters, the documentation begins (after informing me of its own incompleteness) with a long list of changes that are apparently related to specific pre-release versions of D7. I can imagine that this list could be useful to someone, but it isn't helpful to someone who is looking for instructions on how to convert 6.x modules to 7.x, which is the purpose that this documentation page is ostensibly supposed to serve.

Here was my thought process as I encountered the documentation page in its current form: I saw the list of version-specific changes and immediately wondered what I was supposed to do with it. Then I had to wonder why some changes were listed repeatedly under different release versions, and not under others. For example, "Permissions have titles (required) and descriptions (optional)" is listed under "UNSTABLE-1 (2008-Sep-30)," "UNSTABLE-2 (2008-Oct-11)" and "UNSTABLE-10 (2009-Nov-2)" but not under any of the other releases, while "Replace drupal_clone() with clone" is listed under "UNSTABLE-1 (2008-Sep-30)" and not under any of the others. My first thought was, does this mean that "Permissions have titles" was a change that only applied to those release versions and not to the others? Does this mean that "Replace drupal_clone" only applied to the first unstable release and that I'm not supposed to actually make that change when updating my module?

After further review, I realized that each change in the documentation is linked to one or more "needs documentation" issues in Drupal core, and the list of version-specific changes enables me to match each issue to the pre-release version of D7 in which that issue arose. In other words, the listing is a sort of meta-documentation, which I'm sure is useful scaffolding to help in building the actual documentation. The problem is, it is getting in the way of the actual documentation that will be relevant to most module developers like myself. That actual only begins after the long list of version-specific changes that I described above. So why does the documentation page first present us with information that we don't need and is confusing? Can we put that information into a separate "D7 API changes by release version" page so it doesn't create that confusion? Or can we at least move that information to the bottom of the current documentation page, so it isn't the first thing thing that people encounter?

The documentation is also a bit unclear when it says that "Rename user tables" has been postponed. Does this mean that this change won't be happening in the upgrade to D7? Or does it mean that this change won't be happening at all in D7, or does it mean that it will be happening but the D7 team just hasn't gotten around to it yet? If I'm trying to update my module, I'd like to know and not just have to assume. And if this is a change that won't be happening in D7, this change shouldn't be listed at all in the D7 documentation.

I realize that the documentation is a work in progress like the rest of the D7 upgrade, so apologies if my tone here is a bit testy. I'm just a lowly contrib module maintainer. I haven't participated in the work that has gone into developing D7 core, and I certainly appreciate all of the work that other people have done on it. However, i think the fact that I haven't participated in building D7 actually makes me the sort of person that this documentation is intended to serve. Right now it seems that the D7 module upgrade documentation does a better job of serving the needs of D7's core developers than it does of serving the needs of the module maintainers who will actually be using it.

jhodgdon’s picture

Component: base system » documentation
Issue tags: -Needs Documentation +Needs Update Documentation

I am changing the tag scheme, because "needs documentation" was being used for all sorts of stuff.

From now on, anything that needs adding to the Update Guide is being tagged "Needs Update Documentation", not "Needs Documentation".

I am also re-tagging the issues in the Needs Update Documentation queue.

There are also a bunch of issues that were never tagged as needs doc/needs update doc. Namely, many issues that were tagged "API Change", then had a patch committed and were marked fixed, but they should have been left at Needs Work and tagged with "Needs Update Documentation".

I also didn't know about this issue, because it should have been in the Documentation component. So moving it there...

Anyway. So there are 3 tasks:

a) Go through the open issues currently tagged with "needs documentation" and change them to "needs update documentation" if what they need is documentation in the theme/module update guide. It would be helpful if the issue has a lot of comments, to add a comment saying exactly what needs to be documented, or point to the comment number where that is stated. And if there is something else that needs documentation, possibly move them into the Documentation component (if it is API doc blocks that need to be written or edited) or file new issues in the Documentation project issue queue (if it is Handbook documentation that needs to be written, aside from the theme/module update guide). In the latter two cases, remove the "Needs documentation" tag, as it's redundant.

b) Go through the issues that are fixed or "closed/fixed" that are tagged with API change, and see if any of them need to be documented in the update guides. If so, add the "needs update documentation" tag to those issues, and change their status back to "needs work".

c) Go through the issues tagged "needs update documentation" and document them in the theme/module update guides.

I am currently working on (a)...

jhodgdon’s picture

I'm nearly finished with going through the Needs Documentation queue.

Link to search now:

rfay’s picture


jhodgdon’s picture

From #16 - task (a) is done. I'm starting on (b).

webchick’s picture

Thanks so much for doing this, Jennifer!

jhodgdon’s picture

Hmmm. I thought I had added a comment here - must have gotten lost.

Anyway. I've finished task (b). "All" that remains is to actually write the update doc for issues tagged "Needs Update Documentation" (see link in #17 for a search).

Going forward, I'll be monitoring the API Change and Needs Documentation issue queues to update status/tags appropriately.

jhodgdon’s picture

Status: Active » Fixed

I am going to go ahead and close this issue. Drupal 7 obviously was released without the update doc being completed. Also, the list at http://drupal.org/project/issues/search/drupal?status[]=Open&issue_tags=... is all green except for 4 issues that are currently marked "needs more information". There's not much point in this issue any more, since the main points were (a) block release (didn't happen) (b) motivate contributors to write update doc (didn't happen) and (c) make sure all issues that had api changes were noted in the docs or at least reopened until they were documented (did happen).

Sheldon Rampton’s picture

I propose demoting un-releasing D7 and tagging it as "still beta after all." That will light a fire under people to take the documentation seriously, and will also help some of the folks who pledged to have their contrib modules ready for D7 release day but didn't actually succeed.

Just joking.

rfay’s picture

Well... D7 *is* still beta after all, isn't it? I don't think it's just the documentation :-) Not joking. Something over 200 major issues. Many of them lost in 8.x.

jhodgdon’s picture

RE #23 - I realize you are making a joke, but I'd just like to say that there are only 4 API changes that I am aware of that haven't been documented in the 6/7 module update guide at this point, as compared to the hundreds that were documented -- which is the real reason I'm marking this "fixed".

rfay’s picture

So incredible that you can catch up with these!

webchick’s picture

jhodgdon++ is right.

Thanks so much for performing this critically necessary but incredibly tedious and oftentimes thankless clean-up work. Let's continue brainstorming on the documentation gate for D8 so that this process doesn't repeat itself ever again.

Sheldon Rampton’s picture


I admire the work that has gone into both developing D7 and the documentation that has been written already, but this documentation on updating is still virtually unusable in its current form. I say this as someone who has upgraded modules from D4.5->4.7, from D4.7->D5, from D5->D6, and most recently from D6->D7. During each previous upgrade, I found that it was pretty straightforward to use the upgrade instructions as a laundry list of things that needed checking and fixing. Here, for example, are the upgrade instructions from D5->D6:


There are 82 items on the list that I needed to review to make sure I had fixed everything. OK, it was kind of a long list, but it was doable.

In the case of the D6->D7 instructions, however, not only is the list much longer (a total of 260 items instead of 82), but the "table of contents" at the top of the list is pointlessly broken out by D7 pre-release version. Moreover, some of the items on the list appear multiple times under different releases, while changes that have NOT been made in D7 are also included, which serves no particular purpose other than to further madden any poor soul who tries to use the documentation as actual assistance in helping to upgrade his or her module.

Before you chastise me for not working on this myself, I acknowledge that point fully. In my defense I can only plead that I've been working 70+ hour weeks and just can't make time to work on this too. However, I did squeeze out the time to upgrade one of my contrib modules to D7, and after struggling to use the upgrade documentation, I finally gave up and simply rewrote my module from scratch, ignoring the update instructions and using api.drupal.org as my primary guide.

There's no point in harping on this, because no one is really to blame, but it is nevertheless a problem. There are tons of D6 modules that have not yet been updated to D7, and many of them are important modules whose absence is making it hard for me to update my existing sites from D6 to D7 and making me hesitant to build new sites in it because so much functionality is still missing. The lack of clear documentation is not the only reason why these updates aren't happening faster, but it's certainly a factor.

webchick’s picture

We're working on this problem over at #648218: Make API changes in Drupal core be nodes.

naught101’s picture

Re: Sheldon's point at #28: Why don't we move the categorical list at http://drupal.org/node/394070 to the top of http://drupal.org/update/modules/6/7, and move the by-release list to a backup node and archive it immediately. It's more or less useless, but would probably be good to keep around if only to make sure nothing is missing from the categorical list (which is excellent, BTW).

Sheldon Rampton’s picture

I agree, the categorical list is a huge improvement over the by-release list. I added a bit of detail and formatting to the paragraph at the beginning which explains the status icons for the Coder Review and Coder Upgrade modules, as well as a link to the Coder project page.

jhodgdon’s picture

#30: The categorical list is not complete, and if you notice, is just a list of titles that has pointers back to the chronological list, so PLEASE don't unpublish or archive the chronological list. If you would like to contribute to finishing the categorical list, that would be helpful. Anything without an [x] on the main list has not been put into the categorical list.

#28 (one small point from your rant) - There is not supposed to be anything in the list that didn't make it into Drupal 7. If you can point out what is there that shouldn't be, we will remove it.

General: We all agree this page is useless as it is. See #649218: new report - equipment usage statistics if you would like to contribute constructively to the work and/or discussion of making it better for next time.

Sheldon Rampton’s picture

jhodgdon: Regarding stuff in the list that didn't make it into Drupal 7, there is a section on the page subheaded "Rename user tables" which begins, "NOTE: This change has been postponed (see issue links below) and is not included in an 'UNSTABLE-n' list above." I assume that this is referring to a change which was intended for D7 but didn't actually occur. I mentioned this awhile BTW in my rant #15.

Regarding the ranting, I hope it isn't taken personally. I fully appreciate that documentation is a difficult and generally thankless task, and I feel bad that I'm not able to volunteer to help with it myself.

Sheldon Rampton’s picture

jhodgdon: Couldn't you just cut the chronological list from the top of http://drupal.org/update/modules/6/7 and paste it into a new "archive" node, and then poste in the categorical list from http://drupal.org/node/394070 to replace it?

jhodgdon’s picture

I realize that you don't, but some people actually find the chronological list useful, for instance if they've been keeping up with d7 development and want to know what has changed since they last checked. Not everyone waits until the release to start working on the new version of their module.

Sheldon Rampton’s picture

Sure, the chronological list is useful to some people (and it was probably more useful when D7 was still under development), but now that D7-1.0 has been released, I think more people will find the categorical list useful than the chronological list.

And even if the chronological list is useful, it still was not clear. Partly this is because the page didn't provide any instructions explaining even that the chronological list is a chronological list. When someone sees a subhead that says something such as, "UNSTABLE-1 (2008-Sep-30)," they won't necessarily know that this refers to a specific D7 version release. Someone could just as easily interpret that subhead to mean, "These are changes that are are highly unstable, so I'd better wait until they are stable before I try to implement them."

I've gone ahead and added an introductory section to the page which hopefully will make this more clear.

I think the section titled "Rename user tables" should simply be deleted from the page, since it refers to changes that were not actually introduced in D7. However, I thought I should hold off on deleting it myself just in case there is some reason of which I am unaware for keeping it.

jhodgdon’s picture

Thanks for the header, that's fine. Please don't edit the rest of the page. I don't know who put it there or why, but I'm loathe to remove it. Normally we do wait until something gets committed to add to this page. You could go comment on the referenced issue if you would like more information...

Anyway, this whole "system" is hopefully going away very very very soon. Please, no more discussion here. Please. Please. Please.

catch’s picture

The user tables change was committed then rolled back - likely when it was rolled back, the people involved did not realise it had already been documented on that page.

jhodgdon’s picture

Offending section is removed.

Status: Fixed » Closed (fixed)
Issue tags: -Needs Update Documentation

Automatically closed -- issue fixed for 2 weeks with no activity.

Anonymous’s picture

Issue summary: View changes

Fixed link to be a clickable link