Opened 13 years ago
Closed 9 years ago
#9906 closed enhancement (fixed)
Macro name should be CamelCased
Reported by: | Ryan J Ollos | Owned by: | Ryan J Ollos |
---|---|---|---|
Priority: | normal | Component: | PlantUmlMacro |
Severity: | normal | Keywords: | migration naming |
Cc: | Steffen Hoffmann, Álvaro Iradier, Adrian Fritz | Trac Release: | 0.11 |
Description
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
andPlantUml
. 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 allowPlantUML
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.
Attachments (1)
Change History (9)
comment:1 Changed 13 years ago by
Keywords: | migration naming added |
---|
comment:2 Changed 13 years ago by
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 ;)
comment:3 Changed 13 years ago by
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.
comment:4 Changed 13 years ago by
Cc: | Adrian Fritz added |
---|
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.
comment:5 Changed 12 years ago by
Status: | new → assigned |
---|
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.
comment:6 Changed 11 years ago by
Status: | assigned → new |
---|
Changed 9 years ago by
Attachment: | WikiMacrosDocumentation.png added |
---|
comment:8 Changed 9 years ago by
Resolution: | → fixed |
---|---|
Status: | accepted → closed |
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:And I happen to have learned to appreciate it myself.