Sounds good! Looking forward to that! -Jack On Tue, Nov 30, 2021 at 10:27 AM Sam Redai <s...@tabular.io> wrote:
> @Kyle thanks for the idea, we can definitely add that banner and have it > driven by a site level latest version value so it can easily be set on each > version release. > > @Jack that summary looks right to me. As to your idea of the "Next" > version of the docs and to Russell's description, we could absolutely have > an additional branch in the docs repo that reflects the next (yet to be > released) version of the docs. It would be as simple as including an aptly > named branch in the docs repo that always reflects the docs contained in > iceberg repo proper (possibly through some daily/weekly action). So the > branches in the iceberg docs repo could look something like this: > > - latest > - next > - 0.12.1 > - 0.12.0 > > latest can be set as the default branch for the repo and would essentially > be the result of a force push from 0.12.1 (and once 0.13.0 is released, a > force push from the 0.13.0 branch, and so on and so on). The next branch > could contain this next version that you were referring to, which is > periodically updated with the docs contained in iceberg repo proper. As > Ryan suggested, once a release happens, the docs can be copied over into a > branch for that version. This would result in the following version routes: > > https://iceberg.apache.org/latest/docs > https://iceberg.apache.org/next/docs > https://iceberg.apache.org/0.12.1/docs > https://iceberg.apache.org/0.12.0/docs > > We could also include redirects to from / to /latest/docs in order to not > break permalinks. I'll work on getting all of this finalized and share a > full summary of how the new site works as well as some developer docs on > updating/releasing. > > -Sam > > On Mon, Nov 29, 2021 at 4:28 PM Russell Spitzer <russell.spit...@gmail.com> > wrote: > >> Sounds good to me. To Confirm point 3: We have unpublished version docs >> in Iceberg repo proper, and released version doc fixes target the new >> repository. >> >> >> On Nov 29, 2021, at 4:34 PM, Ryan Blue <b...@tabular.io> wrote: >> >> I think that what Sam has put together is a good path forward for the >> docs. >> >> We definitely want to keep the latest docs in the main repository so that >> we can update them as part of normal pull requests. But at the same time, I >> think we've all had some frustration when searching through files in the >> repository because there are multiple copies of Javadocs there. And if we >> wanted to keep more versions of the markdown docs, the problem would get >> worse. >> >> By keeping just the docs that apply to master in the main iceberg repo, >> we still have the normal maintenance workflow. Copying the docs over at >> release time allows us to maintain each branch of docs separately for >> updates, without polluting the main repo with several copies. It seems like >> a win-win to me to copy docs and maintain them after that point. >> >> Does that seem reasonable to everyone? >> >> Ryan >> >> On Mon, Nov 29, 2021 at 8:54 AM Kyle Bendickson <k...@tabular.io> wrote: >> >>> Wow, the prototype looks great, Sam! >>> >>> I'd like to add a little bit about possible avenues for hosting to >>> explore and other corner areas. >>> >>> I only have one thing to add: >>> >>> 1) For the latest docs, can we consider including a warning message on >>> the page that this is for the master version. >>> >>> Apache Flink has this, and on several occasions it has helped me out. >>> Their doc string reads: "This documentation is for an unreleased version of >>> Apache Flink. We recommend you use the latest stable version <link to that >>> version>". >>> >>> Overall the site looks great. Thank you, Sam! >>> >>> On Sun, Nov 28, 2021 at 11:03 PM Sam Redai <s...@tabular.io> wrote: >>> >>>> Thanks Jack! To your questions: >>>> >>>> 1. In addition to Hugo, I tried out Pelican and Gatsby. (“Tried out” >>>> meaning spent an afternoon fooling around with it) >>>> >>>> Pelican felt easy to use but doing anything custom like a landing page >>>> required a lot of theme and site config customizations. The live reloading >>>> also felt sluggish once I added in all of the content. >>>> >>>> Gatsby seems really flexible and powerful but it requires some >>>> knowledge of React that could discourage some community contributions >>>> in the future. >>>> >>>> Hugo on the other hand, in a little over an hour I was able to get the >>>> site together with the landing page, and another hour the next day I had >>>> asciinema added and the versioned docs working via GitHub (all with no >>>> prior experience with the framework). I definitely could have either of the >>>> other frameworks misunderstood. Some other frameworks out there that I >>>> haven’t looked deeply into are Jekyll, Hexo, and Nuxt. If anyone has strong >>>> preferences for a particular framework, let me know and I can explore it >>>> further. >>>> >>>> 2. The “latest” site is a branch itself. We can actually create as many >>>> branches as we’d like and each would be deployed as a separate site. We >>>> would just have to update the releases section to include the relevant >>>> hrefs. One thing I forgot to mention is that PRs are also deployed and we >>>> could do something clever here like include a link in the PR template that >>>> links to how the PR changes looks fully deployed. >>>> >>>> 3. I was thinking we would keep a copy of the docs in the main iceberg >>>> repo where the main commits occur. As part of the iceberg version release >>>> process, the docs would be copied over to the iceberg-docs repo in a branch >>>> named after the release version. Hotfixes or typo corrections for previous >>>> versions could be done via pull requests directly to that branch in the >>>> iceberg-docs repo. That being said, I believe it’s possible to keep the >>>> docs in the same repo but it would require some magic that may feel >>>> somewhat fragile. For example the branch names such as 0.12.x wouldn’t work >>>> well if we want to have a different docs site for 0.12.0 and 0.12.1, we >>>> could probably work around this by adding some kind of regex to the deploy >>>> workflow and maybe use tags ( >>>> https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet >>>> ). >>>> >>>> -Sam >>>> >>>> On Sat, Nov 27, 2021 at 5:59 PM Jack Ye <yezhao...@gmail.com> wrote: >>>> >>>>> The website looks amazing, thanks for the work!!! >>>>> >>>>> Some questions I have: >>>>> 1. you mentioned that you compared a few different static site >>>>> frameworks. Just for bookkeeping purposes, could you list what frameworks >>>>> you have compared so that people can have more clarity over the decision >>>>> for hugo? >>>>> 2. In the website, I see the latest doc points to 0.12.1. Is it >>>>> possible to have a version named "Next" that shows the latest doc in the >>>>> master branch? >>>>> 3. For the separation of docs to another repo, I remember we discussed >>>>> the topic in the past and we decided to not do it because many people >>>>> expressed that it's valuable for docs to be in the same repo so that they >>>>> can easily view and edit it. Given that we now have the iceberg-docs repo, >>>>> do we plan to run a sync job to copy the docs to that repo, or are you >>>>> thinking about revisiting the decision to fully move the docs to >>>>> iceberg-docs? It would be helpful if you can provide more details in this >>>>> area. >>>>> >>>>> Best, >>>>> Jack Ye >>>>> >>>>> On Sat, Nov 27, 2021 at 8:52 AM Sam Redai <s...@tabular.io> wrote: >>>>> >>>>>> Hey everyone, >>>>>> >>>>>> I wanted to bring to everyone's attention an issue that I opened >>>>>> today that's a proposal for switching to using hugo for the iceberg >>>>>> documentation site. https://github.com/apache/iceberg/issues/3616 >>>>>> >>>>>> I've deployed a prototype of what the site would look like and how it >>>>>> achieves some things still left desired for the current docs site >>>>>> (landing >>>>>> page, branch based versioning, etc). Please check it out when you have a >>>>>> chance and let me know what you all think! >>>>>> https://samredai.github.io/iceberg-docs-prototype/latest/ >>>>>> >>>>>> -Sam >>>>>> >>>>> >> >> -- >> Ryan Blue >> Tabular >> >> >>
