That sounds like a pretty good plan to me. What do others think? On Sun, Jan 9, 2022 at 4:04 PM 张铎(Duo Zhang) <palomino...@gmail.com> wrote:
> 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 > > > -- Best regards, Andrew Words like orphans lost among the crosstalk, meaning torn from truth's decrepit hands - A23, Crosstalk
