Sounds like we're in agreement on this plan. Thanks for all the work, Sam! Is it possible to get a PR up against the docs repo with the initial front page and then we'll build from there?
On Tue, Nov 30, 2021 at 10:30 AM Jack Ye <yezhao...@gmail.com> wrote: > 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 >>> >>> >>> -- Ryan Blue Tabular
