Ouch. IIRC there are lots of documentation improvements only get merged to master branch only...
I think the fact for now is that, it is a bit hard for us to keep the documentation for each minor release in sync correctly... Since we will publish the ref guide as part of our releases, let's just introduce a simple rule, keep the ref guide for all active branches always the same, and once a release line gets EOL, we will not update its ref guide any more. At least for me this rule is not very hard to follow... Thanks. Sean Busbey <[email protected]> 于2022年1月9日周日 17:15写道： > > 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) <[email protected]> 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 <[email protected]> 于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 <[email protected]> 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) <[email protected]> > > > > 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
