That's also a possible solution, I mean remove purge the docs in branches other than master.
So what should be done will be: 1. Remove all docs from branches other than master. 2. See how to skip the doc generating when docs are not there so we do not break the publishing release process. 3. Modify the documentation to also include the information about EOL releases, instead of just purging them from the documentation. WDYT? Thanks. Andrew Purtell <andrew.purt...@gmail.com> 于2022年1月10日周一 01:28写道： > Our branch-1 release process included a step to check out master and > overwrite root src/ to do just that, manually synchronize docs for all > releases. > > I do not believe we can keep docs in branches effectively synchronized. > Periodic manual sweeps could work but is still error prone. It would be > better to remove docs from all branches other than master and then there > will be one copy only to maintain … that will be feasible. > > > On Jan 9, 2022, at 4:39 AM, 张铎 <palomino...@gmail.com> wrote: > > > > 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 <bus...@apache.org> 于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) <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 >
