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 . It seems to me that this is much more an internal implementation of JSPWiki, that a 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 > > >> > > > > > >
