Upgrading environment to 0.11 does not remove old 0.10 pages

[Jason Winnebeck <jpwasp@…>]

Some pages, for example WikiMacros exist as a "guide" page in 0.10 but in 0.11 does not exist at all. This leaves the page with its old content. While r6980 removed a "broken" link to this page, it still exists and could confuse users.

Some suggested solutions:

• Add code to detect "obsoleted" or removed pages, so that when trac-admin wiki upgrade runs, it checks to see if an unmodified (as of the last time trac had it) page with the old name exists, and if so, delete it.
• Document a list of obsoleted pages so that Trac instance admins can remove them. Provide a script to trac-admin wiki delete the pages. Easier, but requires trac admin to determine.

A long-term thing would be to mark/tag/etc pages that are the Trac pages to let trac-admin be smarter. Right now you can edit them, but wiki upgrade kills the edits (last time I checked this was when upgrading to 0.10).

[osimons]

That is a bit unfortunate, actually. The page has been called WikiMacros forever, but seems that it is now called TracWikiMacros. I don't think we have accounted for this change at all.

As most users will experience this from an upgrade (and new projects won't care either way), the easiest is actually to change the name back before 0.11.0 release.

As for the long-term aspects raised, I sincerly hope that we will remove the pages from the wiki completely and replace it with a new Help system. See TracDev/Proposals/NewHelp for more information about this, and we would appreciate your input on this specification if you have comments.

[Jason Winnebeck <jpwasp@…>]

It looks like a good plan, but I don't really know Python or the Trac internals. I agree with cboos that the need for search is real.

I wonder if you can just have "two wikis" where one is the help wiki. A column in whatever table stores wiki format will partition the table. Then you can use existing code to handle everything. But, the benefit is probably low because you would still want the help: syntax to reference the pages, and it would break plugins and other code that try to select/insert the table directly.

Back to this ticket, I realized this when I filed #7184. I wondered why the page was even renamed, but there still is a WikiMacros page; it just references TracWikiMacros. I would agree to rename the new page back, if it makes sense. An alternative would be to include WikiMacros (and any other page that has ever existed), and for the "removed" page you leave the forward link (as WikiMacros has now) or some other comment saying that the page is obsolete/removed/etc.

[cboos]

Well, my fault, that pages was created as a copy of 0.11/TracMacros (TracWikiMacros@1). I'm OK to reuse the old name, as this will indeed simplify the upgrade.

[Jason Winnebeck <jpwasp@…>]

OK I have made all of the changes to rename the page back to the original, but I cannot modify source:/trunk/contrib/checkwiki.py.

If this is the only page that this happened with, maybe this ticket can be closed? If there are others, maybe a better alternative is just to never remove wiki pages part of the default set, so that the "moved to" page still exists for 0.10 users. Even if we didn't decide to rename, I would still vote for that since there could be links in the user environments to the page that does not get updated, and having out-of-date content could be a bad scenario.

[osimons]

Superb work, Jason!

I have renamed the page in my working copy, and have pulled down all the latest wiki changes ready to do a review and commit to 0.11-stable. I'll close the ticket when that is done.

cboos: I figured I might as well try doing the docs merge this time so I at least know how. Just some questions:

• It would be by far the easiest to review and commit all recent changes (including those from Jason), or would you prefer we isolated them and made two changesets? I can't remember we care that much for keeping docs changes isolated in changesets, do we?
• Whatever is in the default pages that I don't think should be in docs are just removed from the wiki, right. Or reworked somehow. Regardless the idea is that they should stay fully in sync, right?
• We don't note versions of pages we merge to repos, do we? The timestamp on repos and wiki changes is enough to correlate if there ever should be a need to go back?

[cboos]

Replying to osimons:

Superb work, Jason!

I second that, thanks!

I have renamed the page in my working copy, and have pulled down all the latest wiki changes ready to do a review and commit to 0.11-stable. I'll close the ticket when that is done. cboos: I figured I might as well try doing the docs merge this time so I at least know how.

How? Use Mercurial...

I use a branch where I import raw changes from the Wiki and a branch where I import raw changes from t.e.o. Then, when I import new changes from t.e.o, the stuff I previously decided not to merge won't show up again.

You can probably set up a similar workflow using git or any other decent version control system (maybe even with svn 1.5.0?), but I'll describe it for Mercurial in TracProject/DefaultWikiPages#sync.

Just some questions: * It would be by far the easiest to review and commit all recent changes (including those from Jason), or would you prefer we isolated them and made two changesets? I can't remember we care that much for keeping docs changes isolated in changesets, do we?

Well, as usual, the more focused the changes, the better the changesets, but right, if some time has elapsed since the last sync, it can prove difficult to record (hint) the different changes in appropriately grouped changesets...

* Whatever is in the default pages that I don't think should be in docs are just removed from the wiki, right. Or reworked somehow. Regardless the idea is that they should stay fully in sync, right?

No, there are differences, some annotations make only sense on t.e.o.

* We don't note versions of pages we merge to repos, do we? The timestamp on repos and wiki changes is enough to correlate if there ever should be a need to go back?

Yes.

[osimons]

Committed in [7024] for 0.11-stable, and merged to trunk in [7025].

(cboos, I just cherry-picked the changes related to this ticket for now. Thanks for the great how-to on documentation merge - I'll look into that soon.)

[Jason Winnebeck <jpwasp@…>]

I thought I mentioned this before, maybe I forgot or put the comment in another ticket, but in the WikiMacros page, there are a couple of links near the bottom (WikiMacros#Implementation) that are source links. Those will not work in user's environments.

I can't remember if the t/trac prefix is predefined in every environments new InterTrac page; that is a possibility. Another is to put the actual URL in there. Yeah, I hate absolute URL links like everyone else but I'm not sure there is a better solution.

I don't mind making any changes myself, but I wanted to know what the Trac developers' convention is for this problem.

[Jason Winnebeck <jpwasp@…>]

Also, perhaps I will note that when we did this, we will put everyone who upgraded to the 0.11 betas/rc/svn version will have a dangling TracWikiMacros page. I think there are two approaches for this:

1. Leave TracWikiMacros in the wiki page set and have it be a link to WikiMacros. Con: people who upgrade from 0.10 to 0.11 final will have this new page created.
2. Document in TracUpgrade this issue, to say:

If upgrading from 0.11 beta or rc releases, you may wish to delete the TracWikiMacros page, if it was created in a trac-admin wiki upgrade operation. This page is not part of the 0.11 final release.

[cboos]

• the trac InterTrac prefix is defined by default in 0.11, so yes we can use that (WikiMacros@27)
• Ok for solution 2.

[thatch]

did you mean to link to trunk with 0.11 verbage nearby?

Here are 2 simple examples on how to create a Macro with Trac 0.11 have a look at trac:source:trunk/sample-plugins/Timestamp.py

[cboos]

Ah, good point, should be rc1 tag for now...