As you say the docs on branches are not updated in any principled way. Extracting the Javadoc from a matrix of branch builds in a automated way for publishing up to the website would be feasible. We can add this to the build website Jenkins job.
On the other hand, this thread’s topic, a support matrix, would need to be updated by hand whenever a change of consequence is backported. We can expect that committers backporting a change breaking old dependencies won’t know about or recall the branch support matrixes. History teaches us they might not even be aware the change breaks support. The RM won’t catch it with the default build. We would need a matrix of compatibility test jobs to catch the cases that fall through the cracks. > On Jan 9, 2022, at 1:15 AM, Sean Busbey <bus...@apache.org> wrote: > > We already publish version specific reference guides as a part of our > binary tarballs. My understanding is that's a big part of why they're > still in the main source repository; that we get docs built as a part > of our assembly. > > e.g. just picking a 2.4 release I have handy: > > (base) sbusbey@seans-mbp ~ % tar tzf Downloads/hbase-2.4.8-bin.tar.gz| > grep pdf > hbase-2.4.8/docs/apache_hbase_reference_guide.pdf > (base) sbusbey@seans-mbp ~ % tar tzf Downloads/hbase-2.4.8-bin.tar.gz| > grep book.html > hbase-2.4.8/docs/book.html > > Historically these do get maintained for each minor version. My > understanding is that the diligence on backporting across both > contributors to docs and release managers has varied considerably over > time. > > If we're only going to have one version of the docs, then we should > break the docs out of the main repo entirely so that we can simplify > their generation. > > IIRC we have only gone through the trouble of publishing to the > website version specific API docs / ref guides for release lines that > made it to be the "stable" branch. > >> On Sat, Jan 8, 2022 at 9:37 AM 张铎(Duo Zhang) <palomino...@gmail.com> wrote: >> >> I agree with Andrew that maybe it is beyond our ability to maintain >> ref guides for different release lines and keep them all in sync... >> >> What about this, we just make the ref guide for the master branch in >> sync, which contains all release lines. We will still remove >> information of the EOL releases as needed, to keep the ref guide >> clean, but as said in the title, less aggressive. >> And when we decide to EOL a release line, we copy the ref guide of the >> current master branch to the specific branch, and generate the ref >> guide for that release line for the last time. >> In this way the release manager does not need to always think of >> keeping the ref guide in sync, we all just need to consider the master >> one, only one extra work needs to be done when EOLing a release line. >> >> WDYT? >> >> Thanks. >> >> Andrew Purtell <apurt...@apache.org> 于2022年1月8日周六 07:16写道： >>> >>> There are some challenges with respect to keeping multiple versions of the >>> documentation around. Each minor release needs a new version? Each RM >>> managing one or more code line(s) needs to update trunk docs and also >>> backport to branch docs (or not, depending)? There's been a JIRA open >>> forever for a 2.4 version of the book and honestly I haven't found time to >>> do it, because it seems both low priority and nontrivial, and there's never >>> enough time for everything... although that may be a personal failing. >>> >>>> On Fri, Jan 7, 2022 at 9:05 AM Sean Busbey <bus...@apache.org> wrote: >>> >>>> We should have a version specific version of the ref guide that >>>> contains that information. >>>> >>>> e.g. >>>> >>>> https://hbase.apache.org/1.4/book.html#hadoop >>>> >>>> https://hbase.apache.org/2.3/book.html#hadoop >>>> >>>> Can we do a better job of making these discoverable to folks rather >>>> than keeping stuff around? >>>> >>>> On Fri, Jan 7, 2022 at 1:14 AM 张铎(Duo Zhang) <palomino...@gmail.com> >>>> wrote: >>>>> >>>>> Recently we've seen several emails on the user list asking whether >>>>> some hbase versions support specific hadoop versions, usually it will >>>>> be some versions which are already EOL, so there is no information in >>>>> our ref guide. >>>>> >>>>> For me I think we could leave the EOL versions in the support matrix >>>>> for a bit longer. It will be useful for our users. >>>>> >>>>> Thanks. >>>> >>> >>> >>> -- >>> Best regards, >>> Andrew >>> >>> Words like orphans lost among the crosstalk, meaning torn from truth's >>> decrepit hands >>> - A23, Crosstalk
