szehon-ho opened a new issue, #8151: URL: https://github.com/apache/iceberg/issues/8151
### Feature Request / Improvement Opening an issue here as https://github.com/apache/iceberg-docs has disabled issues and redirect here. 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: https://github.com/apache/iceberg-docs/pull/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 somewhere it makes sense to do a diff against, 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 like 1.3.1. We cannot cleanly rebase of latest on main, maybe due to the same issue that main docs/javadocs are not correctly updated. ``` Update the 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 ``` We end up force-pushing latest to match with 1.3.1 in this case. It's a bigger change, but could we just have latest in the site somehow be a redirection for 1.3.1, instead of physically having to have two branches that have the same state (1.3.1 and latest). ### Query engine None -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
