Problems in release doc about versioned documentation

[szehon-ho]

Feature Request / Improvement

Issue on https://github.com/apache/iceberg-docs, as that repo has disabled issues.

After releasing Iceberg 1.3.1, I found the section https://github.com/apache/iceberg-docs/blob/main/landing-page/content/common/how-to-release.md#versioned-documentation-update to be the most difficult.

I worked with @aokolnychyi who had similar issues and walked me through some of the steps he had to do for 1.3.0.

Potential Cause

The issue may be that 'main' docs and javadocs folder are not kept up to date, leading to some instruction not working. Although its mentioned briefly in top that 'Note that all changes in iceberg need to happen against the master branch and changes in iceberg-docs need to happen against the main branch.', the detailed instructions don't cover where to update it exactly. But even so, issues remain.

First Issue

The first problem is that there is no way to make a clean pr against iceberg-docs feature branch (lets take an example, where feature branch is 1.3.1).

Instructions are to cut Iceberg-docs 1.3.1 branch (presumably from main branch). We then manually copy over /docs and /javadocs from Iceberg 1.3.1 and then make pr for Iceberg-docs 1.3.1 branch. The pr is un-readable, as it does a diff of whatever the iceberg-docs 1.3.1 base (from main) and the actual iceberg-1.3.1 docs.

First instruction to cut the branch

In the iceberg-docs repository, cut a new branch using the version number as the branch name
cd ../iceberg-docs
git checkout -b <VERSION>
git push --set-upstream apache <VERSION>

Second instruction to copy docs from iceberg 1.3.1 and make pr against iceberg-docs 1.3.1

Copy the versioned docs from the iceberg repo into the iceberg-docs repo
rm -rf ../iceberg-docs/docs/content
cp -r ../iceberg/docs ../iceberg-docs/docs/content
Commit the changes and open a PR against the <VERSION> branch in the iceberg-docs repo

Sample un-readable pr: apache/iceberg-docs#260

In our case, main branch docs/javadocs has not been updated for awhile, hence the weird diff. And even if we always update 'main' branch with latest, diff can still be un-readable if we are doing a patch release for an older version.

So my thought is, should we specify to cut the iceberg-docs 1.3.1 branch from a branch that makes sense as a diff base, say 1.3.1 cuts from 1.3.0, and 1.3.0 diffs against 1.2.0?

Second Issue

The second issue is how to make 'latest' branch like '1.3.1' branch. We cannot cleanly rebase of 'latest' on 'main', maybe due to the same issue that main docs/javadocs are not correctly updated.

Instruction to update latest branch:

Since main is currently the same as the version branch, one needs to rebase latest branch against main:

git checkout latest
git rebase main
git push apache latest

As main is not in the good state, we end up force-pushing 1.3.1 to latest in this case.

Question: could we have latest in the site be a redirection for 1.3.1 subdirectory, instead of physically having two branches that have the same docs and javadoc files (1.3.1 and latest).

[szehon-ho]

@nastra would you know who to bother , to see if we can improve this part of the release process?

[nastra]

Instructions are to cut Iceberg-docs 1.3.1 branch (presumably from main branch). We then manually copy over /docs and /javadocs from Iceberg 1.3.1 and then make pr for Iceberg-docs 1.3.1 branch. The pr is un-readable, as it does a diff of whatever the iceberg-docs 1.3.1 base (from main) and the actual iceberg-1.3.1 docs.

I think one of the issue is that Patch versions aren't really handled in the how-to-release page because we don't do them so often, which causes confusion.
For a patch version the base branch should always be the respective branch of the minor version (e.g. 1.3.0) instead of main/master.

So my thought is, should we specify to cut the iceberg-docs 1.3.1 branch from a branch that makes sense as a diff base, say 1.3.1 cuts from 1.3.0, and 1.3.0 diffs against 1.2.0?

Yes, that's how it should be done IMO

I think we should update the docs to reflect how to do all of those steps for a patch version (since that isn't really handled).

I know that @bitsondatadev is planned to re-work how multi-version docs are maintained and released, so @bitsondatadev just an FYI that this is a good area for improvement.

[szehon-ho]

That's great, thanks guys for looking! Yea for keeping main branch up to date, I saw this fix: apache/iceberg-docs#210 has better instructions, I hope it fixes some of the issue, but definitely as you said it is not written with patch release in mind.

I still think it would be great if 'latest' can be soft redirect somewhere. If it needs to be a git branch, we can consider changing it to a git tag? That way , release manager does have to stress about making that branch same as the release branch , as sometimes force-push is necessary depending on how messed up the 'latest' branch history , which is a bit risky

[bitsondatadev]

@szehon-ho / @nastra PTAL at this and let me know if it this proposal makes sense: https://lists.apache.org/thread/nq283g83p9cgx518jwo7dg85fm5gjrvv