Macro name should be CamelCased

[Ryan J Ollos]

The macro should probably be renamed from PlantUML to PlantUml, since CamelCased macro names are the generally accepted standard for Trac.

The macro name change has the possibility to break compatibility for existing users. A couple of ways to address this are:

• Allow both PlantUML and PlantUml. The downside is that prior to 0.12 the documentation would be displayed for each on the WikiMacros page, which is messy. In 0.12 and later, the documentation would be displayed once, and show one of the two allowed names as an alias.
• Make PlantUml the default, and allow PlantUML as an alias with an option to disable it.
• Make the hard-switchover at a major version num, and suggest to users that the WikiRenamePlugin can be used to change existing macro invokation if they wish to upgrade.

The ideal would be if we could allow PlantUML to be a valid macro name, but hide it from the WikiMacros page. That way the WikiMacros page would stay clean, and nothing would be broken for existing users. Maybe that is a worthwhile Trac feature request.

Maybe I'm just making too big of deal about this and should leave it as is. For now, I'm opening this ticket to request inputs, and I'll let it sit for a while before taking any action.

[Steffen Hoffmann]

Hey, another topic for fictional (at least by now) best-practice wiki pages.

This is a similar pattern for a number of wiki macro providing plugins, you thinking of Stats macro in WikiStatsPlugin. Because it's so easy to advertise one, but support one or more alternative invocations, even with different feature sets, if you insist, I'd always vote for a combination of the 2nd and 3rd option. This is the Trac way:

• provide a new, better API as upcoming default,
• retain backwards-compatibility/graceful degradation,
• add cool, most-wanted improvements only to new API,
• drop old API after one last fat warning.

And I happen to have learned to appreciate it myself.

[Ryan J Ollos]

Yeah, that sounds like a good way to make the transition. If I proceed with the rename, I'll do as you suggest.

I've an idea for a Trac feature request which would aid with Trac project lifecycle management: allow installed macros to be marked as deprecated by an administrator. The feature would be available on the plugins panel of WebAdmin. Marking an installed macro as deprecated would hide its documentation from the WikiMacros page, and a notification would be displayed when a user edited a page that used a deprecated macro. Further, maybe we also allow for the administrator to add an explanation and suggest an alternate macro. Perhaps I'll get around to working on that someday ;)

[Steffen Hoffmann]

Yes, perhaps need another life to fulfill all those own wishes...

Your idea is very reasonable. I happen to do this right now for TOC --> PageOutline. Using the TracSearch, but if there were more active wiki authors, this warn+suggest would help to roll gradually migrations as a joint effort. And have such things like reference for new macro syntax right in view. Nice.

[Ryan J Ollos]

Since this is a WikiProcessor, and the convention for wiki processors seems to be all lowercase (see WikiProcessors#AvailableProcessors), perhaps we should add plantuml as a valid name for the macro.

[Ryan J Ollos]

In [11637] (#7053):

The Trac convention is to use camelcase names for macro calls and lowercase names for WikiProcessors, therefore PlantUml and plantuml have been added as valid casings. However, PlantUML is still a valid casing, retained for backwards compatibility.

[Ryan J Ollos]

Documentation in Trac 1.0.6: