I am always in favor of improving the documentation. The general rule is you never have enough and what you have is never good enough.
Ralph > On Jan 22, 2018, at 12:49 PM, Gary Gregory <garydgreg...@gmail.com> wrote: > > On Mon, Jan 22, 2018 at 12:36 PM, Matt Sicker <boa...@gmail.com> wrote: > >> This whole conversation just reminds me of all the times in the past I >> suggested full modularization of the core API/SPI. I think such an effort >> would make sense in a 3.0 release. >> >> In 2.x, perhaps what we can do is define a stable plugin API based on what >> we already have. Since we're still supporting Java 7, I'd suggest we make >> abstract classes be the stable part of the API since we don't have default >> methods on interfaces here. >> > > At the very least and as a first step, we could make official the > annotations required to build plugins. This would mean a serious effort at > providing better Javadocs. For > example, org.apache.logging.log4j.core.config.plugins.Plugin.deferChildren() > has NO Javadoc. Actually, the first step would be to Javadoc all of the > annotations as best we can, ideally to the point where folks would not need > to go to the site; having examples in the Javadoc you can cut and paste for > example. > > Gary > > >> >> And yes, the GitBox integration thing sounds neat, particularly for code >> review, though that's a separate topic entirely. >> >> On 22 January 2018 at 00:37, Gary Gregory <garydgreg...@gmail.com> wrote: >> >>> On Sun, Jan 21, 2018 at 4:14 PM, Ralph Goers <ralph.go...@dslextreme.com >>> >>> wrote: >>> >>>> I am very much against the idea of a single repo. Yes, you can have >>>> multiple projects in the repo but I am not sure how that can be sanely >>>> released. I much prefer the model that Maven has taken. They are now >>> using >>>> gitbox [1] which seems to allow GitHub to be the primary repo. >>> >>> >>> GitHub is a distracting tangent here IMO. I really like GitHub's code >>> commenting feature, but it should not matter if we use Apache's Git >> hosted >>> repos or GitHub's. So I'm not sure why we are mixing GitHub in the >>> conversation... ;-) >>> >>> Gary >>> >>> >>>> Every Maven plugin is individually released. Scroll down the link below >>> to >>>> the Maven section and you can see all the plugin repos. >>>> >>>> The upside to this is that it are: >>>> 1. It is far easier to perform releases of the individual >>>> components. >>>> 2. It is much easier to accept plugin contributions. >>>> The downsides are: >>>> 1. A page like https://maven.apache.org/plugins/ < >>>> https://maven.apache.org/plugins/> is needed to keep track of the >> plugin >>>> versions. >>>> 2. It could make sense to have log4j-parent and log4j-bom >>>> projects. The first to help keep the builds similar and the second to >>> help >>>> customers pick up the latest versions. >>>> >>>> Ralph >>>> >>>> [1] https://gitbox.apache.org/repos/asf <https://gitbox.apache.org/ >>>> repos/asf> >>>> >>>>> On Jan 21, 2018, at 8:55 AM, Gary Gregory <garydgreg...@gmail.com> >>>> wrote: >>>>> >>>>> Hi All, >>>>> >>>>> I am writing this to in an effort to understand how we can manage and >>>> grow >>>>> Log4j. I use the term 'grow' not in the 'bigger is better' sense but >>> more >>>>> in the maturing sense. >>>>> >>>>> I am prompted to write this by Ralph's comment that log4j-core and >> the >>>> main >>>>> repo is too big and that releases take too long make, partially >>> prompted >>>> by >>>>> my addition of a new module called log4j-jdbc-dbcp2 which currently >>>>> contains one small class with a dependency on Apache Commons DBCP 2. >>>>> >>>>> I would like to express my gratitude at Ralph's efforts to >> revitalized >>>>> Log4j and performing most release management duties. Thank you Ralph! >>>>> >>>>> I can see two main orthogonal issues: >>>>> - The size of the git repo. >>>>> - The size of the log4j-core module. >>>>> >>>>> Ralph has proposed that new modules like log4j-jdbc-dbcp2 be moved to >>>>> another 'plugin' repo. >>>>> >>>>> I really dislike this idea: >>>>> - The plugin repo has never been released. Not that one releases a >> repo >>>> but >>>>> you get the point. >>>>> - How do you keep things in sync between repos and code when we have >> no >>>>> official 'core' SPI. >>>>> >>>>> For my money, we should keep _everything_ in one repo. Good enough >> for >>>>> Google, so good enough for me. What we release out of that repo is a >>>>> different story and what I would like to discuss next. >>>>> >>>>> This is not the same as Maven plugins IMO but the case could be made >>> for >>>> it >>>>> I suppose where a lot/most plugins live in their own repos. It is not >>> the >>>>> same as with Maven IMO because our plugins rely on log4j-core and >> it's >>>>> guts, for which we only make loose compatibility guarantees -- as >>> opposed >>>>> to log4j-core where we are strict(er). Maven OTOH, has a API for >> plugin >>>>> auteurs. >>>>> >>>>> For example, log4j-jdbc-dbcp2 replies on the guts of log4j-core and >> we >>>> have >>>>> no 'official' core SPI, so splitting it off into a separate repo >> would >>>>> greatly increase the risk of it falling out of sync. It is just so >> much >>>>> more easier to maintain when it is all in one repo. >>>>> >>>>> My proposal is to: >>>>> >>>>> - Put everything back into one repo (Chainsaw too?) >>>>> - Define a core SPI for plugin writers where we make some statement >>> about >>>>> BC, more than the casual 'we try not break stuff.' >>>>> - Defining what Log4j project 'components' we have and release based >> on >>>>> that. For example, today, all of the main Log4j repo is one component >>>> with >>>>> many modules. Chainsaw would be another component of the Log4j >> project. >>>>> Maybe we need to redefine components: API, File, JDBC and so on. A >>>>> component can have one of more module >>>>> - Got for there. >>>>> >>>>> Thoughts? Help me flush this out? >>>>> >>>>> Thank you for reading! >>>>> Gary >>>> >>>> >>> >> >> >> >> -- >> Matt Sicker <boa...@gmail.com> >>
