Modify

Opened 5 years ago

Closed 2 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 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.

Attachments (1)

WikiMacrosDocumentation.png (36.4 KB) - added by Ryan J Ollos 2 years ago.

Download all attachments as: .zip

Change History (9)

comment:1 Changed 5 years ago by Steffen Hoffmann

Keywords: migration naming added

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.

comment:2 Changed 5 years ago by 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 ;)

comment:3 Changed 5 years ago by 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.

comment:4 Changed 5 years ago by Ryan J Ollos

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 5 years ago by Ryan J Ollos

Status: newassigned

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.

comment:6 Changed 4 years ago by Ryan J Ollos

Status: assignednew

Changed 2 years ago by Ryan J Ollos

Attachment: WikiMacrosDocumentation.png added

comment:7 Changed 2 years ago by Ryan J Ollos

Status: newaccepted

Documentation in Trac 1.0.6:

comment:8 Changed 2 years ago by Ryan J Ollos

Resolution: fixed
Status: acceptedclosed

Modify Ticket

Change Properties
Set your email in Preferences
Action
as closed The owner will remain Ryan J Ollos.
The resolution will be deleted.

Add Comment


E-mail address and name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.