Hi Dirk, I've to say I've got mixed feelings about adding the method to the Engine (but not to add it somewhere else on the public API). On one hand, if it helps with backwards compatibility I wouldn't mind putting that shortcut on the Engine, or maybe only on the WikiEngine. However once in the API, it would mean that, to remove it, we should release a major version, so instead of moving it away we'd perpetuate it in the public API in a place not so well suited for it (in this case, for this method, let me ellaborate in a bit)..
On the other hand, having to explicit .getManager(RenderingManager.class) on wherever (plugin, filter, etc.) explicits a dependency between the "wherever" and the rendering manager which I think is ok, as it clearly depicts expectations on what is needed by the "wherever", be it on the public API or not. What would be the reason of having that method on the public API instead of having to go through the getManager(..) method? The only thing coming to mind is that being on the public API would mean plugins, filters, etc, using it would have the certainty of still keep working through every minor release. If that's the reasoning, I'd better promote the RenderingManager interface (or maybe only parts of it) to the public API. The Engine as is right now is more focused on the "static" side of the application: providing dependencies, configuration properties, the associated servlet context, etc. In this case, textToHtml seems nearer to me to rendering procedures, so having that method on a new interface on the o.a.w.api.engine package, and then have the RenderingManager extend from it would be ok for me. And the same with other operations on other managers /operations that are common enough. The public API by no means is closed, we can add as many classes / interfaces as we deem necessary, its only that we must have extra care, as once a new class / method / etc. in there is released, if it ends up being ina bad place or a bad decission, it is going to be very difficult to get rid of it (i.e. a major release). Said that and re-reading the public API document + the versioning proposal, I'd like to emphasize that having to code against non-public APIs doesn't mean an extension (or whatever) will probably stop working on next minor. The policy for breaking changes should be the same as we've doing: only if there isn't a sensible workaround; f.ex, prefer overloading a method instead of changing its signature. And removing a class / method on the scope of a minor release should be done like some releases after announcing, perhaps announcing and waiting a couple of years or something like that? We've always tried to be as nice as possible for custom extensions, having the public API shouldn't mean we are going to stop being nice.. This isn't expressed on the public API or versioning proposal pages, but should be, somehow. @everybody, how could this be phrased? (apologies on the large e-mail, been a tough day at work with too much overthinking; hope I haven't digressed too much / have been able to express myself clear..) best regards, juan pablo On Mon, Apr 6, 2020 at 10:54 PM Dirk Frederickx <dirk.frederi...@gmail.com> wrote: > Juan, > > When converting one of the plugins to the latest api; I noticed that . > textToHTML is not available on the public api. > I needed to do something like: > > m_context.getEngine().getManager(RenderingManager.class).textToHTML(... > > iso > > m_context.getEngine().textToHTML(... > > As the textToHtml is IMO a common function used by plugin writers; I would > be useful to have that available in the public api. > > WDYT? > > dirk > > On Mon, Apr 6, 2020 at 10:47 PM Dirk Frederickx <dirk.frederi...@gmail.com > > > wrote: > > > Juan, > > > > Excellent work done on the api & documentation ! > > And tx for the report too. > > > > > > dirk > > > > On Sun, Apr 5, 2020 at 9:10 PM Juan Pablo Santos Rodríguez < > > juanpablo.san...@gmail.com> wrote: > > > >> Hi, > >> > >> below is the draft for next board report, I intend to send no more later > >> than next Wednesday. As usual, any edits, comments, etc. are more than > >> welcome. > >> > >> > >> best regards, > >> juan pablo > >> > >> > >> > >> > ============================================================================= > >> > >> ## Description: > >> The mission of JSPWiki is the creation and maintenance of software > related > >> to > >> Leading open source WikiWiki engine, feature-rich and built around > >> standard > >> JEE components (Java, servlets, JSP). > >> > >> ## Issues: > >> There are no issues requiring board attention. > >> > >> ## Membership Data: > >> Apache JSPWiki was founded 2013-07-17 (7 years ago) > >> There are currently 16 committers and 11 PMC members in this project. > >> The Committer-to-PMC ratio is roughly 4:3. > >> > >> Community changes, past quarter: > >> - No new PMC members. Last addition was Dave Koelmeyer on 2016-04-06. > >> - No new committers. Last addition was Dave Koelmeyer on 2016-04-06. > >> > >> ## Project Activity: > >> This quarter's project activity has revolved mostly around the following > >> items > >> * The refactor of WikiEngine, one of the core classes of JSPWiki > >> (JSPWIKI-120) > >> * The development of a public API for JSPWiki's custom extensions > >> (JSPWIKI-303) > >> * Other bugfixes and improvements > >> > >> Because of two first, we missed our release train stop this quarter, as > in > >> the > >> moment of releasing the master branch, it wasn't backwards compatible > with > >> current 3rd party extensions. We should be able to release next quarter, > >> though. > >> > >> The development of the public API also allowed us to add the possibility > >> of > >> including custom managers on the Wiki Engine (JSPWIKI-806) and the > ability > >> of > >> swapping core JSPWiki classes (WikiContext, WikiEngine, WikiPage, etc.) > >> with > >> custom ones through an SPI, bringing up JSPWiki pluggability another > step > >> up. > >> > >> ## Community Health: > >> There is enough oversight, with questions getting answered on MLs. The > >> public > >> API sparkled a conversation on how / when to break backwards > >> compatibility, > >> which ended up on specifying /clarifying our versioning proposal [#1]. > >> > >> We received one security report this quarter, but ended up rejecting it. > >> > >> One pull request merged into master, with 3 people committing into > master. > >> > >> In order to foster / attract contributors, we also had an overhaul of > >> documentation related to different ways of extending / customizing > >> JSPWiki: > >> - How to write plugins [#2] > >> - How to write filters [#3] > >> - How to write page providers [#4] > >> - Starting point for developing custom extensions [#5] > >> - JSPWiki's public API [#6] > >> - Adding / improving translations [#7], [#8] > >> > >> [#1] https://jspwiki-wiki.apache.org/Wiki.jsp?page=VersioningProposal > >> [#2 < > https://jspwiki-wiki.apache.org/Wiki.jsp?page=VersioningProposal[#2>] > >> https://jspwiki-wiki.apache.org/Wiki.jsp?page=HowToWriteAPlugin > >> [#3 <https://jspwiki-wiki.apache.org/Wiki.jsp?page=HowToWriteAPlugin[#3 > >] > >> https://jspwiki-wiki.apache.org/Wiki.jsp?page=HowToWriteAFilter > >> [#4 <https://jspwiki-wiki.apache.org/Wiki.jsp?page=HowToWriteAFilter[#4 > >] > >> https://jspwiki-wiki.apache.org/Wiki.jsp?page=HowToWriteAPageProvider > >> [#5 > >> < > https://jspwiki-wiki.apache.org/Wiki.jsp?page=HowToWriteAPageProvider[#5> > >> ] > >> > >> > https://jspwiki-wiki.apache.org/Wiki.jsp?page=StartingPointForCustomExtensions > >> [#6 > >> < > https://jspwiki-wiki.apache.org/Wiki.jsp?page=StartingPointForCustomExtensions[#6 > >] > >> https://jspwiki-wiki.apache.org/Wiki.jsp?page=JSPWikiPublicAPI > >> [#7 <https://jspwiki-wiki.apache.org/Wiki.jsp?page=JSPWikiPublicAPI[#7 > >] > >> https://jspwiki-wiki.apache.org/Wiki.jsp?page=HowToI18n > >> [#8] https://jspwiki.apache.org/development/i18n.html > >> > > >
