Skip to content

Docs: update document release steps #9921

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ajantha-bhat wants to merge 1 commit into from
Closed

Docs: update document release steps #9921

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 2 additions & 67 deletions site/docs/how-to-release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -313,74 +313,9 @@ Create a PR in the `iceberg` repo to make revapi run on the new release. For an
### Documentation Release

Documentation needs to be updated as a part of an Iceberg release after a release candidate is passed.
The commands described below assume you are in a directory containing a local clone of the `iceberg-docs`
repository and `iceberg` repository. Adjust the commands accordingly if it is not the case. 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.
Please follow the steps from [README](../README.md) to update the site docs and javadocs.
Copy link
Copy Markdown
Contributor

@nastra nastra Mar 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should this link to the section that mentions what needs to be done during a release?

Copy link
Copy Markdown
Member Author

@ajantha-bhat ajantha-bhat Mar 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wanted to link to https://github.com/apache/iceberg/blob/main/site/README.md#release-process, but release deploy won't work. So, I linked the whole file.

P.S: I just want to get rid of referencing the archived iceberg-docs repo. Once we have automation we can update this section or add more info about manual steps in a follow up.

Copy link
Copy Markdown
Collaborator

@bitsondatadev bitsondatadev Mar 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ajantha, now that the release is out, could you and @Fokko and @nastra help me review my release script?

Three thinks I'd like to have fixed by the next release are:

  1. Fix internal links that cross versioned doc and site boundaries.

  2. Add release script.

  3. Update release and contribution docs.

Copy link
Copy Markdown
Member Author

@ajantha-bhat ajantha-bhat Mar 13, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Always happy to validate.

So you want us to keep this PR on hold until we have the script for release?


#### Common documentation update

1. To start the release process, run the following steps in the `iceberg-docs` repository to copy docs over:
```shell
cp -r ../iceberg/format/* ../iceberg-docs/landing-page/content/common/
```
2. Change into the `iceberg-docs` repository and create a branch.
```shell
cd ../iceberg-docs
git checkout -b <BRANCH NAME>
```
3. Commit, push, and open a PR against the `iceberg-docs` repo (`<BRANCH NAME>` -> `main`)

#### Versioned documentation update

Once the common docs changes have been merged into `main`, the next step is to update the versioned docs.

1. In the `iceberg-docs` repository, cut a new branch using the version number as the branch name
```shell
cd ../iceberg-docs
git checkout -b <VERSION>
git push --set-upstream apache <VERSION>
```
2. Copy the versioned docs from the `iceberg` repo into the `iceberg-docs` repo
```shell
rm -rf ../iceberg-docs/docs/content
cp -r ../iceberg/docs ../iceberg-docs/docs/content
```
3. Commit the changes and open a PR against the `<VERSION>` branch in the `iceberg-docs` repo

#### Javadoc update

In the `iceberg` repository, generate the javadoc for your release and copy it to the `javadoc` folder in `iceberg-docs` repo:
```shell
cd ../iceberg
./gradlew refreshJavadoc
rm -rf ../iceberg-docs/javadoc
cp -r site/docs/javadoc/<VERSION NUMBER> ../iceberg-docs/javadoc
```

This resulted changes in `iceberg-docs` should be approved in a separate PR.

#### Update the latest branch

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

```shell
git checkout latest
git rebase main
git push apache latest
```

#### Set latest version in iceberg-docs repo

The last step is to update the `main` branch in `iceberg-docs` to set the latest version.
A PR needs to be published in the `iceberg-docs` repository with the following changes:
1. Update variable `latestVersions.iceberg` to the new release version in `landing-page/config.toml`
2. Update variable `latestVersions.iceberg` to the new release version and
`versions.nessie` to the version of `org.projectnessie.nessie:*` from [versions.props](https://github.com/apache/iceberg/blob/master/versions.props) in `docs/config.toml`
3. Update list `versions` with the new release in `landing-page/config.toml`
4. Update list `versions` with the new release in `docs/config.toml`
5. Mark the current latest release notes to past releases under `landing-page/content/common/release-notes.md`
6. Add release notes for the new release version in `landing-page/content/common/release-notes.md`
Update the `icebergVersion` and `nessieVersion` in the site config files. For an example see [this PR](https://github.com/apache/iceberg/pull/9931).

# How to Verify a Release

Expand Down