Skip to content
Permalink
Browse files
[website] Add script for cut new release (release-notes, new docs, si…
…debar..) (#3198)
  • Loading branch information
nicoloboschi committed May 13, 2022
1 parent 74927db commit 736759fb2266cdf9edbe21b2a93502c61e48bc39
Showing 4 changed files with 142 additions and 44 deletions.
@@ -4,42 +4,26 @@
The "next" release doc is under `docs` directory. If you need to edit the sidebar, you have to modify `sidebars.json` file.

## How to add a new release
### Patch release
In order to add the release you have to follow the [official Docusaurus guide](https://docusaurus.io/docs/versioning#tagging-a-new-version)

Ensure you have [yarn](https://classic.yarnpkg.com/lang/en/docs/install) installed.
### Patch release

For each minor release only the latest patch version documentation is kept.

```
LATEST_RELEASED=4.14.4
NEW_RELEASE=4.14.5
cd site3/website
yarn run docusaurus docs:version $NEW_RELEASE
rm -rf versioned_docs/version-${LATEST_RELEASED}
rm -rf versioned_sidebars/version-${LATEST_RELEASED}-sidebars.json
# remove $LATEST_RELEASED from versions.json
export LATEST_RELEASED=4.14.4
export NEW_RELEASE=4.14.5
./site3/website/scripts/release-minor.sh
```
Then you have to:
- remove $LATEST_RELEASED from versions.json
- add release notes for the new release in the `src/pages/release-notes.md` file.
- - commit and push the changes
- add release notes for the new release in the `./site3/website/src/pages/release-notes.md` file.

### Major/minor release

```
NEW_RELEASE=4.15.0
cd site3/website
yarn install
yarn run docusaurus docs:version $NEW_RELEASE
export NEW_RELEASE=4.15.0
./site3/website/scripts/release-major.sh
```
Then you have to:
- add release notes for the new release in the `src/pages/release-notes.md` file.
- commit and push the changes


- add release notes for the new release in the `./site3/website/src/pages/release-notes.md` file.
@@ -0,0 +1,56 @@
#!/bin/bash
#
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.
#
set -e

if [[ -z $NEW_RELEASE ]]; then
echo "env NEW_RELEASE not set"
exit 1
fi

cd site3/website

sidebar_file="sidebars.json"
docs_dir="docs"

cd site3/website

# create versioned sidebar file
cp $sidebar_file versioned_sidebars/version-${NEW_RELEASE}-sidebars.json
# add unique id for each item in the sidebar
sed -i'.bak' "s/\"id\": \"/\"id\": \"version-${NEW_RELEASE}\//" versioned_sidebars/version-${NEW_RELEASE}-sidebars.json
rm versioned_sidebars/version-${NEW_RELEASE}-sidebars.json.bak


# create new versioned_docs from "docs" dir
cp -R $docs_dir versioned_docs/version-${NEW_RELEASE}
# replace {{ site.latest_release }} with the current release
find versioned_docs/version-${NEW_RELEASE} -type f -exec sed -i'.bak' "s/{{ site.latest_release }}/${NEW_RELEASE}/g" {} +
find versioned_docs/version-${NEW_RELEASE} -name "*.bak" | xargs rm
# resolve release notes link
new_release_md_link=${NEW_RELEASE//./}
find versioned_docs/version-${NEW_RELEASE} -type f -exec sed -i'.bak' "s/(\/release-notes)/(\/release-notes#${new_release_md_link})/g" {} +
find versioned_docs/version-${NEW_RELEASE} -name "*.bak" | xargs rm

# update versions.json with the new release
node > versions.json <<EOF
var data = require('./versions.json');
data.unshift(process.env.NEW_RELEASE);
console.log(JSON.stringify(data));
EOF
@@ -0,0 +1,58 @@
#!/bin/bash
#
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.
#
set -e

if [[ -z $LATEST_RELEASED ]]; then
echo "env LATEST_RELEASED not set"
exit 1
fi

if [[ -z $NEW_RELEASE ]]; then
echo "env NEW_RELEASE not set"
exit 1
fi


sidebar_file="version-${LATEST_RELEASED}-sidebars.json"

cd site3/website
find versioned_sidebars -name "version-${LATEST_RELEASED}-sidebars.json"
find versioned_docs -name "version-${LATEST_RELEASED}"

# replace sidebar items identifier
sed -i'.bak' "s/version-${LATEST_RELEASED}/version-${NEW_RELEASE}/" versioned_sidebars/$sidebar_file
rm "versioned_sidebars/${sidebar_file}.bak"
# rename sidebar file
mv versioned_sidebars/$sidebar_file versioned_sidebars/version-${NEW_RELEASE}-sidebars.json

# replace version in files
find versioned_docs/version-${LATEST_RELEASED} -type f -exec sed -i'.bak' "s/${LATEST_RELEASED}/${NEW_RELEASE}/g" {} +
find versioned_docs/version-${LATEST_RELEASED} -name "*.bak" | xargs rm
latest_released_md_link=${LATEST_RELEASED//./}
new_release_md_link=${NEW_RELEASE//./}
# replace Markdown links
find versioned_docs/version-${LATEST_RELEASED} -type f -exec sed -i'.bak' "s/#${latest_released_md_link}/#${new_release_md_link}/g" {} +
find versioned_docs/version-${LATEST_RELEASED} -name "*.bak" | xargs rm
# rename versioned_docs directory
mv versioned_docs/version-${LATEST_RELEASED} versioned_docs/version-${NEW_RELEASE}

# update versions.json
sed -i'.bak' "s/${LATEST_RELEASED}/${NEW_RELEASE}/" versions.json
rm versions.json.bak
@@ -174,7 +174,7 @@ For Github, we can use the milestone link in the Release Notes. E.g. [Release 4.

#### Prepare Release Notes

After review the release notes on both Github, you should write a `releaseNotes` under `site/docs/${release_version}/overview/releaseNotes.md` and then send out a pull request for review.
After review the release notes on both Github, you should write a the release notes under `site3/website/src/release-notes.md` and then send out a pull request for review.

[4.5.0 Release Notes](https://github.com/apache/bookkeeper/pull/402) is a good example to follow.

@@ -446,25 +446,25 @@ Copy the source release from the `dev` repository to the `release` repository at

### Update Website

1. Create the documentation for `${VERSION}`. Run the `release.sh` to generate the branch for `${VERSION}` and bump
the versions for website documentation; or run the `release_minor.sh` to release documentation when doing a
mintor release.

```shell
$ cd site
// use `release.sh` for major releases
$ ./scripts/release.sh
// or `release_minor.sh` for minor releases
$ ./scripts/release_minor.sh
```

Once run the `release.sh`, please send a pull request for it and get approval from any committers, then merge it.
The CI job will automatically update the website in a few minutes. Please review the website to make sure the
documentation for `${VERSION}` is live.

2. Merge the Release Notes pull request and make sure the Release Notes is updated.
1. Create the documentation for the release
#### Patch release
For each minor release only the latest patch version documentation is kept.
export LATEST_RELEASED= # version to replace
export NEW_RELEASE=${VERSION}
./site3/website/scripts/release-minor.sh

#### Major/minor release

export NEW_RELEASE=${VERSION}
./site3/website/scripts/release-major.sh
Once run the above commands, please send a pull request for it and get approval from any committers, then merge it.
The CI job will automatically update the website in a few minutes. Please review the website to make sure the
documentation for `${VERSION}` is live.

2. Merge the Release Notes pull request and make sure the [release notes page](/release-notes) is updated.

### Git tag

0 comments on commit 736759f

Please sign in to comment.