Sorry, part of the mail was incomplete.Corrected & resend:
> Juan, > > Thx for the (long) reply. > It is indeed key to carefully select what will/will-not be added to the > public api. > > Having textToHtml() on the public api make a lot of sense IMO. It will > facilitate plugin authors (existing, new) in quickly building new plugins > just be using the public api's (without needing much in-depth > understanding of the internals of JSPWiki) > > textToHtml() is a pretty stable and "static" function as it converts one > string into another; without dependency on other interfaces in the public > api. > > As "the public "Engine" interface focuses more on the "static" side of the > application" , it could be a good place also to host some other supporting > functions. > But it would probably give a broader role to "Engine" than its initial > purpose. > (maybe we should try to list other "static" functions we'd like to bring > into the public api, to see whether this makes sense) > > I'm not sure whether promoting the RenderingManager to be part of the > public api is a good idea. > It seems to me that this is much more an internal implementation of > JSPWiki, and not a good candidate for the public api. > > (BTW - Note that when pulling in the RenderingManager, it is also needed > to pull in other dependencies (WikiEventListener). Adding additional > complexities fo Plugin writers.) > > > my .02 cent, > > dirk > > > On Tue, Apr 7, 2020 at 9:47 PM Juan Pablo Santos Rodríguez < > juanpablo.san...@gmail.com> wrote: > >> 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 >> > >> >> > > >> > >> >
