Alec Thomas wrote:
> ... I know myself how tedious it is upgrading
> plugins to a new API version. It's not "fun" coding, it's just boring.
> The less of this we subject plugin authors to, the more likely it is
> that they will keep working on them.
>
Well, let me first explain the "let's break the API" point of view, in
this specific case.
A lot of macros are playing tricks to get the informations that are now
provided by the formatter (and the formatter.context), so I think it
usually makes sense to _really_ upgrade them.
Also, more and more parts of the Trac API are now directly taking a
context argument, and this can be obtained from the formatter, but not
from the req (well, you could always build a global Context(self.env,
req), but you loose the "real" resource context to which the wiki text
belongs).
That being said, I'm not against adding back support for the
render_macro(req, ...), as there seems to be consensus on that.
The idea is to anticipate the WikiDOM changes (see #4431) and provide a
new API for the macros, in addition to the old render_macro(req, ...)
method, kept for compatibility.
The new API would be:
def parse_macro(parser, name, content):
"""Called after the wiki text containing the call has been
parsed."""
def format_macro(formatter, name, content):
"""Called by the formatter when rendering the parsed wiki text."""
The parser object is not yet defined, but like the formatter, it will
have a .context property and a .source property , most probably also a
.wikidom property, containing the tree of parsed Wiki elements.
The macro_parse method will get called early enough so that the hacks
currently needed for adding CSS files won't be needed anymore.
> Personally, I think the following guidelines would be okay:
>
> - Always try to maintain API compatibility.
> - If an interface must be changed, try to maintain the old interface
> for at least one minor (eg. 0.10 -> 0.11) version change, logging
> deprecation warnings when it's used. Document the API change in
> ApiChanges/<version>
> - If the old interface can't be maintained, document it as such in
> ApiChanges/<version>.
>
The "at least one minor version" rule seems OK to me, as well as the
other guidelines.
We should document that in the
http://trac.edgewall.org/wiki/TracDev/PluginDevelopment page.
> We've discussed this in the past, specifically interface validation. I
> can't really see a reason *not* to add it, and it would definitely help
> plugin authors. Here's a patch implementing some basic checks:
>
> http://swapoff.org/files/interface-check.diff
>
Wow, that's impressive. However I think an admin page about it would be
more effective than a bunch of lines in the log, something like an
additional ''Check Interfaces'' button on the plugins admin page...
-- Christian
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "Trac
Development" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
