This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch update_community_docs in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 5cbcf9a8d35b428d9a7f2db5bfde5828281a6bf2 Author: 慕白 <[email protected]> AuthorDate: Thu May 21 17:23:12 2026 +0800 docs: refresh release process guide --- docs/community/how_to_release.md | 737 +++++++++------------ .../current/community/how_to_release.md | 609 ++++++++++------- .../version-1.0.0/community/how_to_release.md | 609 ++++++++++------- .../version-1.0.0/community/how_to_release.md | 737 +++++++++------------ 4 files changed, 1354 insertions(+), 1338 deletions(-) diff --git a/docs/community/how_to_release.md b/docs/community/how_to_release.md index ae29da7724..c13e12f4e0 100644 --- a/docs/community/how_to_release.md +++ b/docs/community/how_to_release.md @@ -4,455 +4,320 @@ sidebar_position: 0 id: how_to_release --- -This document mainly introduces how the release manager releases a new version of Apache Fory™. +This document describes how a release manager prepares, votes, publishes, and announces an Apache Fory™ release. -## Introduction +## Release principles -Source Release is the most important part which Apache values. +- The official Apache release artifact is the source distribution hosted on Apache dist. +- Release candidates must be voted on by the Apache Fory community before they become an official release. +- Do not publish final release artifacts, update the public website as released, or send the announcement until the vote has passed. +- Keep the release version, release-candidate version, and next development version separate. -Please pay more attention to license and signing issues. -Publishing software is a serious thing and has legal consequences. +## Variables used below -## First-time as a release manager +Replace these values before running commands: -### Environmental requirements - -This release process is operated in the Ubuntu OS, and the following tools are required: - -- JDK 1.8 -- Apache Maven 3.x -- Python 3.8 -- GnuPG 2.x -- Git -- SVN (apache uses svn to host project releases) -- Pay attention to setting environment variables: if you configure gpg keys under a different directory, - please `export GNUPGHOME=$(xxx)` +```bash +export RELEASE_VERSION=1.0.0 +export PREVIOUS_VERSION=0.17.0 +export RC_VERSION=rc1 +export RELEASE_CANDIDATE=${RELEASE_VERSION}-${RC_VERSION} +export NEXT_DEV_VERSION=1.1.0-dev +export GIT_REMOTE=apache +export GPG_KEY_ID=<your-gpg-key-id> +export MAVEN_STAGING_REPO=orgapachefory-1000 +``` -### Prepare GPG Key +Use the current release values instead of the examples above. The code version must not contain `rc`; only the tag and SVN release-candidate directory use `${RC_VERSION}`. -If you are the first to become a release manager, you need to prepare a gpg key. +Unless noted otherwise, run repository commands from the root of the `apache/fory` repository. Confirm that `${GIT_REMOTE}` points to `[email protected]:apache/fory.git` before pushing branches or tags. -Following is a quick setup, you can refer to [Apache openpgp doc](https://infra.apache.org/openpgp.html) for further -details. +## First-time setup for release managers -#### Install GPG +### Tools -```bash -sudo apt install gnupg2 -``` +Install the tools needed for the source release and for the languages you plan to verify: -#### Generate GPG Key +- JDK 17+ +- Apache Maven 3.6.3+ +- CPython 3.8+ +- GnuPG 2.x +- Git +- SVN +- Optional package verification tools: Node.js LTS and npm, Rust via rustup, Go 1.24+, Dart, .NET SDK 8.0+, and sbt -Please use your apache name and email for generate key +See the [development guide](https://github.com/apache/fory/blob/main/docs/DEVELOPMENT.md) for language-specific build requirements. -```bash -$ gpg --full-gen-key -gpg (GnuPG) 2.2.20; Copyright (C) 2020 Free Software Foundation, Inc. -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. - -Please select what kind of key you want: - (1) RSA and RSA (default) - (2) DSA and Elgamal - (3) DSA (sign only) - (4) RSA (sign only) - (14) Existing key from card -Your selection? 1 # input 1 -RSA keys may be between 1024 and 4096 bits long. -What keysize do you want? (2048) 4096 # input 4096 -Requested keysize is 4096 bits -Please specify how long the key should be valid. - 0 = key does not expire - <n> = key expires in n days - <n>w = key expires in n weeks - <n>m = key expires in n months - <n>y = key expires in n years -Key is valid for? (0) 0 # input 0 -Key does not expire at all -Is this correct? (y/N) y # input y - -GnuPG needs to construct a user ID to identify your key. - -Real name: Chaokun Yang # input your name -Email address: [email protected] # input your email -Comment: CODE SIGNING KEY # input some annotations, optional -You selected this USER-ID: - "Chaokun <[email protected]>" - -Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O # input O -We need to generate a lot of random bytes. It is a good idea to perform -some other action (type on the keyboard, move the mouse, utilize the -disks) during the prime generation; this gives the random number -generator a better chance to gain enough entropy. -We need to generate a lot of random bytes. It is a good idea to perform -some other action (type on the keyboard, move the mouse, utilize the -disks) during the prime generation; this gives the random number -generator a better chance to gain enough entropy. - -# Input the security key -┌──────────────────────────────────────────────────────┐ -│ Please enter this passphrase │ -│ │ -│ Passphrase: _______________________________ │ -│ │ -│ <OK> <Cancel> │ -└──────────────────────────────────────────────────────┘ -# key generation will be done after your inputting the key with the following output -gpg: key E49B00F626B marked as ultimately trusted -gpg: revocation certificate stored as '/Users/chaokunyang/.gnupg/openpgp-revocs.d/1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4.rev' -public and secret key created and signed. - -pub rsa4096 2022-07-12 [SC] - 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4 -uid [ultimate] Chaokun <[email protected]> -sub rsa4096 2022-07-12 [E] -``` - -#### Upload your public key to public GPG keyserver - -Firstly, list your key: +If your GPG home is not the default directory, export it before signing: ```bash -gpg --list-keys +export GNUPGHOME=<path-to-your-gnupg-home> ``` -The output is like: +### Prepare a GPG key + +If this is your first release, create a GPG key with your Apache name and email. See the [Apache OpenPGP guide](https://infra.apache.org/openpgp.html) and [release signing guide](https://infra.apache.org/release-signing.html). ```bash --------------------------------------------------- -pub rsa4096 2024-03-27 [SC] - 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4 -uid [ultimate] chaokunyang (CODE SIGNING KEY) <[email protected]> -sub rsa4096 2024-03-27 [E] +gpg --full-gen-key +gpg --list-keys +gpg --keyserver keys.openpgp.org --send-key ${GPG_KEY_ID} ``` -Then, send your key id to key server: +Add the public key to the Apache Fory KEYS file: ```bash -gpg --keyserver keys.openpgp.org --send-key <key-id> # e.g., 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4 +svn co --depth=files https://dist.apache.org/repos/dist/release/fory fory-dist-release +cd fory-dist-release +(gpg --list-sigs [email protected] && \ + gpg --export --armor [email protected]) >> KEYS +svn status +svn add KEYS 2>/dev/null || true +svn commit -m "Add release key for <your name>" ``` -Among them, `keys.openpgp.org` is a randomly selected keyserver, you can use keyserver.ubuntu.com or any other -full-featured keyserver. - -#### Check whether the key is created successfully - -Uploading takes about one minute; after that, you can check by email at the corresponding keyserver. - -Uploading keys to the keyserver is mainly for joining -a [Web of Trust](https://infra.apache.org/release-signing.html#web-of-trust). +Also add the GPG key to your GitHub account and make sure the email address is verified. -#### Add your GPG public key to the project KEYS file +### Configure Maven publishing credentials -The svn repository of the release branch is: https://dist.apache.org/repos/dist/release/fory +Before staging Java, Kotlin, or Scala artifacts, configure your Apache Nexus credentials in `~/.m2/settings.xml`. Use encrypted Maven passwords; do not store plain-text passwords. -Please add the public key to KEYS in the release branch: - -```bash -svn co --depth=files https://dist.apache.org/repos/dist/release/fory fory-dist -cd fory-dist -(gpg --list-sigs [email protected] && gpg --export --armor [email protected]) >> KEYS # Append your key to the KEYS file -svn add . # It is not needed if the KEYS document exists before. -svn ci -m "add gpg key for YOUR_NAME" # Later on, if you are asked to enter a username and password, just use your apache username and password. +```xml +<servers> + <server> + <id>apache.snapshots.https</id> + <username>your-apache-username</username> + <password>{your-encrypted-password}</password> + </server> + <server> + <id>apache.releases.https</id> + <username>your-apache-username</username> + <password>{your-encrypted-password}</password> + </server> +</servers> ``` -#### Upload the GPG public key to your GitHub account +See [Publishing Maven Artifacts](https://infra.apache.org/publishing-maven-artifacts.html) for Maven password encryption. -- Enter https://github.com/settings/keys to add your GPG key. -- Please remember to bind the email address used in the GPG key to your GitHub - account (https://github.com/settings/emails) if you find "unverified" after adding it. +### Check registry publishing access -### Further reading +Fory uses GitHub Actions to publish ecosystem packages from release tags. Before pushing any `v*` release tag, verify that the repository publishing setup is healthy for the packages included in the release: -It's recommended but not mandatory to read following documents before making a release to know more details about apache -release: +- Python wheels: `Build Containerized Release Wheels`, `Build Native Release Wheels`, and `Publish Python` +- Compiler package: `Publish Compiler` +- JavaScript packages: `Publish JavaScript` +- Rust crates: `Publish Rust` +- Dart package: `Publish Dart` +- C# package: `Publish C#` -- Release policy: https://www.apache.org/legal/release-policy.html -- TLP release: https://infra.apache.org/release-distribution -- Release sign: https://infra.apache.org/release-signing.html -- Release publish: https://infra.apache.org/release-publishing.html -- Release download pages: https://infra.apache.org/release-download-pages.html -- Publishing maven artifacts: https://infra.apache.org/publishing-maven-artifacts.html +Tags starting with `go/fory` are intentionally skipped by the tag publishing workflows. Push a Go module tag only when the Go module should be published for the final release. -## Start discussion about the release +## Start the release discussion -Start a discussion about the next release via sending email to: [email protected]: +Start a discussion on `[email protected]`. -Title: +Subject: -``` -[DISCUSS] Release Apache Fory ${release_version} +```text +[DISCUSS] Release Apache Fory ${RELEASE_VERSION} ``` Content: -``` +```text Hello, Apache Fory Community, -This is a call for a discussion to release Apache Fory version ${release_version}. +This is a call for discussion to release Apache Fory ${RELEASE_VERSION}. -The change lists about this release: +The planned change list is: +https://github.com/apache/fory/compare/v${PREVIOUS_VERSION}...main -https://github.com/apache/fory/compare/v0.12.0...v0.12.1-rc1 - -Please leave your comments here about this release plan. We will bump the version in repo and start the release process after the discussion. +Please leave your comments on this release plan. If there are no +blocking concerns, I will prepare the release candidate and start the +vote. Thanks, - -${name} +${YOUR_NAME} ``` -## Preparing for release - -If the discussion goes positive, you will need to prepare the release artifiacts. +## Prepare the release candidate -### Github branch and tag +### Create the release branch and bump versions -- Create a new branch named `releases-0.16.0` -- Bump version to `$version` by executing command `python ci/release.py bump_version -l all -version $version` -- Make a git commit and push the branch to `[email protected]:apache/fory.git` -- Create a new release tag by `git tag v0.16.0-rc1`, then push it to `[email protected]:apache/fory.git` -- If the Go module under `go/fory` is part of this release, create and push the Go submodule tag as well. For example, for the final `0.16.0` release: +Start from a clean main branch: ```bash -git remote add apache [email protected]:apache/fory.git -git tag go/fory/v0.16.0 -git push apache go/fory/v0.16.0 +git checkout main +git pull --ff-only ${GIT_REMOTE} main +git status --short ``` -### Build and upload artifacts to SVN dist/dev repo - -First you need to build source release artifacts by `python ci/release.py build -v $version`. - -Then you need to upload it to svn dist repo. The dist repo of the dev branch -is: https://dist.apache.org/repos/dist/dev/fory +Create the release branch and bump all package versions: ```bash -# As this step will copy all the versions, it will take some time. If the network is broken, please use svn cleanup to delete the lock before re-execute it. -svn co https://dist.apache.org/repos/dist/dev/fory fory-dist-dev +python ci/release.py prepare -v ${RELEASE_VERSION} +git push ${GIT_REMOTE} releases-${RELEASE_VERSION} ``` -Then, upload the artifacts: +If the branch already exists, check it out and run the version bump directly: ```bash -cd fory-dist-dev -# create a directory named by version -mkdir ${release_version}-${rc_version} -# copy source code and signature package to the versioned directory -cp ${repo_dir}/dist/* ${release_version}-${rc_version} -# check svn status -svn status -# add to svn -svn add ${release_version}-${rc_version} -# check svn status -svn status -# commit to SVN remote server -svn commit -m "Prepare for fory ${release_version}-${rc_version}" +git checkout releases-${RELEASE_VERSION} +python ci/release.py bump_version -l all -version ${RELEASE_VERSION} +git add -u +git commit -m "Prepare release ${RELEASE_VERSION}" +git push ${GIT_REMOTE} releases-${RELEASE_VERSION} ``` -Visit https://dist.apache.org/repos/dist/dev/fory/ to check the artifacts are uploaded correctly. - -### What to do if something goes wrong - -If some files are unexpected, you need to remove by `svn delete` and repeat the above upload process. - -## Voting - -### check version - -Fory requires votes from the Fory Community. - -- release_version: the version for fory, like 0.12.0. -- release_candidate_version: the version for voting, like 0.12.0-rc1. -- maven_artifact_number: the number for Maven staging artifacts, like 1001. Specifically, the maven_artifact_number can - be found by searching "fory" on https://repository.apache.org/#stagingRepositories. - -### Build the source code of fory and release it to nexus - -#### Configure Apache Account Passwords +Run the required tests for the release scope. At minimum, follow the build commands in the development guide and make sure the release branch CI is green. -Before publishing Fory to Nexus, you need to securely configure your Apache account credentials. This step is critical -as passwords must be encrypted. +### Build and verify the source artifact -First, open your Maven global settings file `settings.xml`, typically located at `~/.m2/settings.xml`. Add or modify the -following section: +Build the Apache source release artifact from the release branch: -```xml - -<servers> - <server> - <id>apache.snapshots.https</id> - <username>your-apache-username</username> - <password>{your-encrypted-password}</password> - </server> - <server> - <id>apache.releases.https</id> - <username>your-apache-username</username> - <password>{your-encrypted-password}</password> - </server> -</servers> +```bash +python ci/release.py build -v ${RELEASE_VERSION} ``` -**Important Notes:** - -- Replace `your-apache-username` with your Apache LDAP username -- Passwords must be encrypted using Maven's password encryption tool -- Encrypted passwords should be enclosed in curly braces `{}` - -Refer to the official documentation for detailed encryption -instructions: [Publishing Maven Artifacts](https://infra.apache.org/publishing-maven-artifacts.html) +This creates: -Steps to encrypt your password: - -1. Generate a master password (if you haven't already): - -2. ```sh - - mvn --encrypt-master-password your-master-password - - ``` +```text +dist/apache-fory-${RELEASE_VERSION}-src.tar.gz +dist/apache-fory-${RELEASE_VERSION}-src.tar.gz.asc +dist/apache-fory-${RELEASE_VERSION}-src.tar.gz.sha512 +``` - Save the output to `~/.m2/settings-security.xml`: +Verify the signature and checksum: -3. ```xml +```bash +cd dist +gpg --verify apache-fory-${RELEASE_VERSION}-src.tar.gz.asc \ + apache-fory-${RELEASE_VERSION}-src.tar.gz +sha512sum --check apache-fory-${RELEASE_VERSION}-src.tar.gz.sha512 +cd .. +``` - <settingsSecurity> - <master>{your-encrypted-master-password}</master> - </settingsSecurity> +It is also recommended to unpack the source archive in a clean directory and confirm that `LICENSE`, `NOTICE`, source layout, and basic builds are correct. - ``` +### Upload the release candidate to Apache dist/dev -4. Encrypt your Apache account password: +Upload the source artifact, signature, and checksum to the dev distribution repository: - ```sh +```bash +svn co https://dist.apache.org/repos/dist/dev/fory fory-dist-dev +cd fory-dist-dev +mkdir ${RELEASE_CANDIDATE} +cp ../dist/apache-fory-${RELEASE_VERSION}-src.tar.gz* ${RELEASE_CANDIDATE}/ +svn add ${RELEASE_CANDIDATE} +svn status +svn commit -m "Prepare Apache Fory ${RELEASE_CANDIDATE}" +cd .. +``` - mvn --encrypt-password your-apache-password +Check the uploaded files at: - ``` +```text +https://dist.apache.org/repos/dist/dev/fory/${RELEASE_CANDIDATE}/ +``` - Place the encrypted output into the `password` field in `settings.xml` +### Stage Maven artifacts -#### Build and Publish Java Module +Stage Java, Kotlin, and Scala artifacts before the vote. Do not release the staging repository until the vote passes. -```sh +Java: -# Navigate to the Java module directory +```bash cd java - -# Execute Maven build and deploy to Nexus -# -T10: Use 10 threads for parallel build, improving speed -# clean: Clean the project -# deploy: Deploy to remote repository -# -Papache-release: Activate apache-release profile -# -DskipTests: Skip tests -# -Dgpg.skip=false: Enable GPG signing (required for release verification) -mvn -T10 clean deploy -Papache-release -DskipTests -Dgpg.skip=false - +mvn -T10 clean deploy --no-transfer-progress -DskipTests -Prelease +cd .. ``` -#### Build and Publish Kotlin Module - -```sh - -# Return to project root and navigate to Kotlin module -cd ../kotlin - -# Execute the same Maven command as Java module -# Configuration parameters are identical to Java module -mvn -T10 clean deploy -Papache-release -DskipTests -Dgpg.skip=false +Kotlin: +```bash +cd kotlin +mvn -T10 clean deploy --no-transfer-progress -DskipTests -Prelease +cd .. ``` -#### Build and Publish Scala Module - -```sh +Scala: -# Return to project root and navigate to Scala module -cd ../scala - -# Build and sign JARs for all Scala versions -# +publishSigned: Execute publishSigned for all configured Scala versions -echo "Starting to build Scala JARs..." +```bash +cd scala sbt +publishSigned - -# Prepare for upload to Sonatype (Nexus) -# sonatypePrepare: Prepare for Maven Central Repository release -echo "Starting upload preparation..." sbt sonatypePrepare - -# Upload packaged JARs to Sonatype -# sonatypeBundleUpload: Upload prepared bundles -echo "Starting JAR upload..." sbt sonatypeBundleUpload - -echo "Scala JAR deployment succeeded!" - +cd .. ``` -#### Lock the Release in Nexus +Then open `https://repository.apache.org/#stagingRepositories`, find the `orgapachefory-<number>` staging repository, and close it. Record the staging repository id in `${MAVEN_STAGING_REPO}` for the vote email. + +### Create the RC tag and GitHub prerelease -After completing the publication of all modules, perform the following steps in Nexus: +Create and push the release-candidate tag from the release branch: -1. Log in to the Apache Nexus repository management interface -2. Navigate to the "Snapshots" or "Releases" repository (depending on your release type) -3. Locate the latest Fory project version -4. Execute the "Close" operation to validate all uploaded artifacts -5. After successful validation, execute the "Release" operation to finalize the deployment +```bash +git checkout releases-${RELEASE_VERSION} +git tag -a v${RELEASE_CANDIDATE} -m "Apache Fory ${RELEASE_CANDIDATE}" +git push ${GIT_REMOTE} v${RELEASE_CANDIDATE} +``` -These steps ensure all published artifacts are verified and correctly deployed to the public repository. +Pushing a `v*` tag triggers the package release workflows. For tags that contain `-`, workflows publish prerelease or staging packages where the ecosystem supports it, for example TestPyPI for Python packages and the `next` tag for npm packages. Monitor the GitHub Actions runs and include relevant links in the vote email when useful. -### build a Pre-release +Create a GitHub prerelease for the candidate and attach the source artifacts if needed: -You need to build a Pre-release before voting, such as: -https://github.com/apache/fory/releases/tag/v0.12.0-rc1 +```bash +gh release create v${RELEASE_CANDIDATE} \ + --repo apache/fory \ + --title "Apache Fory ${RELEASE_CANDIDATE}" \ + --prerelease \ + --notes "Release candidate for Apache Fory ${RELEASE_VERSION}." +``` -### Fory Community Vote +## Vote on the release candidate -you need send a email to Fory Community: [email protected]: +Send the vote email to `[email protected]`. -Title: +Subject: -``` -[VOTE] Release Apache Fory v${release_version}-${rc_version} +```text +[VOTE] Release Apache Fory v${RELEASE_CANDIDATE} ``` Content: -``` -Hello, Apache Fory Community: +```text +Hello, Apache Fory Community, -This is a call for vote to release Apache Fory -version release-${release_version}-${rc_version}. +This is a call for vote to release Apache Fory v${RELEASE_CANDIDATE}. -Apache Fory - A blazingly fast multi-language serialization -framework powered by JIT and zero-copy. +Apache Fory is a blazingly fast multi-language serialization framework +for idiomatic domain objects, schema IDL, and cross-language data +exchange. The discussion thread: -https://lists.apache.org/thread/xxr3od301g6v3ndj14zqc05byp9qvclh +${DISCUSS_THREAD_URL} -The change lists about this release: -https://github.com/apache/fory/compare/v0.12.0...v0.12.1-rc1 +The change list: +https://github.com/apache/fory/compare/v${PREVIOUS_VERSION}...v${RELEASE_CANDIDATE} -The release candidates: -https://dist.apache.org/repos/dist/dev/fory/0.5.0-rc3/ +The release candidate: +https://dist.apache.org/repos/dist/dev/fory/${RELEASE_CANDIDATE}/ -The maven staging for this release: -https://repository.apache.org/content/repositories/orgapachefory-1003 +The Maven staging repository: +https://repository.apache.org/content/repositories/${MAVEN_STAGING_REPO}/ Git tag for the release: -https://github.com/apache/fory/releases/tag/v0.12.0-rc1 - -If this release also publishes the Go module, include the Go submodule tag too: -https://github.com/apache/fory/releases/tag/go/fory/v0.16.0 +https://github.com/apache/fory/releases/tag/v${RELEASE_CANDIDATE} Git commit for the release: -https://github.com/apache/fory/commit/fae06330edd049bb960536e978a45b97bca66faf +${RELEASE_COMMIT_URL} -The artifacts signed with PGP key [5E580BA4], corresponding to -[[email protected]], that can be found in keys file: +The artifacts are signed with PGP key ${GPG_KEY_ID}, corresponding to +${YOUR_APACHE_EMAIL}. The key is available in the KEYS file: https://downloads.apache.org/fory/KEYS -The vote will be open for at least 72 hours until the necessary number of votes are reached. +The vote will be open for at least 72 hours. Please vote accordingly: @@ -462,55 +327,56 @@ Please vote accordingly: To learn more about Fory, please see https://fory.apache.org/ -*Valid check is a requirement for a vote. *Checklist for reference: +Checklist for reference: -[ ] Download Fory is valid. +[ ] Download links are valid. [ ] Checksums and PGP signatures are valid. -[ ] Source code distributions have correct names matching the current release. +[ ] Source distribution names match the release. [ ] LICENSE and NOTICE files are correct. -[ ] All files have license headers if necessary. -[ ] No compiled archives bundled in source archive. -[ ] Can compile from source. - -How to Build and Test, please refer to: https://github.com/apache/fory/blob/main/docs/DEVELOPMENT.md +[ ] Source files have license headers where required. +[ ] No compiled archives are bundled in the source distribution. +[ ] Source builds and tests pass. +Build and test instructions: +https://github.com/apache/fory/blob/main/docs/DEVELOPMENT.md Thanks, -${name} +${YOUR_NAME} ``` -After at least 3 +1 binding vote (from Fory Podling PMC member and committers) and no veto, -first, reply to the above voting thread to notify that the voting has ended. +The vote must stay open for at least 72 hours and receive at least three binding `+1` votes from Apache Fory PMC members, with no unresolved `-1` votes. -``` +When the vote closes, reply to the vote thread: + +```text Hi all, -The vote for Release Apache Fory v${release_version}-${rc_version} is closed now. +The vote for Apache Fory v${RELEASE_CANDIDATE} is closed now. -Thanks to everyone for helping checking and voting for the release. +Thanks to everyone who checked and voted on the release. -I will close the vote later in another thread. +I will send the vote result in a separate thread. Best, -${name} +${YOUR_NAME} ``` -Immediately afterward, launch a new voting thread to claim the voting results. +Then send the result email. -Title: +Subject: -``` -[RESULT][VOTE] Release Apache Fory v${release_version}-${rc_version} +```text +[RESULT][VOTE] Release Apache Fory v${RELEASE_CANDIDATE} ``` Content: -``` +```text Hello, Apache Fory Community, -The vote to release Apache Fory v${release_version}-${rc_version} has passed. +The vote to release Apache Fory v${RELEASE_CANDIDATE} has passed. -The vote PASSED with 3 binding +1 and 0 -1 vote: +The vote PASSED with 3 binding +1 votes and 0 -1 votes: Binding votes: @@ -518,128 +384,159 @@ Binding votes: - yyy - zzz -Vote thread: ${vote_thread_url} +Vote thread: ${VOTE_THREAD_URL} Thanks, - -${name} +${YOUR_NAME} ``` -### What if vote fail +## If the vote fails -If the vote failed, click "Drop" to drop the staging Maven artifacts. +If the vote fails: -Address the raised issues, then bump `rc_version` and file a new vote again. +1. Drop the Maven staging repository in Nexus. +2. Remove the candidate from Apache dist/dev with `svn delete`. +3. Delete the GitHub prerelease and RC tag if they should not remain visible. +4. Fix the issue. +5. Prepare a new candidate by incrementing `${RC_VERSION}` and repeating the release-candidate flow. -## Official Release +## Publish the official release -### Publish artifacts to SVN Release Directory +### Move source artifacts to Apache dist/release -- release_version: the release version for fory, like 0.5.0 -- release_candidate_version: the version for voting, like 0.5.0-rc1 +After the vote passes, move the voted source artifacts from dev to release: ```bash -svn mv https://dist.apache.org/repos/dist/dev/fory/${release_version}-${rc_version} https://dist.apache.org/repos/dist/release/fory/${release_version} -m "Release fory ${release_version}" +svn mv \ + https://dist.apache.org/repos/dist/dev/fory/${RELEASE_CANDIDATE} \ + https://dist.apache.org/repos/dist/release/fory/${RELEASE_VERSION} \ + -m "Release Apache Fory ${RELEASE_VERSION}" ``` -In the repository at https://dist.apache.org/repos/dist/dev/fory/, if any -outdated release_candidate_version are left behind when releasing the release_version, -please clear them to keep the dev repository tidy. +Wait until the release is visible on Apache mirrors and archive: -When `https://archive.apache.org/dist/fory/0.12.0/${release_version}` is -accessible (confirming that the release_version has been successfully released -and archived), we may clean up the previous release version in the release repository, -leaving only the current version. +```text +https://downloads.apache.org/fory/${RELEASE_VERSION}/ +https://archive.apache.org/dist/fory/${RELEASE_VERSION}/ +``` -### Update Fory&Fory-Site content +Clean old release-candidate directories from `dist/dev` when they are no longer needed. After the new release is archived, remove older releases from `dist/release` according to Apache distribution policy. -Submit a PR to https://github.com/apache/fory-site to update Fory-site. -Reference implementation: [#283](https://github.com/apache/fory-site/pull/283) -and [#285](https://github.com/apache/fory-site/pull/285). +### Release Maven artifacts -#### Update Fory-Site +Open `https://repository.apache.org/#stagingRepositories`, find `${MAVEN_STAGING_REPO}`, and click `Release`. -In general, the following two key areas need to be modified: +### Create the final GitHub release tag -1. Write a new announcement, for example: - Add a new markdown file under the blog folder: +Create the final tag from the voted commit and push it: +```bash +git checkout releases-${RELEASE_VERSION} +git tag -a v${RELEASE_VERSION} -m "Apache Fory ${RELEASE_VERSION}" +git push ${GIT_REMOTE} v${RELEASE_VERSION} ``` -The Apache Fory team is pleased to announce the [?] release. This is a major release that includes [? PR](https://github.com/apache/fory/compare/v[?]...v[?]) from ? distinct contributors. See the [Install](https://fory.apache.org/docs/start/install) Page to learn how to get the libraries for your platform. + +Create the final GitHub release: + +```bash +gh release create v${RELEASE_VERSION} \ + --repo apache/fory \ + --title "Apache Fory ${RELEASE_VERSION}" \ + --notes "Apache Fory ${RELEASE_VERSION} release." ``` -2. Replace versions by upgrading old versions to new ones. - For example, in [install](https://fory.apache.org/docs/start/install/#java) section, it is necessary to update the documentation for both the development branch and the latest release branch:: +The final `v${RELEASE_VERSION}` tag triggers package publishing workflows for Python, compiler, JavaScript, Rust, Dart, and C#. Monitor every workflow to completion before announcing the release. + +If this release publishes the Go module under `go/fory`, also create and push the Go submodule tag after the vote passes: +```bash +git tag go/fory/v${RELEASE_VERSION} +git push ${GIT_REMOTE} go/fory/v${RELEASE_VERSION} ``` -<dependency> - <groupId>org.apache.fory</groupId> - <artifactId>fory-core</artifactId> - <version>0.11.2</version> -</dependency> + +### Bump main to the next development version + +After the release is published, update the main branch to the next development version: + +```bash +git checkout main +git pull --ff-only ${GIT_REMOTE} main +python ci/release.py bump_version -l all -version ${NEXT_DEV_VERSION} ``` -#### Update Fory +Review user-facing installation snippets after the bump. Package metadata should move to the next development version, but README and guide installation examples should continue to show the latest released version where they are intended for users. -Submit a PR to https://github.com/apache/fury to update [README](https://github.com/apache/fury/blob/main/README.md), -like [#2207](https://github.com/apache/fury/pull/2207). +Submit the follow-up PR to `apache/fory`. -### Github officially released +### Update the website and documentation -You need to officially release this version in the Fory project -Reference implementation: https://github.com/apache/fory/releases/tag/v0.12.0 +Submit a PR to `https://github.com/apache/fory-site` that updates the release-facing website content: -### Release Maven artifacts +- Release blog post +- Download page and checksum/signature examples +- Current install docs and language guide version snippets +- zh-CN translations for the release blog and changed docs +- Versioned docs snapshot for `${RELEASE_VERSION}` +- `versions.json` and `docusaurus.config.ts` default docs version -- maven_artifact_number: the number for Maven staging artifacts, like 1001. -- Open https://repository.apache.org/#stagingRepositories. -- Find the artifact `orgapachefory-${maven_artifact_number}`, click "Release". +Build the site and verify the English and Chinese release pages before merging. ### Send the announcement -Send the release announcement to [email protected] and CC [email protected]. +Send the announcement to `[email protected]` and CC `[email protected]` after mirrors, package publishing, GitHub release, and the website update are complete. -Title: +Subject: -``` -[ANNOUNCE] Apache Fory ${release_version} released +```text +[ANNOUNCE] Apache Fory ${RELEASE_VERSION} released ``` Content: -``` +```text Hi all, -The Apache Fory community is pleased to announce -that Apache Fory {release_version} has been released! +The Apache Fory community is pleased to announce that Apache Fory +${RELEASE_VERSION} is now available. + +Apache Fory is a blazingly fast multi-language serialization framework +for idiomatic domain objects, schema IDL, and cross-language data +exchange. + +This release includes ${PR_COUNT} PRs from ${CONTRIBUTOR_COUNT} contributors. + +Highlights in ${RELEASE_VERSION} include: -Apache Fory - A blazingly fast multi-language serialization -framework powered by JIT and zero-copy. +- ... -The release notes are available here: -https://github.com/apache/fory/releases/tag/v${release_version} +Release blog, with details and examples: +https://fory.apache.org/blog/fory_${RELEASE_VERSION_WITH_UNDERSCORES}_release -For the complete list of changes: -https://github.com/apache/fory/compare/v0.12.0...v${release_version} +Release notes: +https://github.com/apache/fory/releases/tag/v${RELEASE_VERSION} -Apache Fory website: https://fory.apache.org/ +Complete change list: +https://github.com/apache/fory/compare/v${PREVIOUS_VERSION}...v${RELEASE_VERSION} -Download Links: https://fory.apache.org/download +Apache Fory website: +https://fory.apache.org/ -Fory Resources: -- Fory github repo: https://github.com/apache/fory -- Issue: https://github.com/apache/fory/issues +Download links: +https://fory.apache.org/download + +Fory resources: + +- GitHub repo: https://github.com/apache/fory +- Issue tracker: https://github.com/apache/fory/issues - Mailing list: [email protected] -We are looking to grow our community and welcome new contributors. If -you are interested in contributing to Fory, please contact us on the -mailing list or on GitHub. We will be happy to help you get started. +Thanks to everyone in the community who contributed to this release. +We welcome new contributors. If you are interested in contributing to +Fory, please contact us on the mailing list or on GitHub. ------------------ Best Regards, -${your_name} +${YOUR_NAME} ``` -Remember to use plain text instead of rich text format, or you may be rejected when CC [email protected] - -After completing the above steps, the Fory release process comes to an end. +The release process is complete after the announcement is sent. diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/community/how_to_release.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/community/how_to_release.md index a457cbab8d..09b653eae7 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/community/how_to_release.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/community/how_to_release.md @@ -4,303 +4,320 @@ sidebar_position: 0 id: how_to_release --- -本文主要介绍如何发布新版本的 Apache Fory™。 +本文说明 release manager 如何准备、投票、发布和公告 Apache Fory™ 版本。 -## 介绍 +## 发布原则 -源代码发布是 Apache 最重视以及最重要的部分。 +- 官方 Apache 发布物是托管在 Apache dist 上的源码包。 +- Release candidate 必须先经过 Apache Fory 社区投票，才能成为正式发布。 +- 投票通过之前，不要发布最终版 artifacts，不要把官网更新成“已发布”状态，也不要发送发布公告。 +- 请区分发布版本、release-candidate 版本和下一个开发版本。 -请注意许可证和发布的软件签名问题。发布软件是一件严肃的事情，并会产生相应的法律后果。 +## 下文使用的变量 -## release manager 第一次发布 +运行命令前请替换这些值： -### 环境要求 +```bash +export RELEASE_VERSION=1.0.0 +export PREVIOUS_VERSION=0.17.0 +export RC_VERSION=rc1 +export RELEASE_CANDIDATE=${RELEASE_VERSION}-${RC_VERSION} +export NEXT_DEV_VERSION=1.1.0-dev +export GIT_REMOTE=apache +export GPG_KEY_ID=<your-gpg-key-id> +export MAVEN_STAGING_REPO=orgapachefory-1000 +``` -此发布过程在 Ubuntu 系统中运行，需要以下几个环境依赖： +请使用当前发布的真实值，而不是上面的示例值。代码中的版本号不能包含 `rc`；只有 tag 和 SVN release-candidate 目录使用 `${RC_VERSION}`。 -- JDK 1.8+ -- Apache Maven 3.x+ -- Python 3.8 -- GnuPG 2.x -- Git -- SVN（Apache 基金会使用 svn 来托管项目发布） -- **设置环境变量**：如果您在不同的目录下配置了 gpg 密钥，请执行 `export GNUPGHOME=$(xxx)` 导出环境变量。 +除非另有说明，仓库命令都应在 `apache/fory` 仓库根目录下执行。推送分支或 tag 前，请确认 `${GIT_REMOTE}` 指向 `[email protected]:apache/fory.git`。 -### 准备 GPG 密钥 +## Release manager 第一次发布前的准备 -如果您是第一次作为软件发布者，您需要准备一个 GPG 密钥。 +### 工具 -您可以参考这里的[快速开始](https://infra.apache.org/openpgp.html)获取一个 GPG 密钥或者获取更多相关信息。 +安装源码发布所需工具，以及你计划验证的语言运行时工具： -#### 安装 GPG +- JDK 17+ +- Apache Maven 3.6.3+ +- CPython 3.8+ +- GnuPG 2.x +- Git +- SVN +- 可选的包验证工具：Node.js LTS 和 npm、Rust via rustup、Go 1.24+、Dart、.NET SDK 8.0+、sbt + +语言相关的构建要求见 [development guide](https://github.com/apache/fory/blob/main/docs/DEVELOPMENT.md)。 + +如果你的 GPG home 不是默认目录，请在签名前导出： ```bash -sudo apt install gnupg2 +export GNUPGHOME=<path-to-your-gnupg-home> ``` -#### 生成 GPG 密钥 - -请使用您的 Apache 名字和电子邮件地址生成 GPG 密钥： +### 准备 GPG 密钥 -```bash -$ gpg --full-gen-key -gpg (GnuPG) 2.2.20; Copyright (C) 2020 Free Software Foundation, Inc. -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. - -Please select what kind of key you want: - (1) RSA and RSA (default) - (2) DSA and Elgamal - (3) DSA (sign only) - (4) RSA (sign only) - (14) Existing key from card -Your selection? 1 # input 1 -RSA keys may be between 1024 and 4096 bits long. -What keysize do you want? (2048) 4096 # input 4096 -Requested keysize is 4096 bits -Please specify how long the key should be valid. - 0 = key does not expire - <n> = key expires in n days - <n>w = key expires in n weeks - <n>m = key expires in n months - <n>y = key expires in n years -Key is valid for? (0) 0 # input 0 -Key does not expire at all -Is this correct? (y/N) y # input y - -GnuPG needs to construct a user ID to identify your key. - -Real name: Chaokun Yang # input your name -Email address: [email protected] # input your email -Comment: CODE SIGNING KEY # input some annotations, optional -You selected this USER-ID: - "Chaokun <[email protected]>" - -Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O # input O -We need to generate a lot of random bytes. It is a good idea to perform -some other action (type on the keyboard, move the mouse, utilize the -disks) during the prime generation; this gives the random number -generator a better chance to gain enough entropy. -We need to generate a lot of random bytes. It is a good idea to perform -some other action (type on the keyboard, move the mouse, utilize the -disks) during the prime generation; this gives the random number -generator a better chance to gain enough entropy. - -# Input the security key -┌──────────────────────────────────────────────────────┐ -│ Please enter this passphrase │ -│ │ -│ Passphrase: _______________________________ │ -│ │ -│ <OK> <Cancel> │ -└──────────────────────────────────────────────────────┘ -# key generation will be done after your inputting the key with the following output -gpg: key E49B00F626B marked as ultimately trusted -gpg: revocation certificate stored as '/Users/chaokunyang/.gnupg/openpgp-revocs.d/1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4.rev' -public and secret key created and signed. - -pub rsa4096 2022-07-12 [SC] - 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4 -uid [ultimate] Chaokun <[email protected]> -sub rsa4096 2022-07-12 [E] -``` - -#### 上传公钥至 GPG 密钥服务器 - -首先，列出您所创建的 GPG 密钥： +如果这是你第一次发布，请使用你的 Apache 姓名和邮箱创建 GPG 密钥。参考 [Apache OpenPGP guide](https://infra.apache.org/openpgp.html) 和 [release signing guide](https://infra.apache.org/release-signing.html)。 ```bash +gpg --full-gen-key gpg --list-keys +gpg --keyserver keys.openpgp.org --send-key ${GPG_KEY_ID} ``` -执行相关命令之后，您将看到如下输出： +把公钥加入 Apache Fory 的 KEYS 文件： ```bash --------------------------------------------------- -pub rsa4096 2024-03-27 [SC] - 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4 -uid [ultimate] chaokunyang (CODE SIGNING KEY) <[email protected]> -sub rsa4096 2024-03-27 [E] +svn co --depth=files https://dist.apache.org/repos/dist/release/fory fory-dist-release +cd fory-dist-release +(gpg --list-sigs [email protected] && \ + gpg --export --armor [email protected]) >> KEYS +svn status +svn add KEYS 2>/dev/null || true +svn commit -m "Add release key for <your name>" ``` -然后，将您的密钥 ID 发送到密钥服务器： - -```bash -gpg --keyserver keys.openpgp.org --send-key <key-id> # e.g., 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4 +同时把 GPG key 添加到你的 GitHub 账号，并确认对应邮箱已通过验证。 + +### 配置 Maven 发布凭据 + +发布 Java、Kotlin 或 Scala artifacts 到 Maven staging 仓库之前，需要在 `~/.m2/settings.xml` 配置 Apache Nexus 凭据。请使用 Maven 加密密码，不要保存明文密码。 + +```xml +<servers> + <server> + <id>apache.snapshots.https</id> + <username>your-apache-username</username> + <password>{your-encrypted-password}</password> + </server> + <server> + <id>apache.releases.https</id> + <username>your-apache-username</username> + <password>{your-encrypted-password}</password> + </server> +</servers> ``` -其中，`keys.openpgp.org` 是一个随机选择的密钥服务器，可以使用 keyserver.ubuntu.com 或任何其他功能完备的密钥服务器。 +Maven 密码加密方式见 [Publishing Maven Artifacts](https://infra.apache.org/publishing-maven-artifacts.html)。 -#### 检查密钥是否创建成功 +### 检查各语言包发布权限 -上传大约需要一分钟；之后，您可以通过电子邮件在相应的密钥服务器上检查。 +Fory 使用 GitHub Actions 从 release tag 发布各语言生态的包。推送任何 `v*` release tag 之前，请确认本次发布涉及的包发布配置正常： -将密钥上传到密钥服务器的主要目的是为了加入一个可信的[信任网络](https://infra.apache.org/release-signing.html#web-of-trust)。 +- Python wheels：`Build Containerized Release Wheels`、`Build Native Release Wheels` 和 `Publish Python` +- Compiler package：`Publish Compiler` +- JavaScript packages：`Publish JavaScript` +- Rust crates：`Publish Rust` +- Dart package：`Publish Dart` +- C# package：`Publish C#` -#### 将 GPG 公钥添加到项目 KEYS 文件中 +以 `go/fory` 开头的 tag 会被 tag publishing workflows 跳过。只有最终版需要发布 Go module 时，才推送 Go module tag。 -发布分支的 svn 仓库是：https://dist.apache.org/repos/dist/release/fory +## 发起发布讨论 -请在发布分支的 KEYS 中添加公钥： +向 `[email protected]` 发起讨论。 -```bash -svn co https://dist.apache.org/repos/dist/release/fory fory-dist -# As this step will copy all the versions, it will take some time. If the network is broken, please use svn cleanup to delete the lock before re-execute it. -cd fory-dist -(gpg --list-sigs [email protected] && gpg --export --armor [email protected]) >> KEYS # Append your key to the KEYS file -svn add . # It is not needed if the KEYS document exists before. -svn ci -m "add gpg key for YOUR_NAME" # Later on, if you are asked to enter a username and password, just use your apache username and password. +标题： + +```text +[DISCUSS] Release Apache Fory ${RELEASE_VERSION} ``` -#### 将 GPG 公钥上传到您的 GitHub 帐户 +内容： -- 输入 `https://github.com/settings/keys` 以添加您的 GPG 密钥。 -- 如果添加后发现“未验证”字样，请将 GPG 密钥中使用的电子邮件地址绑定到您的 GitHub 帐户（https://github.com/settings/emails）。 +```text +Hello, Apache Fory Community, -### 延伸阅读 +This is a call for discussion to release Apache Fory ${RELEASE_VERSION}. -建议您在发布之前阅读以下文档，了解有关 Apache 基金会发布软件的更多详细信息，但这不是必须的： +The planned change list is: +https://github.com/apache/fory/compare/v${PREVIOUS_VERSION}...main -- 发布政策：https://www.apache.org/legal/release-policy.html -- TLP 版本：https://infra.apache.org/release-distribution -- 发布标志：https://infra.apache.org/release-signing.html -- 发布发布：https://infra.apache.org/release-publishing.html -- 发布下载页面：https://infra.apache.org/release-download-pages.html -- 发布 maven artifacts：https://infra.apache.org/publishing-maven-artifacts.html +Please leave your comments on this release plan. If there are no +blocking concerns, I will prepare the release candidate and start the +vote. -## 开始有关发布的讨论 +Thanks, +${YOUR_NAME} +``` -通过发送电子邮件至以下地址发起有关下一个版本的讨论：[email protected]： +## 准备 release candidate -标题： +### 创建发布分支并更新版本号 +从干净的 main 分支开始： + +```bash +git checkout main +git pull --ff-only ${GIT_REMOTE} main +git status --short ``` -[DISCUSS] Release Apache Fory ${release_version} + +创建发布分支并更新所有包版本： + +```bash +python ci/release.py prepare -v ${RELEASE_VERSION} +git push ${GIT_REMOTE} releases-${RELEASE_VERSION} ``` -内容： +如果发布分支已经存在，切到该分支并直接运行版本更新： +```bash +git checkout releases-${RELEASE_VERSION} +python ci/release.py bump_version -l all -version ${RELEASE_VERSION} +git add -u +git commit -m "Prepare release ${RELEASE_VERSION}" +git push ${GIT_REMOTE} releases-${RELEASE_VERSION} ``` -Hello, Apache Fory Community, -This is a call for a discussion to release Apache Fory version ${release_version}. +运行本次发布范围需要的测试。至少应按 development guide 中的构建命令验证，并确认发布分支 CI 为绿色。 -The change lists about this release: +### 构建并验证源码包 -https://github.com/apache/fory/compare/v0.11.2...v0.12.0 +从发布分支构建 Apache 源码发布包： -Please leave your comments here about this release plan. We will bump the version in repo and start the release process after the discussion. +```bash +python ci/release.py build -v ${RELEASE_VERSION} +``` -Thanks, +该命令会生成： -${name} +```text +dist/apache-fory-${RELEASE_VERSION}-src.tar.gz +dist/apache-fory-${RELEASE_VERSION}-src.tar.gz.asc +dist/apache-fory-${RELEASE_VERSION}-src.tar.gz.sha512 ``` -## 准备发布 +验证签名和 checksum： + +```bash +cd dist +gpg --verify apache-fory-${RELEASE_VERSION}-src.tar.gz.asc \ + apache-fory-${RELEASE_VERSION}-src.tar.gz +sha512sum --check apache-fory-${RELEASE_VERSION}-src.tar.gz.sha512 +cd .. +``` -如果讨论结果中没有出现反对声音，您需要做一些发布版本的准备工作。 +建议再把源码包解压到干净目录，确认 `LICENSE`、`NOTICE`、源码目录结构和基本构建都正确。 -### Github 分支和标签 +### 上传 release candidate 到 Apache dist/dev -- 创建一个名为 `releases-0.16.0` -- 通过执行命令将版本 `$version` 升级到 `python ci/release.py bump_version -l all -version $version` -- 执行 git commit 并将分支推送到 `[email protected]:apache/fory.git` -- 通过 `git tag v0.16.0-rc1` 创建一个 release 标签，然后将其推送到 `[email protected]:apache/fory.git` -- 如果本次发布包含 `go/fory` 这个 Go 子模块，还需要额外创建并推送 Go 子模块标签。例如，对于最终版 `0.16.0`，执行： +把源码包、签名和 checksum 上传到 dev distribution 仓库： ```bash -git tag go/fory/v0.16.0 -git push apache go/fory/v0.16.0 +svn co https://dist.apache.org/repos/dist/dev/fory fory-dist-dev +cd fory-dist-dev +mkdir ${RELEASE_CANDIDATE} +cp ../dist/apache-fory-${RELEASE_VERSION}-src.tar.gz* ${RELEASE_CANDIDATE}/ +svn add ${RELEASE_CANDIDATE} +svn status +svn commit -m "Prepare Apache Fory ${RELEASE_CANDIDATE}" +cd .. +``` + +检查上传后的文件： + +```text +https://dist.apache.org/repos/dist/dev/fory/${RELEASE_CANDIDATE}/ ``` -### 构建 artifacts 并上传到 SVN dist/dev 仓库 +### Stage Maven artifacts -首先，您需要通过 `python ci/release.py build -v $version` 构建预发布 artifacts。 +投票前先 stage Java、Kotlin 和 Scala artifacts。投票通过前不要 release 这个 staging repository。 -然后您需要把它上传到 svn dist repo。dev 分支的 dist 仓库地址是：https://dist.apache.org/repos/dist/dev/fory +Java： ```bash -# As this step will copy all the versions, it will take some time. If the network is broken, please use svn cleanup to delete the lock before re-execute it. -svn co https://dist.apache.org/repos/dist/dev/fory fory-dist-dev +cd java +mvn -T10 clean deploy --no-transfer-progress -DskipTests -Prelease +cd .. ``` -然后，上传项目： +Kotlin： ```bash -cd fory-dist-dev -# create a directory named by version -mkdir ${release_version}-${rc_version} -# copy source code and signature package to the versioned directory -cp ${repo_dir}/dist/* ${release_version}-${rc_version} -# check svn status -svn status -# add to svn -svn add ${release_version}-${rc_version} -# check svn status -svn status -# commit to SVN remote server -svn commit -m "Prepare for fory ${release_version}-${rc_version}" +cd kotlin +mvn -T10 clean deploy --no-transfer-progress -DskipTests -Prelease +cd .. +``` + +Scala： + +```bash +cd scala +sbt +publishSigned +sbt sonatypePrepare +sbt sonatypeBundleUpload +cd .. ``` -访问 https://dist.apache.org/repos/dist/dev/fory/ 以检查 artifacts 是否正确上传。 +然后打开 `https://repository.apache.org/#stagingRepositories`，找到 `orgapachefory-<number>` staging repository，并执行 close。把 staging repository id 记录到 `${MAVEN_STAGING_REPO}`，用于投票邮件。 + +### 创建 RC tag 和 GitHub prerelease -### 如果出现问题该怎么办 +从发布分支创建并推送 release-candidate tag： -如果某些文件是意外出现或者发生某些错误，则需要删除相关内容并执行 `svn delete`，然后重复上述上传过程。 +```bash +git checkout releases-${RELEASE_VERSION} +git tag -a v${RELEASE_CANDIDATE} -m "Apache Fory ${RELEASE_CANDIDATE}" +git push ${GIT_REMOTE} v${RELEASE_CANDIDATE} +``` -## 投票 +推送 `v*` tag 会触发 package release workflows。对于包含 `-` 的 tag，workflow 会在对应生态支持时发布 prerelease 或 staging 包，例如 Python 包发布到 TestPyPI，npm 包使用 `next` tag。请监控 GitHub Actions 运行结果；有需要时把相关链接放进投票邮件。 -新版本发布需要 Apache Fory 社区的投票。 +创建 GitHub prerelease，并按需附加源码包： -- release_version：Fory 的版本，如 0.12.0。 -- release_candidate_version：投票的版本，如 0.12.0-rc1。 -- maven_artifact_number：Maven 暂存 artifacts 的数量。如 1001. 具体来说，可以通过搜索 “fory” 来找到 maven_artifact_number https://repository.apache.org/#stagingRepositories. +```bash +gh release create v${RELEASE_CANDIDATE} \ + --repo apache/fory \ + --title "Apache Fory ${RELEASE_CANDIDATE}" \ + --prerelease \ + --notes "Release candidate for Apache Fory ${RELEASE_VERSION}." +``` -### Fory 社区投票 +## 对 release candidate 发起投票 -发送电子邮件至 Fory Community：[email protected]： +向 `[email protected]` 发送投票邮件。 标题： -``` -[VOTE] Release Apache Fory v${release_version}-${rc_version} +```text +[VOTE] Release Apache Fory v${RELEASE_CANDIDATE} ``` 内容： -``` -Hello, Apache Fory Community: +```text +Hello, Apache Fory Community, -This is a call for vote to release Apache Fory -version release-0.12.0-rc1. +This is a call for vote to release Apache Fory v${RELEASE_CANDIDATE}. -Apache Fory - A blazingly fast multi-language serialization -framework powered by JIT and zero-copy. +Apache Fory is a blazingly fast multi-language serialization framework +for idiomatic domain objects, schema IDL, and cross-language data +exchange. -The change lists about this release: +The discussion thread: +${DISCUSS_THREAD_URL} -https://github.com/apache/fory/compare/v0.12.0...v0.12.0-rc1 +The change list: +https://github.com/apache/fory/compare/v${PREVIOUS_VERSION}...v${RELEASE_CANDIDATE} -The release candidates: -https://dist.apache.org/repos/dist/dev/fory/0.12.0-rc1/ +The release candidate: +https://dist.apache.org/repos/dist/dev/fory/${RELEASE_CANDIDATE}/ -The maven staging for this release: -https://repository.apache.org/content/repositories/orgapachefory-1003 +The Maven staging repository: +https://repository.apache.org/content/repositories/${MAVEN_STAGING_REPO}/ Git tag for the release: -https://github.com/apache/fory/releases/tag/v0.12.0-rc1 - -如果本次发布还包含 Go 模块，请同时附上 Go 子模块标签： -https://github.com/apache/fory/releases/tag/go/fory/v0.16.0 +https://github.com/apache/fory/releases/tag/v${RELEASE_CANDIDATE} Git commit for the release: -https://github.com/apache/fory/commit/fae06330edd049bb960536e978a45b97bca66faf +${RELEASE_COMMIT_URL} -The artifacts signed with PGP key [5E580BA4], corresponding to -[[email protected]], that can be found in keys file: +The artifacts are signed with PGP key ${GPG_KEY_ID}, corresponding to +${YOUR_APACHE_EMAIL}. The key is available in the KEYS file: https://downloads.apache.org/fory/KEYS -The vote will be open for at least 72 hours until the necessary number of votes are reached. +The vote will be open for at least 72 hours. Please vote accordingly: @@ -310,38 +327,56 @@ Please vote accordingly: To learn more about Fory, please see https://fory.apache.org/ -*Valid check is a requirement for a vote. *Checklist for reference: +Checklist for reference: -[ ] Download Fory is valid. +[ ] Download links are valid. [ ] Checksums and PGP signatures are valid. -[ ] Source code distributions have correct names matching the current release. +[ ] Source distribution names match the release. [ ] LICENSE and NOTICE files are correct. -[ ] All files have license headers if necessary. -[ ] No compiled archives bundled in source archive. -[ ] Can compile from source. +[ ] Source files have license headers where required. +[ ] No compiled archives are bundled in the source distribution. +[ ] Source builds and tests pass. -How to Build and Test, please refer to: https://github.com/apache/fory/blob/main/docs/DEVELOPMENT.md +Build and test instructions: +https://github.com/apache/fory/blob/main/docs/DEVELOPMENT.md Thanks, -Chaokun Yang +${YOUR_NAME} ``` -在至少获得 3 + 1 且具有约束力的投票（来自 Fory Podling PMC 成员和提交者）并没有收到否决票之后，发布投票结果： +投票至少保持 72 小时，并且需要至少三个 Apache Fory PMC member 的 binding `+1`，且没有未解决的 `-1`。 -标题： +投票结束时，先回复投票线程： + +```text +Hi all, + +The vote for Apache Fory v${RELEASE_CANDIDATE} is closed now. + +Thanks to everyone who checked and voted on the release. +I will send the vote result in a separate thread. + +Best, +${YOUR_NAME} ``` -[RESULT][VOTE] Release Apache Fory v${release_version}-${rc_version} + +然后发送投票结果邮件。 + +标题： + +```text +[RESULT][VOTE] Release Apache Fory v${RELEASE_CANDIDATE} ``` 内容： -``` +```text Hello, Apache Fory Community, -The vote to release Apache Fory v${release_version}-${rc_version} has passed. +The vote to release Apache Fory v${RELEASE_CANDIDATE} has passed. -The vote PASSED with 3 binding +1 and 0 -1 vote: +The vote PASSED with 3 binding +1 votes and 0 -1 votes: Binding votes: @@ -349,83 +384,159 @@ Binding votes: - yyy - zzz -Vote thread: ${vote_thread_url} +Vote thread: ${VOTE_THREAD_URL} Thanks, +${YOUR_NAME} +``` + +## 如果投票失败 + +如果投票失败： + +1. 在 Nexus 中 drop Maven staging repository。 +2. 使用 `svn delete` 从 Apache dist/dev 删除该 candidate。 +3. 如果不应该继续展示 GitHub prerelease 和 RC tag，也删除它们。 +4. 修复问题。 +5. 递增 `${RC_VERSION}`，重新准备新的 candidate 并再次进入投票流程。 + +## 发布正式版本 + +### 将源码包移动到 Apache dist/release + +投票通过后，把通过投票的源码包从 dev 移到 release： -${name} +```bash +svn mv \ + https://dist.apache.org/repos/dist/dev/fory/${RELEASE_CANDIDATE} \ + https://dist.apache.org/repos/dist/release/fory/${RELEASE_VERSION} \ + -m "Release Apache Fory ${RELEASE_VERSION}" ``` -### 如果投票失败怎么办 +等待发布在 Apache mirror 和 archive 可见： + +```text +https://downloads.apache.org/fory/${RELEASE_VERSION}/ +https://archive.apache.org/dist/fory/${RELEASE_VERSION}/ +``` -如果投票失败，请单击“删除”以删除暂存的 Maven artifacts。 +不再需要的 release-candidate 目录应从 `dist/dev` 清理。新版本归档后，根据 Apache distribution policy 从 `dist/release` 删除旧版本。 -解决提出的问题，然后再次提出 `rc_version` 的新投票。 +### Release Maven artifacts -## 官方发布 +打开 `https://repository.apache.org/#stagingRepositories`，找到 `${MAVEN_STAGING_REPO}`，点击 `Release`。 -### 将 artifacts 发布到 SVN 发布目录 +### 创建最终 GitHub release tag -- release_version：Fory 的发布版本，如 0.12.0 -- release_candidate_version：投票版本，如 0.12.0-rc1 +从通过投票的 commit 创建并推送最终 tag： ```bash -svn mv https://dist.apache.org/repos/dist/dev/fory/${release_version}-${rc_version} https://dist.apache.org/repos/dist/release/fory/${release_version} -m "Release fory ${release_version}" +git checkout releases-${RELEASE_VERSION} +git tag -a v${RELEASE_VERSION} -m "Apache Fory ${RELEASE_VERSION}" +git push ${GIT_REMOTE} v${RELEASE_VERSION} ``` -### 更改 Fory 网站下载链接 +创建最终 GitHub release： -提交 PR 到 https://github.com/apache/fory-site 仓库更新 Fory 版本，[下载页面](https://fory.apache.org/download) +```bash +gh release create v${RELEASE_VERSION} \ + --repo apache/fory \ + --title "Apache Fory ${RELEASE_VERSION}" \ + --notes "Apache Fory ${RELEASE_VERSION} release." +``` -### 发布 Maven artifacts +最终的 `v${RELEASE_VERSION}` tag 会触发 Python、compiler、JavaScript、Rust、Dart 和 C# 的包发布 workflows。发送发布公告前，请监控所有 workflow 直到完成。 -- maven_artifact_number：Maven 暂存 artifacts 的数量。如 1001。 -- 打开https://repository.apache.org/#stagingRepositories. -- 找到 artifacts `orgapachefory-${maven_artifact_number}`，点击“发布”。 +如果本次发布包含 `go/fory` 下的 Go module，请在投票通过后同时创建并推送 Go 子模块 tag： -### 发送公告 +```bash +git tag go/fory/v${RELEASE_VERSION} +git push ${GIT_REMOTE} go/fory/v${RELEASE_VERSION} +``` -将发布公告发送给 [email protected] 并且抄送给 [email protected]。 +### 将 main 分支更新到下一个开发版本 -标题： +发布完成后，把 main 分支更新到下一个开发版本： +```bash +git checkout main +git pull --ff-only ${GIT_REMOTE} main +python ci/release.py bump_version -l all -version ${NEXT_DEV_VERSION} ``` -[ANNOUNCE] Apache Fory ${release_version} released + +版本更新后检查面向用户的安装示例。包元数据应该移动到下一个开发版本，但 README 和 guide 中面向用户的安装示例如果表示“最新稳定版”，应继续展示刚发布的版本。 + +向 `apache/fory` 提交后续 PR。 + +### 更新网站和文档 + +向 `https://github.com/apache/fory-site` 提交 PR，更新面向发布的官网内容： + +- Release blog post +- Download page 和 checksum/signature 示例 +- Current install docs 和各语言 guide 中的版本示例 +- Release blog 和变更文档的 zh-CN 翻译 +- `${RELEASE_VERSION}` 的 versioned docs snapshot +- `versions.json` 和 `docusaurus.config.ts` 默认 docs 版本 + +合并前请构建站点，并验证英文和中文发布页面。 + +### 发送发布公告 + +Apache mirror、包发布、GitHub release 和网站更新完成后，向 `[email protected]` 发送公告，并抄送 `[email protected]`。 + +标题： + +```text +[ANNOUNCE] Apache Fory ${RELEASE_VERSION} released ``` 内容： -``` +```text Hi all, -The Apache Fory community is pleased to announce -that Apache Fory {release_version} has been released! +The Apache Fory community is pleased to announce that Apache Fory +${RELEASE_VERSION} is now available. + +Apache Fory is a blazingly fast multi-language serialization framework +for idiomatic domain objects, schema IDL, and cross-language data +exchange. + +This release includes ${PR_COUNT} PRs from ${CONTRIBUTOR_COUNT} contributors. + +Highlights in ${RELEASE_VERSION} include: + +- ... + +Release blog, with details and examples: +https://fory.apache.org/blog/fory_${RELEASE_VERSION_WITH_UNDERSCORES}_release -Apache Fory - A blazingly fast multi-language serialization -framework powered by JIT and zero-copy. +Release notes: +https://github.com/apache/fory/releases/tag/v${RELEASE_VERSION} -The release notes are available here: -https://github.com/apache/fory/releases/tag/v${release_version} +Complete change list: +https://github.com/apache/fory/compare/v${PREVIOUS_VERSION}...v${RELEASE_VERSION} -For the complete list of changes: -https://github.com/apache/fory/compare/v0.12.0...v${release_version} +Apache Fory website: +https://fory.apache.org/ -Apache Fory website: https://fory.apache.org/ +Download links: +https://fory.apache.org/download -Download Links: https://fory.apache.org/download +Fory resources: -Fory Resources: -- Fory github repo: https://github.com/apache/fory -- Issue: https://github.com/apache/fory/issues +- GitHub repo: https://github.com/apache/fory +- Issue tracker: https://github.com/apache/fory/issues - Mailing list: [email protected] -We are looking to grow our community and welcome new contributors. If -you are interested in contributing to Fory, please contact us on the -mailing list or on GitHub. We will be happy to help you get started. +Thanks to everyone in the community who contributed to this release. +We welcome new contributors. If you are interested in contributing to +Fory, please contact us on the mailing list or on GitHub. ------------------ Best Regards, -${your_name} +${YOUR_NAME} ``` -至此，整个发布流程结束。 +发布公告发送后，整个发布流程完成。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.0.0/community/how_to_release.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.0.0/community/how_to_release.md index a457cbab8d..09b653eae7 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.0.0/community/how_to_release.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-1.0.0/community/how_to_release.md @@ -4,303 +4,320 @@ sidebar_position: 0 id: how_to_release --- -本文主要介绍如何发布新版本的 Apache Fory™。 +本文说明 release manager 如何准备、投票、发布和公告 Apache Fory™ 版本。 -## 介绍 +## 发布原则 -源代码发布是 Apache 最重视以及最重要的部分。 +- 官方 Apache 发布物是托管在 Apache dist 上的源码包。 +- Release candidate 必须先经过 Apache Fory 社区投票，才能成为正式发布。 +- 投票通过之前，不要发布最终版 artifacts，不要把官网更新成“已发布”状态，也不要发送发布公告。 +- 请区分发布版本、release-candidate 版本和下一个开发版本。 -请注意许可证和发布的软件签名问题。发布软件是一件严肃的事情，并会产生相应的法律后果。 +## 下文使用的变量 -## release manager 第一次发布 +运行命令前请替换这些值： -### 环境要求 +```bash +export RELEASE_VERSION=1.0.0 +export PREVIOUS_VERSION=0.17.0 +export RC_VERSION=rc1 +export RELEASE_CANDIDATE=${RELEASE_VERSION}-${RC_VERSION} +export NEXT_DEV_VERSION=1.1.0-dev +export GIT_REMOTE=apache +export GPG_KEY_ID=<your-gpg-key-id> +export MAVEN_STAGING_REPO=orgapachefory-1000 +``` -此发布过程在 Ubuntu 系统中运行，需要以下几个环境依赖： +请使用当前发布的真实值，而不是上面的示例值。代码中的版本号不能包含 `rc`；只有 tag 和 SVN release-candidate 目录使用 `${RC_VERSION}`。 -- JDK 1.8+ -- Apache Maven 3.x+ -- Python 3.8 -- GnuPG 2.x -- Git -- SVN（Apache 基金会使用 svn 来托管项目发布） -- **设置环境变量**：如果您在不同的目录下配置了 gpg 密钥，请执行 `export GNUPGHOME=$(xxx)` 导出环境变量。 +除非另有说明，仓库命令都应在 `apache/fory` 仓库根目录下执行。推送分支或 tag 前，请确认 `${GIT_REMOTE}` 指向 `[email protected]:apache/fory.git`。 -### 准备 GPG 密钥 +## Release manager 第一次发布前的准备 -如果您是第一次作为软件发布者，您需要准备一个 GPG 密钥。 +### 工具 -您可以参考这里的[快速开始](https://infra.apache.org/openpgp.html)获取一个 GPG 密钥或者获取更多相关信息。 +安装源码发布所需工具，以及你计划验证的语言运行时工具： -#### 安装 GPG +- JDK 17+ +- Apache Maven 3.6.3+ +- CPython 3.8+ +- GnuPG 2.x +- Git +- SVN +- 可选的包验证工具：Node.js LTS 和 npm、Rust via rustup、Go 1.24+、Dart、.NET SDK 8.0+、sbt + +语言相关的构建要求见 [development guide](https://github.com/apache/fory/blob/main/docs/DEVELOPMENT.md)。 + +如果你的 GPG home 不是默认目录，请在签名前导出： ```bash -sudo apt install gnupg2 +export GNUPGHOME=<path-to-your-gnupg-home> ``` -#### 生成 GPG 密钥 - -请使用您的 Apache 名字和电子邮件地址生成 GPG 密钥： +### 准备 GPG 密钥 -```bash -$ gpg --full-gen-key -gpg (GnuPG) 2.2.20; Copyright (C) 2020 Free Software Foundation, Inc. -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. - -Please select what kind of key you want: - (1) RSA and RSA (default) - (2) DSA and Elgamal - (3) DSA (sign only) - (4) RSA (sign only) - (14) Existing key from card -Your selection? 1 # input 1 -RSA keys may be between 1024 and 4096 bits long. -What keysize do you want? (2048) 4096 # input 4096 -Requested keysize is 4096 bits -Please specify how long the key should be valid. - 0 = key does not expire - <n> = key expires in n days - <n>w = key expires in n weeks - <n>m = key expires in n months - <n>y = key expires in n years -Key is valid for? (0) 0 # input 0 -Key does not expire at all -Is this correct? (y/N) y # input y - -GnuPG needs to construct a user ID to identify your key. - -Real name: Chaokun Yang # input your name -Email address: [email protected] # input your email -Comment: CODE SIGNING KEY # input some annotations, optional -You selected this USER-ID: - "Chaokun <[email protected]>" - -Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O # input O -We need to generate a lot of random bytes. It is a good idea to perform -some other action (type on the keyboard, move the mouse, utilize the -disks) during the prime generation; this gives the random number -generator a better chance to gain enough entropy. -We need to generate a lot of random bytes. It is a good idea to perform -some other action (type on the keyboard, move the mouse, utilize the -disks) during the prime generation; this gives the random number -generator a better chance to gain enough entropy. - -# Input the security key -┌──────────────────────────────────────────────────────┐ -│ Please enter this passphrase │ -│ │ -│ Passphrase: _______________________________ │ -│ │ -│ <OK> <Cancel> │ -└──────────────────────────────────────────────────────┘ -# key generation will be done after your inputting the key with the following output -gpg: key E49B00F626B marked as ultimately trusted -gpg: revocation certificate stored as '/Users/chaokunyang/.gnupg/openpgp-revocs.d/1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4.rev' -public and secret key created and signed. - -pub rsa4096 2022-07-12 [SC] - 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4 -uid [ultimate] Chaokun <[email protected]> -sub rsa4096 2022-07-12 [E] -``` - -#### 上传公钥至 GPG 密钥服务器 - -首先，列出您所创建的 GPG 密钥： +如果这是你第一次发布，请使用你的 Apache 姓名和邮箱创建 GPG 密钥。参考 [Apache OpenPGP guide](https://infra.apache.org/openpgp.html) 和 [release signing guide](https://infra.apache.org/release-signing.html)。 ```bash +gpg --full-gen-key gpg --list-keys +gpg --keyserver keys.openpgp.org --send-key ${GPG_KEY_ID} ``` -执行相关命令之后，您将看到如下输出： +把公钥加入 Apache Fory 的 KEYS 文件： ```bash --------------------------------------------------- -pub rsa4096 2024-03-27 [SC] - 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4 -uid [ultimate] chaokunyang (CODE SIGNING KEY) <[email protected]> -sub rsa4096 2024-03-27 [E] +svn co --depth=files https://dist.apache.org/repos/dist/release/fory fory-dist-release +cd fory-dist-release +(gpg --list-sigs [email protected] && \ + gpg --export --armor [email protected]) >> KEYS +svn status +svn add KEYS 2>/dev/null || true +svn commit -m "Add release key for <your name>" ``` -然后，将您的密钥 ID 发送到密钥服务器： - -```bash -gpg --keyserver keys.openpgp.org --send-key <key-id> # e.g., 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4 +同时把 GPG key 添加到你的 GitHub 账号，并确认对应邮箱已通过验证。 + +### 配置 Maven 发布凭据 + +发布 Java、Kotlin 或 Scala artifacts 到 Maven staging 仓库之前，需要在 `~/.m2/settings.xml` 配置 Apache Nexus 凭据。请使用 Maven 加密密码，不要保存明文密码。 + +```xml +<servers> + <server> + <id>apache.snapshots.https</id> + <username>your-apache-username</username> + <password>{your-encrypted-password}</password> + </server> + <server> + <id>apache.releases.https</id> + <username>your-apache-username</username> + <password>{your-encrypted-password}</password> + </server> +</servers> ``` -其中，`keys.openpgp.org` 是一个随机选择的密钥服务器，可以使用 keyserver.ubuntu.com 或任何其他功能完备的密钥服务器。 +Maven 密码加密方式见 [Publishing Maven Artifacts](https://infra.apache.org/publishing-maven-artifacts.html)。 -#### 检查密钥是否创建成功 +### 检查各语言包发布权限 -上传大约需要一分钟；之后，您可以通过电子邮件在相应的密钥服务器上检查。 +Fory 使用 GitHub Actions 从 release tag 发布各语言生态的包。推送任何 `v*` release tag 之前，请确认本次发布涉及的包发布配置正常： -将密钥上传到密钥服务器的主要目的是为了加入一个可信的[信任网络](https://infra.apache.org/release-signing.html#web-of-trust)。 +- Python wheels：`Build Containerized Release Wheels`、`Build Native Release Wheels` 和 `Publish Python` +- Compiler package：`Publish Compiler` +- JavaScript packages：`Publish JavaScript` +- Rust crates：`Publish Rust` +- Dart package：`Publish Dart` +- C# package：`Publish C#` -#### 将 GPG 公钥添加到项目 KEYS 文件中 +以 `go/fory` 开头的 tag 会被 tag publishing workflows 跳过。只有最终版需要发布 Go module 时，才推送 Go module tag。 -发布分支的 svn 仓库是：https://dist.apache.org/repos/dist/release/fory +## 发起发布讨论 -请在发布分支的 KEYS 中添加公钥： +向 `[email protected]` 发起讨论。 -```bash -svn co https://dist.apache.org/repos/dist/release/fory fory-dist -# As this step will copy all the versions, it will take some time. If the network is broken, please use svn cleanup to delete the lock before re-execute it. -cd fory-dist -(gpg --list-sigs [email protected] && gpg --export --armor [email protected]) >> KEYS # Append your key to the KEYS file -svn add . # It is not needed if the KEYS document exists before. -svn ci -m "add gpg key for YOUR_NAME" # Later on, if you are asked to enter a username and password, just use your apache username and password. +标题： + +```text +[DISCUSS] Release Apache Fory ${RELEASE_VERSION} ``` -#### 将 GPG 公钥上传到您的 GitHub 帐户 +内容： -- 输入 `https://github.com/settings/keys` 以添加您的 GPG 密钥。 -- 如果添加后发现“未验证”字样，请将 GPG 密钥中使用的电子邮件地址绑定到您的 GitHub 帐户（https://github.com/settings/emails）。 +```text +Hello, Apache Fory Community, -### 延伸阅读 +This is a call for discussion to release Apache Fory ${RELEASE_VERSION}. -建议您在发布之前阅读以下文档，了解有关 Apache 基金会发布软件的更多详细信息，但这不是必须的： +The planned change list is: +https://github.com/apache/fory/compare/v${PREVIOUS_VERSION}...main -- 发布政策：https://www.apache.org/legal/release-policy.html -- TLP 版本：https://infra.apache.org/release-distribution -- 发布标志：https://infra.apache.org/release-signing.html -- 发布发布：https://infra.apache.org/release-publishing.html -- 发布下载页面：https://infra.apache.org/release-download-pages.html -- 发布 maven artifacts：https://infra.apache.org/publishing-maven-artifacts.html +Please leave your comments on this release plan. If there are no +blocking concerns, I will prepare the release candidate and start the +vote. -## 开始有关发布的讨论 +Thanks, +${YOUR_NAME} +``` -通过发送电子邮件至以下地址发起有关下一个版本的讨论：[email protected]： +## 准备 release candidate -标题： +### 创建发布分支并更新版本号 +从干净的 main 分支开始： + +```bash +git checkout main +git pull --ff-only ${GIT_REMOTE} main +git status --short ``` -[DISCUSS] Release Apache Fory ${release_version} + +创建发布分支并更新所有包版本： + +```bash +python ci/release.py prepare -v ${RELEASE_VERSION} +git push ${GIT_REMOTE} releases-${RELEASE_VERSION} ``` -内容： +如果发布分支已经存在，切到该分支并直接运行版本更新： +```bash +git checkout releases-${RELEASE_VERSION} +python ci/release.py bump_version -l all -version ${RELEASE_VERSION} +git add -u +git commit -m "Prepare release ${RELEASE_VERSION}" +git push ${GIT_REMOTE} releases-${RELEASE_VERSION} ``` -Hello, Apache Fory Community, -This is a call for a discussion to release Apache Fory version ${release_version}. +运行本次发布范围需要的测试。至少应按 development guide 中的构建命令验证，并确认发布分支 CI 为绿色。 -The change lists about this release: +### 构建并验证源码包 -https://github.com/apache/fory/compare/v0.11.2...v0.12.0 +从发布分支构建 Apache 源码发布包： -Please leave your comments here about this release plan. We will bump the version in repo and start the release process after the discussion. +```bash +python ci/release.py build -v ${RELEASE_VERSION} +``` -Thanks, +该命令会生成： -${name} +```text +dist/apache-fory-${RELEASE_VERSION}-src.tar.gz +dist/apache-fory-${RELEASE_VERSION}-src.tar.gz.asc +dist/apache-fory-${RELEASE_VERSION}-src.tar.gz.sha512 ``` -## 准备发布 +验证签名和 checksum： + +```bash +cd dist +gpg --verify apache-fory-${RELEASE_VERSION}-src.tar.gz.asc \ + apache-fory-${RELEASE_VERSION}-src.tar.gz +sha512sum --check apache-fory-${RELEASE_VERSION}-src.tar.gz.sha512 +cd .. +``` -如果讨论结果中没有出现反对声音，您需要做一些发布版本的准备工作。 +建议再把源码包解压到干净目录，确认 `LICENSE`、`NOTICE`、源码目录结构和基本构建都正确。 -### Github 分支和标签 +### 上传 release candidate 到 Apache dist/dev -- 创建一个名为 `releases-0.16.0` -- 通过执行命令将版本 `$version` 升级到 `python ci/release.py bump_version -l all -version $version` -- 执行 git commit 并将分支推送到 `[email protected]:apache/fory.git` -- 通过 `git tag v0.16.0-rc1` 创建一个 release 标签，然后将其推送到 `[email protected]:apache/fory.git` -- 如果本次发布包含 `go/fory` 这个 Go 子模块，还需要额外创建并推送 Go 子模块标签。例如，对于最终版 `0.16.0`，执行： +把源码包、签名和 checksum 上传到 dev distribution 仓库： ```bash -git tag go/fory/v0.16.0 -git push apache go/fory/v0.16.0 +svn co https://dist.apache.org/repos/dist/dev/fory fory-dist-dev +cd fory-dist-dev +mkdir ${RELEASE_CANDIDATE} +cp ../dist/apache-fory-${RELEASE_VERSION}-src.tar.gz* ${RELEASE_CANDIDATE}/ +svn add ${RELEASE_CANDIDATE} +svn status +svn commit -m "Prepare Apache Fory ${RELEASE_CANDIDATE}" +cd .. +``` + +检查上传后的文件： + +```text +https://dist.apache.org/repos/dist/dev/fory/${RELEASE_CANDIDATE}/ ``` -### 构建 artifacts 并上传到 SVN dist/dev 仓库 +### Stage Maven artifacts -首先，您需要通过 `python ci/release.py build -v $version` 构建预发布 artifacts。 +投票前先 stage Java、Kotlin 和 Scala artifacts。投票通过前不要 release 这个 staging repository。 -然后您需要把它上传到 svn dist repo。dev 分支的 dist 仓库地址是：https://dist.apache.org/repos/dist/dev/fory +Java： ```bash -# As this step will copy all the versions, it will take some time. If the network is broken, please use svn cleanup to delete the lock before re-execute it. -svn co https://dist.apache.org/repos/dist/dev/fory fory-dist-dev +cd java +mvn -T10 clean deploy --no-transfer-progress -DskipTests -Prelease +cd .. ``` -然后，上传项目： +Kotlin： ```bash -cd fory-dist-dev -# create a directory named by version -mkdir ${release_version}-${rc_version} -# copy source code and signature package to the versioned directory -cp ${repo_dir}/dist/* ${release_version}-${rc_version} -# check svn status -svn status -# add to svn -svn add ${release_version}-${rc_version} -# check svn status -svn status -# commit to SVN remote server -svn commit -m "Prepare for fory ${release_version}-${rc_version}" +cd kotlin +mvn -T10 clean deploy --no-transfer-progress -DskipTests -Prelease +cd .. +``` + +Scala： + +```bash +cd scala +sbt +publishSigned +sbt sonatypePrepare +sbt sonatypeBundleUpload +cd .. ``` -访问 https://dist.apache.org/repos/dist/dev/fory/ 以检查 artifacts 是否正确上传。 +然后打开 `https://repository.apache.org/#stagingRepositories`，找到 `orgapachefory-<number>` staging repository，并执行 close。把 staging repository id 记录到 `${MAVEN_STAGING_REPO}`，用于投票邮件。 + +### 创建 RC tag 和 GitHub prerelease -### 如果出现问题该怎么办 +从发布分支创建并推送 release-candidate tag： -如果某些文件是意外出现或者发生某些错误，则需要删除相关内容并执行 `svn delete`，然后重复上述上传过程。 +```bash +git checkout releases-${RELEASE_VERSION} +git tag -a v${RELEASE_CANDIDATE} -m "Apache Fory ${RELEASE_CANDIDATE}" +git push ${GIT_REMOTE} v${RELEASE_CANDIDATE} +``` -## 投票 +推送 `v*` tag 会触发 package release workflows。对于包含 `-` 的 tag，workflow 会在对应生态支持时发布 prerelease 或 staging 包，例如 Python 包发布到 TestPyPI，npm 包使用 `next` tag。请监控 GitHub Actions 运行结果；有需要时把相关链接放进投票邮件。 -新版本发布需要 Apache Fory 社区的投票。 +创建 GitHub prerelease，并按需附加源码包： -- release_version：Fory 的版本，如 0.12.0。 -- release_candidate_version：投票的版本，如 0.12.0-rc1。 -- maven_artifact_number：Maven 暂存 artifacts 的数量。如 1001. 具体来说，可以通过搜索 “fory” 来找到 maven_artifact_number https://repository.apache.org/#stagingRepositories. +```bash +gh release create v${RELEASE_CANDIDATE} \ + --repo apache/fory \ + --title "Apache Fory ${RELEASE_CANDIDATE}" \ + --prerelease \ + --notes "Release candidate for Apache Fory ${RELEASE_VERSION}." +``` -### Fory 社区投票 +## 对 release candidate 发起投票 -发送电子邮件至 Fory Community：[email protected]： +向 `[email protected]` 发送投票邮件。 标题： -``` -[VOTE] Release Apache Fory v${release_version}-${rc_version} +```text +[VOTE] Release Apache Fory v${RELEASE_CANDIDATE} ``` 内容： -``` -Hello, Apache Fory Community: +```text +Hello, Apache Fory Community, -This is a call for vote to release Apache Fory -version release-0.12.0-rc1. +This is a call for vote to release Apache Fory v${RELEASE_CANDIDATE}. -Apache Fory - A blazingly fast multi-language serialization -framework powered by JIT and zero-copy. +Apache Fory is a blazingly fast multi-language serialization framework +for idiomatic domain objects, schema IDL, and cross-language data +exchange. -The change lists about this release: +The discussion thread: +${DISCUSS_THREAD_URL} -https://github.com/apache/fory/compare/v0.12.0...v0.12.0-rc1 +The change list: +https://github.com/apache/fory/compare/v${PREVIOUS_VERSION}...v${RELEASE_CANDIDATE} -The release candidates: -https://dist.apache.org/repos/dist/dev/fory/0.12.0-rc1/ +The release candidate: +https://dist.apache.org/repos/dist/dev/fory/${RELEASE_CANDIDATE}/ -The maven staging for this release: -https://repository.apache.org/content/repositories/orgapachefory-1003 +The Maven staging repository: +https://repository.apache.org/content/repositories/${MAVEN_STAGING_REPO}/ Git tag for the release: -https://github.com/apache/fory/releases/tag/v0.12.0-rc1 - -如果本次发布还包含 Go 模块，请同时附上 Go 子模块标签： -https://github.com/apache/fory/releases/tag/go/fory/v0.16.0 +https://github.com/apache/fory/releases/tag/v${RELEASE_CANDIDATE} Git commit for the release: -https://github.com/apache/fory/commit/fae06330edd049bb960536e978a45b97bca66faf +${RELEASE_COMMIT_URL} -The artifacts signed with PGP key [5E580BA4], corresponding to -[[email protected]], that can be found in keys file: +The artifacts are signed with PGP key ${GPG_KEY_ID}, corresponding to +${YOUR_APACHE_EMAIL}. The key is available in the KEYS file: https://downloads.apache.org/fory/KEYS -The vote will be open for at least 72 hours until the necessary number of votes are reached. +The vote will be open for at least 72 hours. Please vote accordingly: @@ -310,38 +327,56 @@ Please vote accordingly: To learn more about Fory, please see https://fory.apache.org/ -*Valid check is a requirement for a vote. *Checklist for reference: +Checklist for reference: -[ ] Download Fory is valid. +[ ] Download links are valid. [ ] Checksums and PGP signatures are valid. -[ ] Source code distributions have correct names matching the current release. +[ ] Source distribution names match the release. [ ] LICENSE and NOTICE files are correct. -[ ] All files have license headers if necessary. -[ ] No compiled archives bundled in source archive. -[ ] Can compile from source. +[ ] Source files have license headers where required. +[ ] No compiled archives are bundled in the source distribution. +[ ] Source builds and tests pass. -How to Build and Test, please refer to: https://github.com/apache/fory/blob/main/docs/DEVELOPMENT.md +Build and test instructions: +https://github.com/apache/fory/blob/main/docs/DEVELOPMENT.md Thanks, -Chaokun Yang +${YOUR_NAME} ``` -在至少获得 3 + 1 且具有约束力的投票（来自 Fory Podling PMC 成员和提交者）并没有收到否决票之后，发布投票结果： +投票至少保持 72 小时，并且需要至少三个 Apache Fory PMC member 的 binding `+1`，且没有未解决的 `-1`。 -标题： +投票结束时，先回复投票线程： + +```text +Hi all, + +The vote for Apache Fory v${RELEASE_CANDIDATE} is closed now. + +Thanks to everyone who checked and voted on the release. +I will send the vote result in a separate thread. + +Best, +${YOUR_NAME} ``` -[RESULT][VOTE] Release Apache Fory v${release_version}-${rc_version} + +然后发送投票结果邮件。 + +标题： + +```text +[RESULT][VOTE] Release Apache Fory v${RELEASE_CANDIDATE} ``` 内容： -``` +```text Hello, Apache Fory Community, -The vote to release Apache Fory v${release_version}-${rc_version} has passed. +The vote to release Apache Fory v${RELEASE_CANDIDATE} has passed. -The vote PASSED with 3 binding +1 and 0 -1 vote: +The vote PASSED with 3 binding +1 votes and 0 -1 votes: Binding votes: @@ -349,83 +384,159 @@ Binding votes: - yyy - zzz -Vote thread: ${vote_thread_url} +Vote thread: ${VOTE_THREAD_URL} Thanks, +${YOUR_NAME} +``` + +## 如果投票失败 + +如果投票失败： + +1. 在 Nexus 中 drop Maven staging repository。 +2. 使用 `svn delete` 从 Apache dist/dev 删除该 candidate。 +3. 如果不应该继续展示 GitHub prerelease 和 RC tag，也删除它们。 +4. 修复问题。 +5. 递增 `${RC_VERSION}`，重新准备新的 candidate 并再次进入投票流程。 + +## 发布正式版本 + +### 将源码包移动到 Apache dist/release + +投票通过后，把通过投票的源码包从 dev 移到 release： -${name} +```bash +svn mv \ + https://dist.apache.org/repos/dist/dev/fory/${RELEASE_CANDIDATE} \ + https://dist.apache.org/repos/dist/release/fory/${RELEASE_VERSION} \ + -m "Release Apache Fory ${RELEASE_VERSION}" ``` -### 如果投票失败怎么办 +等待发布在 Apache mirror 和 archive 可见： + +```text +https://downloads.apache.org/fory/${RELEASE_VERSION}/ +https://archive.apache.org/dist/fory/${RELEASE_VERSION}/ +``` -如果投票失败，请单击“删除”以删除暂存的 Maven artifacts。 +不再需要的 release-candidate 目录应从 `dist/dev` 清理。新版本归档后，根据 Apache distribution policy 从 `dist/release` 删除旧版本。 -解决提出的问题，然后再次提出 `rc_version` 的新投票。 +### Release Maven artifacts -## 官方发布 +打开 `https://repository.apache.org/#stagingRepositories`，找到 `${MAVEN_STAGING_REPO}`，点击 `Release`。 -### 将 artifacts 发布到 SVN 发布目录 +### 创建最终 GitHub release tag -- release_version：Fory 的发布版本，如 0.12.0 -- release_candidate_version：投票版本，如 0.12.0-rc1 +从通过投票的 commit 创建并推送最终 tag： ```bash -svn mv https://dist.apache.org/repos/dist/dev/fory/${release_version}-${rc_version} https://dist.apache.org/repos/dist/release/fory/${release_version} -m "Release fory ${release_version}" +git checkout releases-${RELEASE_VERSION} +git tag -a v${RELEASE_VERSION} -m "Apache Fory ${RELEASE_VERSION}" +git push ${GIT_REMOTE} v${RELEASE_VERSION} ``` -### 更改 Fory 网站下载链接 +创建最终 GitHub release： -提交 PR 到 https://github.com/apache/fory-site 仓库更新 Fory 版本，[下载页面](https://fory.apache.org/download) +```bash +gh release create v${RELEASE_VERSION} \ + --repo apache/fory \ + --title "Apache Fory ${RELEASE_VERSION}" \ + --notes "Apache Fory ${RELEASE_VERSION} release." +``` -### 发布 Maven artifacts +最终的 `v${RELEASE_VERSION}` tag 会触发 Python、compiler、JavaScript、Rust、Dart 和 C# 的包发布 workflows。发送发布公告前，请监控所有 workflow 直到完成。 -- maven_artifact_number：Maven 暂存 artifacts 的数量。如 1001。 -- 打开https://repository.apache.org/#stagingRepositories. -- 找到 artifacts `orgapachefory-${maven_artifact_number}`，点击“发布”。 +如果本次发布包含 `go/fory` 下的 Go module，请在投票通过后同时创建并推送 Go 子模块 tag： -### 发送公告 +```bash +git tag go/fory/v${RELEASE_VERSION} +git push ${GIT_REMOTE} go/fory/v${RELEASE_VERSION} +``` -将发布公告发送给 [email protected] 并且抄送给 [email protected]。 +### 将 main 分支更新到下一个开发版本 -标题： +发布完成后，把 main 分支更新到下一个开发版本： +```bash +git checkout main +git pull --ff-only ${GIT_REMOTE} main +python ci/release.py bump_version -l all -version ${NEXT_DEV_VERSION} ``` -[ANNOUNCE] Apache Fory ${release_version} released + +版本更新后检查面向用户的安装示例。包元数据应该移动到下一个开发版本，但 README 和 guide 中面向用户的安装示例如果表示“最新稳定版”，应继续展示刚发布的版本。 + +向 `apache/fory` 提交后续 PR。 + +### 更新网站和文档 + +向 `https://github.com/apache/fory-site` 提交 PR，更新面向发布的官网内容： + +- Release blog post +- Download page 和 checksum/signature 示例 +- Current install docs 和各语言 guide 中的版本示例 +- Release blog 和变更文档的 zh-CN 翻译 +- `${RELEASE_VERSION}` 的 versioned docs snapshot +- `versions.json` 和 `docusaurus.config.ts` 默认 docs 版本 + +合并前请构建站点，并验证英文和中文发布页面。 + +### 发送发布公告 + +Apache mirror、包发布、GitHub release 和网站更新完成后，向 `[email protected]` 发送公告，并抄送 `[email protected]`。 + +标题： + +```text +[ANNOUNCE] Apache Fory ${RELEASE_VERSION} released ``` 内容： -``` +```text Hi all, -The Apache Fory community is pleased to announce -that Apache Fory {release_version} has been released! +The Apache Fory community is pleased to announce that Apache Fory +${RELEASE_VERSION} is now available. + +Apache Fory is a blazingly fast multi-language serialization framework +for idiomatic domain objects, schema IDL, and cross-language data +exchange. + +This release includes ${PR_COUNT} PRs from ${CONTRIBUTOR_COUNT} contributors. + +Highlights in ${RELEASE_VERSION} include: + +- ... + +Release blog, with details and examples: +https://fory.apache.org/blog/fory_${RELEASE_VERSION_WITH_UNDERSCORES}_release -Apache Fory - A blazingly fast multi-language serialization -framework powered by JIT and zero-copy. +Release notes: +https://github.com/apache/fory/releases/tag/v${RELEASE_VERSION} -The release notes are available here: -https://github.com/apache/fory/releases/tag/v${release_version} +Complete change list: +https://github.com/apache/fory/compare/v${PREVIOUS_VERSION}...v${RELEASE_VERSION} -For the complete list of changes: -https://github.com/apache/fory/compare/v0.12.0...v${release_version} +Apache Fory website: +https://fory.apache.org/ -Apache Fory website: https://fory.apache.org/ +Download links: +https://fory.apache.org/download -Download Links: https://fory.apache.org/download +Fory resources: -Fory Resources: -- Fory github repo: https://github.com/apache/fory -- Issue: https://github.com/apache/fory/issues +- GitHub repo: https://github.com/apache/fory +- Issue tracker: https://github.com/apache/fory/issues - Mailing list: [email protected] -We are looking to grow our community and welcome new contributors. If -you are interested in contributing to Fory, please contact us on the -mailing list or on GitHub. We will be happy to help you get started. +Thanks to everyone in the community who contributed to this release. +We welcome new contributors. If you are interested in contributing to +Fory, please contact us on the mailing list or on GitHub. ------------------ Best Regards, -${your_name} +${YOUR_NAME} ``` -至此，整个发布流程结束。 +发布公告发送后，整个发布流程完成。 diff --git a/versioned_docs/version-1.0.0/community/how_to_release.md b/versioned_docs/version-1.0.0/community/how_to_release.md index ae29da7724..c13e12f4e0 100644 --- a/versioned_docs/version-1.0.0/community/how_to_release.md +++ b/versioned_docs/version-1.0.0/community/how_to_release.md @@ -4,455 +4,320 @@ sidebar_position: 0 id: how_to_release --- -This document mainly introduces how the release manager releases a new version of Apache Fory™. +This document describes how a release manager prepares, votes, publishes, and announces an Apache Fory™ release. -## Introduction +## Release principles -Source Release is the most important part which Apache values. +- The official Apache release artifact is the source distribution hosted on Apache dist. +- Release candidates must be voted on by the Apache Fory community before they become an official release. +- Do not publish final release artifacts, update the public website as released, or send the announcement until the vote has passed. +- Keep the release version, release-candidate version, and next development version separate. -Please pay more attention to license and signing issues. -Publishing software is a serious thing and has legal consequences. +## Variables used below -## First-time as a release manager +Replace these values before running commands: -### Environmental requirements - -This release process is operated in the Ubuntu OS, and the following tools are required: - -- JDK 1.8 -- Apache Maven 3.x -- Python 3.8 -- GnuPG 2.x -- Git -- SVN (apache uses svn to host project releases) -- Pay attention to setting environment variables: if you configure gpg keys under a different directory, - please `export GNUPGHOME=$(xxx)` +```bash +export RELEASE_VERSION=1.0.0 +export PREVIOUS_VERSION=0.17.0 +export RC_VERSION=rc1 +export RELEASE_CANDIDATE=${RELEASE_VERSION}-${RC_VERSION} +export NEXT_DEV_VERSION=1.1.0-dev +export GIT_REMOTE=apache +export GPG_KEY_ID=<your-gpg-key-id> +export MAVEN_STAGING_REPO=orgapachefory-1000 +``` -### Prepare GPG Key +Use the current release values instead of the examples above. The code version must not contain `rc`; only the tag and SVN release-candidate directory use `${RC_VERSION}`. -If you are the first to become a release manager, you need to prepare a gpg key. +Unless noted otherwise, run repository commands from the root of the `apache/fory` repository. Confirm that `${GIT_REMOTE}` points to `[email protected]:apache/fory.git` before pushing branches or tags. -Following is a quick setup, you can refer to [Apache openpgp doc](https://infra.apache.org/openpgp.html) for further -details. +## First-time setup for release managers -#### Install GPG +### Tools -```bash -sudo apt install gnupg2 -``` +Install the tools needed for the source release and for the languages you plan to verify: -#### Generate GPG Key +- JDK 17+ +- Apache Maven 3.6.3+ +- CPython 3.8+ +- GnuPG 2.x +- Git +- SVN +- Optional package verification tools: Node.js LTS and npm, Rust via rustup, Go 1.24+, Dart, .NET SDK 8.0+, and sbt -Please use your apache name and email for generate key +See the [development guide](https://github.com/apache/fory/blob/main/docs/DEVELOPMENT.md) for language-specific build requirements. -```bash -$ gpg --full-gen-key -gpg (GnuPG) 2.2.20; Copyright (C) 2020 Free Software Foundation, Inc. -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. - -Please select what kind of key you want: - (1) RSA and RSA (default) - (2) DSA and Elgamal - (3) DSA (sign only) - (4) RSA (sign only) - (14) Existing key from card -Your selection? 1 # input 1 -RSA keys may be between 1024 and 4096 bits long. -What keysize do you want? (2048) 4096 # input 4096 -Requested keysize is 4096 bits -Please specify how long the key should be valid. - 0 = key does not expire - <n> = key expires in n days - <n>w = key expires in n weeks - <n>m = key expires in n months - <n>y = key expires in n years -Key is valid for? (0) 0 # input 0 -Key does not expire at all -Is this correct? (y/N) y # input y - -GnuPG needs to construct a user ID to identify your key. - -Real name: Chaokun Yang # input your name -Email address: [email protected] # input your email -Comment: CODE SIGNING KEY # input some annotations, optional -You selected this USER-ID: - "Chaokun <[email protected]>" - -Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O # input O -We need to generate a lot of random bytes. It is a good idea to perform -some other action (type on the keyboard, move the mouse, utilize the -disks) during the prime generation; this gives the random number -generator a better chance to gain enough entropy. -We need to generate a lot of random bytes. It is a good idea to perform -some other action (type on the keyboard, move the mouse, utilize the -disks) during the prime generation; this gives the random number -generator a better chance to gain enough entropy. - -# Input the security key -┌──────────────────────────────────────────────────────┐ -│ Please enter this passphrase │ -│ │ -│ Passphrase: _______________________________ │ -│ │ -│ <OK> <Cancel> │ -└──────────────────────────────────────────────────────┘ -# key generation will be done after your inputting the key with the following output -gpg: key E49B00F626B marked as ultimately trusted -gpg: revocation certificate stored as '/Users/chaokunyang/.gnupg/openpgp-revocs.d/1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4.rev' -public and secret key created and signed. - -pub rsa4096 2022-07-12 [SC] - 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4 -uid [ultimate] Chaokun <[email protected]> -sub rsa4096 2022-07-12 [E] -``` - -#### Upload your public key to public GPG keyserver - -Firstly, list your key: +If your GPG home is not the default directory, export it before signing: ```bash -gpg --list-keys +export GNUPGHOME=<path-to-your-gnupg-home> ``` -The output is like: +### Prepare a GPG key + +If this is your first release, create a GPG key with your Apache name and email. See the [Apache OpenPGP guide](https://infra.apache.org/openpgp.html) and [release signing guide](https://infra.apache.org/release-signing.html). ```bash --------------------------------------------------- -pub rsa4096 2024-03-27 [SC] - 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4 -uid [ultimate] chaokunyang (CODE SIGNING KEY) <[email protected]> -sub rsa4096 2024-03-27 [E] +gpg --full-gen-key +gpg --list-keys +gpg --keyserver keys.openpgp.org --send-key ${GPG_KEY_ID} ``` -Then, send your key id to key server: +Add the public key to the Apache Fory KEYS file: ```bash -gpg --keyserver keys.openpgp.org --send-key <key-id> # e.g., 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4 +svn co --depth=files https://dist.apache.org/repos/dist/release/fory fory-dist-release +cd fory-dist-release +(gpg --list-sigs [email protected] && \ + gpg --export --armor [email protected]) >> KEYS +svn status +svn add KEYS 2>/dev/null || true +svn commit -m "Add release key for <your name>" ``` -Among them, `keys.openpgp.org` is a randomly selected keyserver, you can use keyserver.ubuntu.com or any other -full-featured keyserver. - -#### Check whether the key is created successfully - -Uploading takes about one minute; after that, you can check by email at the corresponding keyserver. - -Uploading keys to the keyserver is mainly for joining -a [Web of Trust](https://infra.apache.org/release-signing.html#web-of-trust). +Also add the GPG key to your GitHub account and make sure the email address is verified. -#### Add your GPG public key to the project KEYS file +### Configure Maven publishing credentials -The svn repository of the release branch is: https://dist.apache.org/repos/dist/release/fory +Before staging Java, Kotlin, or Scala artifacts, configure your Apache Nexus credentials in `~/.m2/settings.xml`. Use encrypted Maven passwords; do not store plain-text passwords. -Please add the public key to KEYS in the release branch: - -```bash -svn co --depth=files https://dist.apache.org/repos/dist/release/fory fory-dist -cd fory-dist -(gpg --list-sigs [email protected] && gpg --export --armor [email protected]) >> KEYS # Append your key to the KEYS file -svn add . # It is not needed if the KEYS document exists before. -svn ci -m "add gpg key for YOUR_NAME" # Later on, if you are asked to enter a username and password, just use your apache username and password. +```xml +<servers> + <server> + <id>apache.snapshots.https</id> + <username>your-apache-username</username> + <password>{your-encrypted-password}</password> + </server> + <server> + <id>apache.releases.https</id> + <username>your-apache-username</username> + <password>{your-encrypted-password}</password> + </server> +</servers> ``` -#### Upload the GPG public key to your GitHub account +See [Publishing Maven Artifacts](https://infra.apache.org/publishing-maven-artifacts.html) for Maven password encryption. -- Enter https://github.com/settings/keys to add your GPG key. -- Please remember to bind the email address used in the GPG key to your GitHub - account (https://github.com/settings/emails) if you find "unverified" after adding it. +### Check registry publishing access -### Further reading +Fory uses GitHub Actions to publish ecosystem packages from release tags. Before pushing any `v*` release tag, verify that the repository publishing setup is healthy for the packages included in the release: -It's recommended but not mandatory to read following documents before making a release to know more details about apache -release: +- Python wheels: `Build Containerized Release Wheels`, `Build Native Release Wheels`, and `Publish Python` +- Compiler package: `Publish Compiler` +- JavaScript packages: `Publish JavaScript` +- Rust crates: `Publish Rust` +- Dart package: `Publish Dart` +- C# package: `Publish C#` -- Release policy: https://www.apache.org/legal/release-policy.html -- TLP release: https://infra.apache.org/release-distribution -- Release sign: https://infra.apache.org/release-signing.html -- Release publish: https://infra.apache.org/release-publishing.html -- Release download pages: https://infra.apache.org/release-download-pages.html -- Publishing maven artifacts: https://infra.apache.org/publishing-maven-artifacts.html +Tags starting with `go/fory` are intentionally skipped by the tag publishing workflows. Push a Go module tag only when the Go module should be published for the final release. -## Start discussion about the release +## Start the release discussion -Start a discussion about the next release via sending email to: [email protected]: +Start a discussion on `[email protected]`. -Title: +Subject: -``` -[DISCUSS] Release Apache Fory ${release_version} +```text +[DISCUSS] Release Apache Fory ${RELEASE_VERSION} ``` Content: -``` +```text Hello, Apache Fory Community, -This is a call for a discussion to release Apache Fory version ${release_version}. +This is a call for discussion to release Apache Fory ${RELEASE_VERSION}. -The change lists about this release: +The planned change list is: +https://github.com/apache/fory/compare/v${PREVIOUS_VERSION}...main -https://github.com/apache/fory/compare/v0.12.0...v0.12.1-rc1 - -Please leave your comments here about this release plan. We will bump the version in repo and start the release process after the discussion. +Please leave your comments on this release plan. If there are no +blocking concerns, I will prepare the release candidate and start the +vote. Thanks, - -${name} +${YOUR_NAME} ``` -## Preparing for release - -If the discussion goes positive, you will need to prepare the release artifiacts. +## Prepare the release candidate -### Github branch and tag +### Create the release branch and bump versions -- Create a new branch named `releases-0.16.0` -- Bump version to `$version` by executing command `python ci/release.py bump_version -l all -version $version` -- Make a git commit and push the branch to `[email protected]:apache/fory.git` -- Create a new release tag by `git tag v0.16.0-rc1`, then push it to `[email protected]:apache/fory.git` -- If the Go module under `go/fory` is part of this release, create and push the Go submodule tag as well. For example, for the final `0.16.0` release: +Start from a clean main branch: ```bash -git remote add apache [email protected]:apache/fory.git -git tag go/fory/v0.16.0 -git push apache go/fory/v0.16.0 +git checkout main +git pull --ff-only ${GIT_REMOTE} main +git status --short ``` -### Build and upload artifacts to SVN dist/dev repo - -First you need to build source release artifacts by `python ci/release.py build -v $version`. - -Then you need to upload it to svn dist repo. The dist repo of the dev branch -is: https://dist.apache.org/repos/dist/dev/fory +Create the release branch and bump all package versions: ```bash -# As this step will copy all the versions, it will take some time. If the network is broken, please use svn cleanup to delete the lock before re-execute it. -svn co https://dist.apache.org/repos/dist/dev/fory fory-dist-dev +python ci/release.py prepare -v ${RELEASE_VERSION} +git push ${GIT_REMOTE} releases-${RELEASE_VERSION} ``` -Then, upload the artifacts: +If the branch already exists, check it out and run the version bump directly: ```bash -cd fory-dist-dev -# create a directory named by version -mkdir ${release_version}-${rc_version} -# copy source code and signature package to the versioned directory -cp ${repo_dir}/dist/* ${release_version}-${rc_version} -# check svn status -svn status -# add to svn -svn add ${release_version}-${rc_version} -# check svn status -svn status -# commit to SVN remote server -svn commit -m "Prepare for fory ${release_version}-${rc_version}" +git checkout releases-${RELEASE_VERSION} +python ci/release.py bump_version -l all -version ${RELEASE_VERSION} +git add -u +git commit -m "Prepare release ${RELEASE_VERSION}" +git push ${GIT_REMOTE} releases-${RELEASE_VERSION} ``` -Visit https://dist.apache.org/repos/dist/dev/fory/ to check the artifacts are uploaded correctly. - -### What to do if something goes wrong - -If some files are unexpected, you need to remove by `svn delete` and repeat the above upload process. - -## Voting - -### check version - -Fory requires votes from the Fory Community. - -- release_version: the version for fory, like 0.12.0. -- release_candidate_version: the version for voting, like 0.12.0-rc1. -- maven_artifact_number: the number for Maven staging artifacts, like 1001. Specifically, the maven_artifact_number can - be found by searching "fory" on https://repository.apache.org/#stagingRepositories. - -### Build the source code of fory and release it to nexus - -#### Configure Apache Account Passwords +Run the required tests for the release scope. At minimum, follow the build commands in the development guide and make sure the release branch CI is green. -Before publishing Fory to Nexus, you need to securely configure your Apache account credentials. This step is critical -as passwords must be encrypted. +### Build and verify the source artifact -First, open your Maven global settings file `settings.xml`, typically located at `~/.m2/settings.xml`. Add or modify the -following section: +Build the Apache source release artifact from the release branch: -```xml - -<servers> - <server> - <id>apache.snapshots.https</id> - <username>your-apache-username</username> - <password>{your-encrypted-password}</password> - </server> - <server> - <id>apache.releases.https</id> - <username>your-apache-username</username> - <password>{your-encrypted-password}</password> - </server> -</servers> +```bash +python ci/release.py build -v ${RELEASE_VERSION} ``` -**Important Notes:** - -- Replace `your-apache-username` with your Apache LDAP username -- Passwords must be encrypted using Maven's password encryption tool -- Encrypted passwords should be enclosed in curly braces `{}` - -Refer to the official documentation for detailed encryption -instructions: [Publishing Maven Artifacts](https://infra.apache.org/publishing-maven-artifacts.html) +This creates: -Steps to encrypt your password: - -1. Generate a master password (if you haven't already): - -2. ```sh - - mvn --encrypt-master-password your-master-password - - ``` +```text +dist/apache-fory-${RELEASE_VERSION}-src.tar.gz +dist/apache-fory-${RELEASE_VERSION}-src.tar.gz.asc +dist/apache-fory-${RELEASE_VERSION}-src.tar.gz.sha512 +``` - Save the output to `~/.m2/settings-security.xml`: +Verify the signature and checksum: -3. ```xml +```bash +cd dist +gpg --verify apache-fory-${RELEASE_VERSION}-src.tar.gz.asc \ + apache-fory-${RELEASE_VERSION}-src.tar.gz +sha512sum --check apache-fory-${RELEASE_VERSION}-src.tar.gz.sha512 +cd .. +``` - <settingsSecurity> - <master>{your-encrypted-master-password}</master> - </settingsSecurity> +It is also recommended to unpack the source archive in a clean directory and confirm that `LICENSE`, `NOTICE`, source layout, and basic builds are correct. - ``` +### Upload the release candidate to Apache dist/dev -4. Encrypt your Apache account password: +Upload the source artifact, signature, and checksum to the dev distribution repository: - ```sh +```bash +svn co https://dist.apache.org/repos/dist/dev/fory fory-dist-dev +cd fory-dist-dev +mkdir ${RELEASE_CANDIDATE} +cp ../dist/apache-fory-${RELEASE_VERSION}-src.tar.gz* ${RELEASE_CANDIDATE}/ +svn add ${RELEASE_CANDIDATE} +svn status +svn commit -m "Prepare Apache Fory ${RELEASE_CANDIDATE}" +cd .. +``` - mvn --encrypt-password your-apache-password +Check the uploaded files at: - ``` +```text +https://dist.apache.org/repos/dist/dev/fory/${RELEASE_CANDIDATE}/ +``` - Place the encrypted output into the `password` field in `settings.xml` +### Stage Maven artifacts -#### Build and Publish Java Module +Stage Java, Kotlin, and Scala artifacts before the vote. Do not release the staging repository until the vote passes. -```sh +Java: -# Navigate to the Java module directory +```bash cd java - -# Execute Maven build and deploy to Nexus -# -T10: Use 10 threads for parallel build, improving speed -# clean: Clean the project -# deploy: Deploy to remote repository -# -Papache-release: Activate apache-release profile -# -DskipTests: Skip tests -# -Dgpg.skip=false: Enable GPG signing (required for release verification) -mvn -T10 clean deploy -Papache-release -DskipTests -Dgpg.skip=false - +mvn -T10 clean deploy --no-transfer-progress -DskipTests -Prelease +cd .. ``` -#### Build and Publish Kotlin Module - -```sh - -# Return to project root and navigate to Kotlin module -cd ../kotlin - -# Execute the same Maven command as Java module -# Configuration parameters are identical to Java module -mvn -T10 clean deploy -Papache-release -DskipTests -Dgpg.skip=false +Kotlin: +```bash +cd kotlin +mvn -T10 clean deploy --no-transfer-progress -DskipTests -Prelease +cd .. ``` -#### Build and Publish Scala Module - -```sh +Scala: -# Return to project root and navigate to Scala module -cd ../scala - -# Build and sign JARs for all Scala versions -# +publishSigned: Execute publishSigned for all configured Scala versions -echo "Starting to build Scala JARs..." +```bash +cd scala sbt +publishSigned - -# Prepare for upload to Sonatype (Nexus) -# sonatypePrepare: Prepare for Maven Central Repository release -echo "Starting upload preparation..." sbt sonatypePrepare - -# Upload packaged JARs to Sonatype -# sonatypeBundleUpload: Upload prepared bundles -echo "Starting JAR upload..." sbt sonatypeBundleUpload - -echo "Scala JAR deployment succeeded!" - +cd .. ``` -#### Lock the Release in Nexus +Then open `https://repository.apache.org/#stagingRepositories`, find the `orgapachefory-<number>` staging repository, and close it. Record the staging repository id in `${MAVEN_STAGING_REPO}` for the vote email. + +### Create the RC tag and GitHub prerelease -After completing the publication of all modules, perform the following steps in Nexus: +Create and push the release-candidate tag from the release branch: -1. Log in to the Apache Nexus repository management interface -2. Navigate to the "Snapshots" or "Releases" repository (depending on your release type) -3. Locate the latest Fory project version -4. Execute the "Close" operation to validate all uploaded artifacts -5. After successful validation, execute the "Release" operation to finalize the deployment +```bash +git checkout releases-${RELEASE_VERSION} +git tag -a v${RELEASE_CANDIDATE} -m "Apache Fory ${RELEASE_CANDIDATE}" +git push ${GIT_REMOTE} v${RELEASE_CANDIDATE} +``` -These steps ensure all published artifacts are verified and correctly deployed to the public repository. +Pushing a `v*` tag triggers the package release workflows. For tags that contain `-`, workflows publish prerelease or staging packages where the ecosystem supports it, for example TestPyPI for Python packages and the `next` tag for npm packages. Monitor the GitHub Actions runs and include relevant links in the vote email when useful. -### build a Pre-release +Create a GitHub prerelease for the candidate and attach the source artifacts if needed: -You need to build a Pre-release before voting, such as: -https://github.com/apache/fory/releases/tag/v0.12.0-rc1 +```bash +gh release create v${RELEASE_CANDIDATE} \ + --repo apache/fory \ + --title "Apache Fory ${RELEASE_CANDIDATE}" \ + --prerelease \ + --notes "Release candidate for Apache Fory ${RELEASE_VERSION}." +``` -### Fory Community Vote +## Vote on the release candidate -you need send a email to Fory Community: [email protected]: +Send the vote email to `[email protected]`. -Title: +Subject: -``` -[VOTE] Release Apache Fory v${release_version}-${rc_version} +```text +[VOTE] Release Apache Fory v${RELEASE_CANDIDATE} ``` Content: -``` -Hello, Apache Fory Community: +```text +Hello, Apache Fory Community, -This is a call for vote to release Apache Fory -version release-${release_version}-${rc_version}. +This is a call for vote to release Apache Fory v${RELEASE_CANDIDATE}. -Apache Fory - A blazingly fast multi-language serialization -framework powered by JIT and zero-copy. +Apache Fory is a blazingly fast multi-language serialization framework +for idiomatic domain objects, schema IDL, and cross-language data +exchange. The discussion thread: -https://lists.apache.org/thread/xxr3od301g6v3ndj14zqc05byp9qvclh +${DISCUSS_THREAD_URL} -The change lists about this release: -https://github.com/apache/fory/compare/v0.12.0...v0.12.1-rc1 +The change list: +https://github.com/apache/fory/compare/v${PREVIOUS_VERSION}...v${RELEASE_CANDIDATE} -The release candidates: -https://dist.apache.org/repos/dist/dev/fory/0.5.0-rc3/ +The release candidate: +https://dist.apache.org/repos/dist/dev/fory/${RELEASE_CANDIDATE}/ -The maven staging for this release: -https://repository.apache.org/content/repositories/orgapachefory-1003 +The Maven staging repository: +https://repository.apache.org/content/repositories/${MAVEN_STAGING_REPO}/ Git tag for the release: -https://github.com/apache/fory/releases/tag/v0.12.0-rc1 - -If this release also publishes the Go module, include the Go submodule tag too: -https://github.com/apache/fory/releases/tag/go/fory/v0.16.0 +https://github.com/apache/fory/releases/tag/v${RELEASE_CANDIDATE} Git commit for the release: -https://github.com/apache/fory/commit/fae06330edd049bb960536e978a45b97bca66faf +${RELEASE_COMMIT_URL} -The artifacts signed with PGP key [5E580BA4], corresponding to -[[email protected]], that can be found in keys file: +The artifacts are signed with PGP key ${GPG_KEY_ID}, corresponding to +${YOUR_APACHE_EMAIL}. The key is available in the KEYS file: https://downloads.apache.org/fory/KEYS -The vote will be open for at least 72 hours until the necessary number of votes are reached. +The vote will be open for at least 72 hours. Please vote accordingly: @@ -462,55 +327,56 @@ Please vote accordingly: To learn more about Fory, please see https://fory.apache.org/ -*Valid check is a requirement for a vote. *Checklist for reference: +Checklist for reference: -[ ] Download Fory is valid. +[ ] Download links are valid. [ ] Checksums and PGP signatures are valid. -[ ] Source code distributions have correct names matching the current release. +[ ] Source distribution names match the release. [ ] LICENSE and NOTICE files are correct. -[ ] All files have license headers if necessary. -[ ] No compiled archives bundled in source archive. -[ ] Can compile from source. - -How to Build and Test, please refer to: https://github.com/apache/fory/blob/main/docs/DEVELOPMENT.md +[ ] Source files have license headers where required. +[ ] No compiled archives are bundled in the source distribution. +[ ] Source builds and tests pass. +Build and test instructions: +https://github.com/apache/fory/blob/main/docs/DEVELOPMENT.md Thanks, -${name} +${YOUR_NAME} ``` -After at least 3 +1 binding vote (from Fory Podling PMC member and committers) and no veto, -first, reply to the above voting thread to notify that the voting has ended. +The vote must stay open for at least 72 hours and receive at least three binding `+1` votes from Apache Fory PMC members, with no unresolved `-1` votes. -``` +When the vote closes, reply to the vote thread: + +```text Hi all, -The vote for Release Apache Fory v${release_version}-${rc_version} is closed now. +The vote for Apache Fory v${RELEASE_CANDIDATE} is closed now. -Thanks to everyone for helping checking and voting for the release. +Thanks to everyone who checked and voted on the release. -I will close the vote later in another thread. +I will send the vote result in a separate thread. Best, -${name} +${YOUR_NAME} ``` -Immediately afterward, launch a new voting thread to claim the voting results. +Then send the result email. -Title: +Subject: -``` -[RESULT][VOTE] Release Apache Fory v${release_version}-${rc_version} +```text +[RESULT][VOTE] Release Apache Fory v${RELEASE_CANDIDATE} ``` Content: -``` +```text Hello, Apache Fory Community, -The vote to release Apache Fory v${release_version}-${rc_version} has passed. +The vote to release Apache Fory v${RELEASE_CANDIDATE} has passed. -The vote PASSED with 3 binding +1 and 0 -1 vote: +The vote PASSED with 3 binding +1 votes and 0 -1 votes: Binding votes: @@ -518,128 +384,159 @@ Binding votes: - yyy - zzz -Vote thread: ${vote_thread_url} +Vote thread: ${VOTE_THREAD_URL} Thanks, - -${name} +${YOUR_NAME} ``` -### What if vote fail +## If the vote fails -If the vote failed, click "Drop" to drop the staging Maven artifacts. +If the vote fails: -Address the raised issues, then bump `rc_version` and file a new vote again. +1. Drop the Maven staging repository in Nexus. +2. Remove the candidate from Apache dist/dev with `svn delete`. +3. Delete the GitHub prerelease and RC tag if they should not remain visible. +4. Fix the issue. +5. Prepare a new candidate by incrementing `${RC_VERSION}` and repeating the release-candidate flow. -## Official Release +## Publish the official release -### Publish artifacts to SVN Release Directory +### Move source artifacts to Apache dist/release -- release_version: the release version for fory, like 0.5.0 -- release_candidate_version: the version for voting, like 0.5.0-rc1 +After the vote passes, move the voted source artifacts from dev to release: ```bash -svn mv https://dist.apache.org/repos/dist/dev/fory/${release_version}-${rc_version} https://dist.apache.org/repos/dist/release/fory/${release_version} -m "Release fory ${release_version}" +svn mv \ + https://dist.apache.org/repos/dist/dev/fory/${RELEASE_CANDIDATE} \ + https://dist.apache.org/repos/dist/release/fory/${RELEASE_VERSION} \ + -m "Release Apache Fory ${RELEASE_VERSION}" ``` -In the repository at https://dist.apache.org/repos/dist/dev/fory/, if any -outdated release_candidate_version are left behind when releasing the release_version, -please clear them to keep the dev repository tidy. +Wait until the release is visible on Apache mirrors and archive: -When `https://archive.apache.org/dist/fory/0.12.0/${release_version}` is -accessible (confirming that the release_version has been successfully released -and archived), we may clean up the previous release version in the release repository, -leaving only the current version. +```text +https://downloads.apache.org/fory/${RELEASE_VERSION}/ +https://archive.apache.org/dist/fory/${RELEASE_VERSION}/ +``` -### Update Fory&Fory-Site content +Clean old release-candidate directories from `dist/dev` when they are no longer needed. After the new release is archived, remove older releases from `dist/release` according to Apache distribution policy. -Submit a PR to https://github.com/apache/fory-site to update Fory-site. -Reference implementation: [#283](https://github.com/apache/fory-site/pull/283) -and [#285](https://github.com/apache/fory-site/pull/285). +### Release Maven artifacts -#### Update Fory-Site +Open `https://repository.apache.org/#stagingRepositories`, find `${MAVEN_STAGING_REPO}`, and click `Release`. -In general, the following two key areas need to be modified: +### Create the final GitHub release tag -1. Write a new announcement, for example: - Add a new markdown file under the blog folder: +Create the final tag from the voted commit and push it: +```bash +git checkout releases-${RELEASE_VERSION} +git tag -a v${RELEASE_VERSION} -m "Apache Fory ${RELEASE_VERSION}" +git push ${GIT_REMOTE} v${RELEASE_VERSION} ``` -The Apache Fory team is pleased to announce the [?] release. This is a major release that includes [? PR](https://github.com/apache/fory/compare/v[?]...v[?]) from ? distinct contributors. See the [Install](https://fory.apache.org/docs/start/install) Page to learn how to get the libraries for your platform. + +Create the final GitHub release: + +```bash +gh release create v${RELEASE_VERSION} \ + --repo apache/fory \ + --title "Apache Fory ${RELEASE_VERSION}" \ + --notes "Apache Fory ${RELEASE_VERSION} release." ``` -2. Replace versions by upgrading old versions to new ones. - For example, in [install](https://fory.apache.org/docs/start/install/#java) section, it is necessary to update the documentation for both the development branch and the latest release branch:: +The final `v${RELEASE_VERSION}` tag triggers package publishing workflows for Python, compiler, JavaScript, Rust, Dart, and C#. Monitor every workflow to completion before announcing the release. + +If this release publishes the Go module under `go/fory`, also create and push the Go submodule tag after the vote passes: +```bash +git tag go/fory/v${RELEASE_VERSION} +git push ${GIT_REMOTE} go/fory/v${RELEASE_VERSION} ``` -<dependency> - <groupId>org.apache.fory</groupId> - <artifactId>fory-core</artifactId> - <version>0.11.2</version> -</dependency> + +### Bump main to the next development version + +After the release is published, update the main branch to the next development version: + +```bash +git checkout main +git pull --ff-only ${GIT_REMOTE} main +python ci/release.py bump_version -l all -version ${NEXT_DEV_VERSION} ``` -#### Update Fory +Review user-facing installation snippets after the bump. Package metadata should move to the next development version, but README and guide installation examples should continue to show the latest released version where they are intended for users. -Submit a PR to https://github.com/apache/fury to update [README](https://github.com/apache/fury/blob/main/README.md), -like [#2207](https://github.com/apache/fury/pull/2207). +Submit the follow-up PR to `apache/fory`. -### Github officially released +### Update the website and documentation -You need to officially release this version in the Fory project -Reference implementation: https://github.com/apache/fory/releases/tag/v0.12.0 +Submit a PR to `https://github.com/apache/fory-site` that updates the release-facing website content: -### Release Maven artifacts +- Release blog post +- Download page and checksum/signature examples +- Current install docs and language guide version snippets +- zh-CN translations for the release blog and changed docs +- Versioned docs snapshot for `${RELEASE_VERSION}` +- `versions.json` and `docusaurus.config.ts` default docs version -- maven_artifact_number: the number for Maven staging artifacts, like 1001. -- Open https://repository.apache.org/#stagingRepositories. -- Find the artifact `orgapachefory-${maven_artifact_number}`, click "Release". +Build the site and verify the English and Chinese release pages before merging. ### Send the announcement -Send the release announcement to [email protected] and CC [email protected]. +Send the announcement to `[email protected]` and CC `[email protected]` after mirrors, package publishing, GitHub release, and the website update are complete. -Title: +Subject: -``` -[ANNOUNCE] Apache Fory ${release_version} released +```text +[ANNOUNCE] Apache Fory ${RELEASE_VERSION} released ``` Content: -``` +```text Hi all, -The Apache Fory community is pleased to announce -that Apache Fory {release_version} has been released! +The Apache Fory community is pleased to announce that Apache Fory +${RELEASE_VERSION} is now available. + +Apache Fory is a blazingly fast multi-language serialization framework +for idiomatic domain objects, schema IDL, and cross-language data +exchange. + +This release includes ${PR_COUNT} PRs from ${CONTRIBUTOR_COUNT} contributors. + +Highlights in ${RELEASE_VERSION} include: -Apache Fory - A blazingly fast multi-language serialization -framework powered by JIT and zero-copy. +- ... -The release notes are available here: -https://github.com/apache/fory/releases/tag/v${release_version} +Release blog, with details and examples: +https://fory.apache.org/blog/fory_${RELEASE_VERSION_WITH_UNDERSCORES}_release -For the complete list of changes: -https://github.com/apache/fory/compare/v0.12.0...v${release_version} +Release notes: +https://github.com/apache/fory/releases/tag/v${RELEASE_VERSION} -Apache Fory website: https://fory.apache.org/ +Complete change list: +https://github.com/apache/fory/compare/v${PREVIOUS_VERSION}...v${RELEASE_VERSION} -Download Links: https://fory.apache.org/download +Apache Fory website: +https://fory.apache.org/ -Fory Resources: -- Fory github repo: https://github.com/apache/fory -- Issue: https://github.com/apache/fory/issues +Download links: +https://fory.apache.org/download + +Fory resources: + +- GitHub repo: https://github.com/apache/fory +- Issue tracker: https://github.com/apache/fory/issues - Mailing list: [email protected] -We are looking to grow our community and welcome new contributors. If -you are interested in contributing to Fory, please contact us on the -mailing list or on GitHub. We will be happy to help you get started. +Thanks to everyone in the community who contributed to this release. +We welcome new contributors. If you are interested in contributing to +Fory, please contact us on the mailing list or on GitHub. ------------------ Best Regards, -${your_name} +${YOUR_NAME} ``` -Remember to use plain text instead of rich text format, or you may be rejected when CC [email protected] - -After completing the above steps, the Fory release process comes to an end. +The release process is complete after the announcement is sent. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
