Hi all, Keeping the 'main' branch sane is a great idea!
As I built most of the site infrastructure, I want to give a heads up on the necessary bits and pieces. The versioned-docs branch has been there since the beginning as the whole documentation is "snapshotted" for each release, duplicating the whole content (currently 42 files in 'site/content/in-dev/unreleased'). The docs for published releases shouldn't be changed, so it's almost always immutable. The always growing amount of files (with each release) and the "do not accidentally change released docs" fact were the drivers for the versioned-docs branch. The required changes for a separate 'blogs' branch are: * The file 'site/content/blog/_index.adoc' should stay, which means the directory structure has to change. * Create a 'blogs' branch just with the existing 5 blog posts from main, but exclude all other files. So all commits from 'main' that touch the 'site/content/blog/' directory - but only the changes to the files in that directory, excluding '_index.adoc'. Also moving all these files from 'site/content/blog/' up to '/'. * Adopt relevant CI workflows (not just one) * Adopt all the scripts in `site/bin` and ensure * site publication works fine * local Hugo runs in Docker work fine * local Hugo runs w/o Docker work fine >From a contributor's and developer's point of view, IntelliJ detects that there is another Git tree in the code tree (main + blogs) and shows it in the Git log (aka: it shows multiple branches in one view). Git(Hub) interactions become a bit tricky in IntelliJ in that case. Git changes in a terminal have to happen from inside the 'site/content/blog/' directory (where the Git worktree would be). We currently have 5 markdown files in 'site/content/blog/2025` with a total of ~700 lines markdown across these 5 files (from `tokei site/content/in-dev/unreleased/`). Robert On Thu, Oct 30, 2025 at 6:58 PM Yufei Gu <[email protected]> wrote: > > > I believe the `blogs` branch should be based on current `main` in order > to preserve git author attribution for existing blog files. > > That's a good idea. Thanks Dmitri! > > Yufei > > > On Thu, Oct 30, 2025 at 8:10 AM Dmitri Bourlatchkov <[email protected]> > wrote: > > > To clarify my proposal: I believe the `blogs` branch should be based on > > current `main` in order to preserve git author attribution for existing > > blog files. > > > > Cheers, > > Dmitri. > > > > On Wed, Oct 29, 2025 at 1:58 PM Dmitri Bourlatchkov <[email protected]> > > wrote: > > > > > Thanks for continuing this discussion, Yufei! > > > > > > From my POV we have to consider these points: > > > > > > * What should be the dir/file layout on the blogs branch? > > > > > > My proposal: keep existing dir structure for site/content/blog, delete > > > everything else, add top-level README pointing to docs on how to > > contribute > > > new blog posts > > > > > > * We should preserve existing git author associations for existing blog > > > files. > > > > > > This means that blog files should not be re-added as "new" files, which > > is > > > currently evident on [2926]. > > > > > > I propose to implement this in the following manner: > > > > > > * We already have a blogs branch > > > * Make a PR with new blog contribution guidelines (but perhaps not merge) > > > * Remove all irrelevant content from the blogs branch and add README (one > > > PR) - this PR should not touch existing blog files. > > > * Make another PR for `main` adjusting CI so take blogs from the branch > > > * Remove blogs from `main` (third PR). > > > * Merge the blog contribution guidelines PR. > > > > > > WDYT? > > > > > > [2926] https://github.com/apache/polaris/pull/2926 > > > > > > Thanks, > > > Dmitri. > > > > > > On Wed, Oct 29, 2025 at 1:08 PM Yufei Gu <[email protected]> wrote: > > > > > >> As part of the effort, CI change is required. We will need to make > > changes > > >> to this file, > > >> > > >> > > https://github.com/polaris-catalog/polaris/blob/main/.github/workflows/site.yml#L23-L23 > > >> . > > >> I think it should not be so hard to add a new branch. We might only need > > >> something similar to this: > > >> > > >> - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 > > >> # v5 > > >> with: > > >> ref: "versioned-docs" > > >> path: site/content/releases > > >> > > >> I think putting this change in the same PR to switch over the whole blog > > >> directory would be preferred. PR #2926 could be the first one to add > > >> contents in the new branch. A second PR makes the CI changes and removes > > >> the blog content from the main branch. What do you think? > > >> > > >> Yufei > > >> > > >> > > >> On Tue, Oct 28, 2025 at 9:11 AM Yufei Gu <[email protected]> wrote: > > >> > > >> > Thanks JB and Dimitri for chiming in. > > >> > > > >> > Agreed that doc changes are needed as a blog publishing guideline. CI > > >> > change is needed as well. We can discuss more details in the PR. > > >> > > > >> > Yufei. > > >> > > > >> > > > >> > On Tue, Oct 28, 2025 at 9:06 AM Dmitri Bourlatchkov <[email protected] > > > > > >> > wrote: > > >> > > > >> >> Hi Yufei, > > >> >> > > >> >> Do you have a proposal for CI changes related to keeping blogs in a > > >> >> separate branch? > > >> >> > > >> >> Thanks, > > >> >> Dmitri. > > >> >> > > >> >> On Fri, Oct 24, 2025 at 6:53 PM Yufei Gu <[email protected]> > > wrote: > > >> >> > > >> >> > Hi folk, > > >> >> > > > >> >> > We are working on moving blogs to a different branch to keep the > > main > > >> >> > branch cleaner. You can find more details in this issue > > >> >> > https://github.com/apache/polaris/issues/2774. Thanks Ashish for > > >> >> picking > > >> >> > this up. As the next step, a new branch will be created for blogs. > > >> >> > > > >> >> > Yufei > > >> >> > > > >> >> > > >> > > > >> > > > > >
