Apache publish guide
Understand the content and process of Apache's release
Source Release is the focus of Apache’s attention and is also a required content for release; Binary Release is optional. Please refer to the following link to find more ASF release guidelines:
Tool preparation
Mainly include the preparation of the signature tool GnuPG, Maven repository certification
1. Install GPG
Download the binary installation package (GnuPG binary releases) at GnuPG official website. The commands of GnuPG 1.x version and 2.x version are slightly different. The following description takes GnuPG-2.x version as example.
$ gpg --version #Check the version, it should be 2.x
2. Generate key with gpg
According to the prompt, generate the key
Note:please use Apache mail box generate GPG Key
$ gpg --full-gen-key
gpg (GnuPG) 2.0.12; Copyright (C) 2009 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)
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 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)
Key does not expire at all
Is this correct? (y/N) y
GnuPG needs to construct a user ID to identify your key.
Real name: ${please enter the username}
Email address: ${enter the email address}
Comment: CODE SIGNING KEY
You selected this USER-ID:
"${username} (CODE SIGNING KEY) <${email address}>"
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
You need a Passphrase to protect your secret key. # enter the password for protecting your secret key
3. Check the key
$ gpg --list-keys
pub rsa4096/579C25F5 2021-04-26 # 579C25F5 is key id
uid [ultimate] ${username} <${email address}>
sub rsa4096 2021-04-26
# upload the public key to keyserver with key id
# Currently available in China: pgp.mit.edu, keyserver.ubuntu.com
$ gpg --keyserver keyserver.ubuntu.com --send-key 579C25F5
# keyserver.ubuntu.com is the corresponding keyserver, The keyserver list is: https://sks-keyservers.net/status/, which are automatically synchronized with each other, and you can choose any one.
$ gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys 579C25F5 # Verify whether it is synchronized to the public network. If the network is not good, you may need to try a few more times
Note: If there are multiple public keys, set the default key. Modify ~/.gnupg/gpg.conf
# If you have more than 1 secret key in your keyring, you may want to
# uncomment the following option and set your preferred keyid.
default-key 28681CB1
If there are multiple public keys, useless keys can also be deleted:
$ gpg --delete-secret-keys 29BBC3CB # first delete the private key and specify the key id
gpg (GnuPG) 2.2.27; Copyright (C) 2021 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
sec rsa4096/EE8DAE7D29BBC3CB 2021-04-27 mikexue <mikexue@apache.org>
Delete this key from the keyring? (y/N) y
This is a secret key! - really delete? (y/N) y
$ gpg --delete-keys 29BBC3CB # delete the public key, specify the key id
gpg (GnuPG) 2.2.27; Copyright (C) 2021 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
pub rsa4096/EE8DAE7D29BBC3CB 2021-04-27 mikexue <mikexue@apache.org>
Delete this key from the keyring? (y/N) y
Since the public key server has no checking mechanism, anyone can upload the public key in your name, so there is no way to guarantee the reliability of the public key on the server. Usually, you can publish a public key fingerprint on the website, so that others can check whether the downloaded public key is genuine.
# use fingerprint parameter generates a public key fingerprint:
$gpg --fingerprint mikexue
pub rsa4096 2021-04-26 [SCA]
F84A 0041 D70B 37AF 9C7B F0B3 39F4 29D7 579C 25F5
uid [ultimate] mikexue <mikexue@apache.org>
sub rsa4096 2021-04-26 [E]
Log in to https://id.apache.org, paste the above fingerprint (ie F84A 0041 D70B 37AF 9C7B F0B3 39F4 29D7 579C 25F5) into your user information OpenPGP Public Key Primary Fingerprint
Publish to the Apache Maven repository
Note: EventMesh is built using Gradle, and gradle-related configuration needs to be modified
1. Export private key file
$ gpg --export-secret-keys -o secring.gpg #the private key file is properly kept, and it is required for later configuration
2. Prepare branch
Pull the new branch from the master branch as the release branch. If you want to release the ${release_version}
version now, pull the new branch ${release_version}-prepare
from the master branch, and then ${release_version}
Release Candidates involves The modification and labeling of all files are carried out in the ${release_version}-prepare
branch, and merged into the main branch after the final release is completed.
3. Update the release note
Update the following files of the official website project and submit them to the master branch:
https://github.com/apache/eventmesh-site/tree/master/events/release-notes
4. Configure the gradle.properties file under the root project
group=org.apache.eventmesh
version=1.2.0-release
#the last 8 digits of the 40-digit public key
signing.keyId=579C25F5
#the passphrase filled in when generating the key
signing.password=
#the path of the exported private key file secring.gpg, absolute path, such as /home/root/secring.gpg
signing.secretKeyRingFile=/home/root/secring.gpg
#apache account
apacheUserName=
#apache password
apachePassWord=
#sign switch
signEnabled=true
5. Check the gradle.properties file under the submodule
group=org.apache.eventmesh
version=${release_version}
6. Check and configure the build.gradle file under the root project
publishing {
publications {
mavenJava(MavenPublication) {
from components.java
artifact packageSources
artifact packageJavadoc
versionMapping {
usage('java-api') {
fromResolutionOf('runtimeClasspath')
}
usage('java-runtime') {
fromResolutionResult()
}
}
pom {
name = 'EventMesh'
description = 'Apache EventMesh'
url = 'https://github.com/apache/eventmesh'
licenses {
license {
name = 'The Apache License, Version 2.0'
url = 'http://www.apache.org/licenses/LICENSE-2.0.txt'
}
}
developers {
developer {
id = 'Apache EventMesh'
name = 'Apache EventMesh of ASF'
url = 'https://eventmesh.apache.org/'
}
}
scm {
connection = 'scm:git:git@github.com:apache/eventmesh.git'
developerConnection = 'scm:git:git@github.com:apache/eventmesh.git'
url = 'https://github.com/apache/eventmesh'
}
}
}
}
repositories {
maven {
def releasesRepoUrl = 'https://repository.apache.org/service/local/staging/deploy/maven2/'
def snapshotsRepoUrl = 'https://repository.apache.org/content/repositories/snapshots/'
url = version.endsWith('SNAPSHOT') ? snapshotsRepoUrl : releasesRepoUrl
credentials {
username apacheUserName
password apachePassWord
}
}
}
}
signing {
sign publishing.publications.mavenJava
}
7. Upload release package
Execute the following command, you need to sign and encrypt files such as jar, source package, doc and pom
$ gradle signMavenJavaPublication publish
After the above command is executed successfully, the version to be released will be automatically uploaded to Apache's staging repository. All Artifacts that are deployed to the remote maven repository will be in the staging state,visit https://repository.apache.org/#stagingRepositories ,log in with Apache's LDAP account, You will see the uploaded version, and the content of the Repository
column is ${STAGING.REPOSITORY}. Click Close
to tell Nexus that the build is complete and only then will the build be usable. If there is a problem with the electronic signature, Close
will fail, and you can view the failure information through Activity
.
Publish to the Apache SVN repository
1. Prepare the svn native environment (Apache uses svn to host the published content of the project)
2. Checkout to local directory
$ svn checkout https://dist.apache.org/repos/dist/dev/eventmesh/
# the local directory is assumed to be ~/apache/eventmesh
3. Add gpg public key
Add the public key to the KEYS file and submit it to the SVN warehouse (the first time the person who publishes needs to do this operation, specifically refer to the description in the KEYS file for operation). KEYS is mainly for voters to import locally to verify the correctness of sign
Windows
$ gpg --list-sigs <your name> | out-file -append KEYS -encoding utf8
$ gpg --armor --export <your name> | out-file -append KEYS -encoding utf8
Mac OS/Linux
$ (gpg --list-sigs <your name> && gpg --armor --export <your name>) >> KEYS
4. Add packages to be published to the SVN directory
$ cd ~/apache/eventmesh # eventmesh svn root path
$ mkdir ${release_version}-${rc_version}
4.1 Create tags
Create a tag on ${release_version}-release
branch, with rc version, which is a pre-release version
$ git tag -a v{$release_version}-{$rc_version} -m "Tagging the ${release_version} first Release Candidate (Candidates start at zero)"
$ git push origin --tags
4.2 Package source code
Check the naming format of the project source package, name the source code apache-eventmesh-${release_version}-src
, and package it in tar.gz format
$ tar -czvf apache-eventmesh-${release_version}-source.tar.gz apache-eventmesh-${release_version}-src
Note: Make sure that there are no binary files in the source package, such as gradle-wrapper.jar, etc.
4.3 Build binary package
Compile the source code packaged in the previous step
Check the compiled file naming format, name the binary as apache-eventmesh-${release_version}
Note: You need to copy the
NOTICE
file in the root directory of the source code, theDISCLAIMER-WIP
file and theLICENSE
file in thetools/third-party-licenses
directory to the binary package
$ gradle clean jar dist && gradle installPlugin && gradle tar -x test
$ tar -czvf apache-eventmesh-${release_version}-bin.tar.gz apache-eventmesh-${release_version}
Compress the source package and bin package, and copy the relevant compressed packages to the svn local warehouse directory /apache/eventmesh/${release_version}-${rc_version}
5. Generate signature/sha512 file
Generate signature/sha512 files for source and binary packages
$ for i in *.tar.gz; do echo $i; gpg --print-md SHA512 $i > $i.sha512 ; done #compute sha512
$ for i in *.tar.gz; do echo $i; gpg --armor --output $i.asc --detach-sig $i ; done #compute signature
6. Commit to Apache svn
$ cd ~/apache/eventmesh # eventmesh svn root directory
$ svn status
$ svn commit -m 'prepare for ${release_version}-${rc_version}'
Verify Release Candidates
For a detailed check list, please refer to the official check list
Download the Release Candidates to be released to the local environment from the following address:
https://dist.apache.org/repos/dist/dev/eventmesh/${release_version}-${rc_version}/
Then start the verification link, which includes but is not limited to the following content and forms
1. Check information such as signature and hash
Due to different operating systems, the check command may be different. For details, please refer to Official Verification Steps
1.1 Check the sha512 hash
Mac OS/Linux
$ shasum -a apache-eventmesh-${release_version}-source.tar.gz
#and compare the output with the contents of the apache-eventmesh-${release_version}-${rc_version}-source.tar.gz.sha512 file
$ shasum -a apache-eventmesh-${release_version}-bin.tar.gz
#and compare the output with the contents of the apache-eventmesh-${release_version}-${rc_version}-bin.tar.gz.sha512 file
Windows
$ certUtil -hashfile apache-eventmesh-${release_version}-source.tar.gz SHA512
#and compare the output with the contents of the apache-eventmesh-${release_version}-${rc_version}-source.tar.gz.sha512 file
$ certUtil -hashfile apache-eventmesh-${release_version}-bin.tar.gz SHA512
#and compare the output with the contents of the apache-eventmesh-${release_version}-${rc_version}-bin.tar.gz.sha512 file
1.2 Check gpg signature
First import the release manager's public key. Import KEYS from the svn repository to the local environment. (The release manager does not need to import again, the person who helps to do the verification needs to import, and the user name can be filled with the user name of the release manager)
$ curl https://dist.apache.org/repos/dist/dev/eventmesh/KEYS >> KEYS
$ gpg --import KEYS
$ gpg --edit-key "${release manager gpg name}"
> trust
Please decide how far you trust this user to correctly verify other users' keys
(by looking at passports, checking fingerprints from different sources, etc.)
1 = I don't know or won't say
2 = I do NOT trust
3 = I trust marginally
4 = I trust fully
5 = I trust ultimately
m = back to the main menu
Your decision? 5
> save
Then check the signature with the following command
$ gpg --verify apache-eventmesh-${release_version}-source.tar.gz.asc apache-eventmesh-${release_version}-source.tar.gz
$ gpg --verify apache-eventmesh-${release_version}-bin.tar.gz.asc apache-eventmesh-${release_version}-bin.tar.gz
2. Check the file content of the source package
Unzip apache-eventmesh-${release_version}-source.tar.gz
and check as follows:
Check whether the source package contains unnecessary files, causing the tar package to be too large
Presence of
LICENSE
andNOTICE
filesExistence of
DISCLAIMER
filecorrect year in
NOTICE
fileOnly text files exist, no binary files exist
All files start with ASF license
It can be compiled correctly and the unit test can pass (./gradle build) (currently supports JAVA 8/gradle 7.0/idea 2021.1.1 and above)
Check for redundant files or folders, such as empty folders, etc.
3. Check the file content of the binary package
Presence of
LICENSE
andNOTICE
filesExistence of
DISCLAIMER
filecorrect year in
NOTICE
fileAll text files start with ASF license
Check third-party dependent licenses:
Compatibility with 3rd party dependent licenses
All 3rd party dependent licenses are declared in the
LICENSE
fileThe full versions of the dependent licenses are all in the
license
directoryIf you are relying on the Apache license and there are
NOTICE
files, then theseNOTICE
files also need to be added to the versionNOTICE
file
You can refer to this article: ASF third-party license policy
Initiates a vote
EventMesh has graduated from incubation and only needs to be voted by the community
- EventMesh community vote, send email to:
dev@eventmesh.apache.org
- In ${Your EventMesh Release Manager} in the body of the community voting email, fill in the person responsible for this release, usually the sender of the email
1. EventMesh community voting stage
- The EventMesh community votes, send a voting email to
dev@eventmesh.apache.org
. PMC needs to check the correctness of the version according to the document before voting. After at least 72 hours and counting 3+1 PMC member
votes, you can enter the next stage of voting. - Announce the voting result, and send the voting result email to
dev@eventmesh.apache.org
.
2. EventMesh community voting template
Title:
[VOTE] Release Apache EventMesh ${release_version} ${rc_version}
Content:
Hello EventMesh Community,
This is a call for vote to release Apache EventMesh version ${release_version}-${rc_version}.
Release notes:
https://github.com/apache/eventmesh/releases/tag/v${release_version}-${rc_version}
The release candidates:
https://dist.apache.org/repos/dist/dev/eventmesh/${release_version}-${rc_version}/
Maven artifacts are available in a staging repository at:
https://repository.apache.org/content/repositories/orgapacheeventmesh-{staging-id}
Git tag for the release:
https://github.com/apache/eventmesh/tree/v${release_version}-${rc_version}
Keys to verify the Release Candidate:
https://downloads.apache.org/eventmesh/KEYS
Hash for the release tag:
#hashCode of this release tag
GPG user ID:
${YOUR.GPG.USER.ID}
The vote will be open for at least 72 hours or until necessary number of votes are reached.
Please vote accordingly:
[ ] +1 approve
[ ] +0 no opinion
[ ] -1 disapprove with the reason
Checklist for reference:
[ ] Download links are valid.
[ ] Checksums and PGP signatures are valid.
[ ] Source code distributions have correct names matching the current release.
[ ] LICENSE and NOTICE files are correct for each EventMesh repo.
[ ] All files have license headers if necessary.
[ ] No compiled archives bundled in source archive.
More detail checklist please refer:
https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist
Thanks,
${Your EventMesh Release Manager}
3. Announcing voting results template
Title:
[RESULT][VOTE] Release Apache EventMesh ${release_version} ${rc_version}
Content:
Hello Apache EventMesh PMC and Community,
The vote closes now as 72hr have passed. The vote PASSES with
xx (+1 binding) votes from the PMC members,
member one
member two
member three
...
xx (+1 non-binding) votes from the rest of the developer community,
and no further 0 or -1 votes.
The vote thread: {vote_mail_address}
Many thanks for all people helping us with the release procedure. I will be working on publishing the artifacts soon.
Thank you for your support.
${Your EventMesh Release Manager}
Official release
1. Merging code branch
Merge the changes of the ${release_version}-release
branch to the master
branch, delete the release
branch after the merge is complete
$ git checkout master
$ git merge origin/${release_version}-release
$ git pull
$ git push origin master
$ git push --delete origin ${release_version}-release
$ git branch -d ${release_version}-release
2. Migrating source and binary packages
Move source and binary packages from the svn dev
directory to the release
directory
$ svn mv https://dist.apache.org/repos/dist/dev/eventmesh/${release_version}-${rc_version} https://dist.apache.org/repos/dist/release/eventmesh/ -m "transfer packages for ${release_version}-${rc_version}" #Move source and binary packages
$ svn delete https://dist.apache.org/repos/dist/release/eventmesh/KEYS -m "delete KEYS" #Clear the KEYS in the original release directory
$ svn cp https://dist.apache.org/repos/dist/dev/eventmesh/KEYS https://dist.apache.org/repos/dist/release/eventmesh/ -m "transfer KEYS for ${release_version}-${rc_version}" #Copy dev directory KEYS to release directory
3. Confirm that the packages under dev and release are correct
- Confirmed that
${release_version}-${rc_version}
under dev has been removed - Delete the release package of the previous version under the directory release, these packages will be automatically saved in [here](https:/ /archive.apache.org/dist/eventmesh/)
$ svn delete https://dist.apache.org/repos/dist/release/eventmesh/${last_release_version} -m "Delete ${last_release_version}"
4. Publish releases in the Apache Staging repository
- Log in to http://repository.apache.org, log in with your Apache account
- Click Staging repositories on the left,
- Search for the EventMesh keyword, select the warehouse you uploaded recently, and the warehouse specified in the voting email
- Click the
Release
button above, this process will perform a series of checks
It usually takes 24 hours for the warehouse to synchronize to other data sources
5. GitHub version release
Tag the commit (on which the vote happened) with the release version without
-${RELEASE_CANDIDATE}
. such as: after a successful vote onv1.2-rc5
, the hash will be tagged again withv1.2
only.Click
Edit
on the${release_version}
version of the GitHub Releases page to edit the version number and version description, and clickPublish release
6. Update download page
After waiting and confirming that the new release version is synchronized to the Apache mirror, update the following page:
https://eventmesh.apache.org/download/
https://eventmesh.apache.org/zh/download/
Download links for GPG signature files and hash verification files should use this prefix:https://downloads.apache.org/eventmesh/
Note: The project download link should use https://www.apache.org/dyn/closer.lua instead of closer.cgi or mirrors.cgi
7. Announce version is released
Please make sure that the Apache Staging warehouse has been released successfully, usually after 24 hours of this step.
Email to dev@eventmesh.apache.org
、 announce@apache.org
Title:
[ANNOUNCE] Apache EventMesh ${release_version} available
Content:
Hi all,
Apache EventMesh Team is glad to announce the new release of Apache EventMesh ${release_version}.
Apache EventMesh is a dynamic cloud-native eventing infrastructure used to decouple the application and backend middleware layer, which supports a wide range of use cases that encompass complex multi-cloud, widely distributed topologies using diverse technology stacks.
Download Links: https://eventmesh.apache.org/projects/eventmesh/download/
Release Notes: https://eventmesh.apache.org/events/release-notes/v${release_version}/
Website: https://eventmesh.apache.org/
EventMesh Resources:
- Issue: https://github.com/apache/eventmesh/issues
- Mailing list: dev@eventmesh.apache.org
Apache EventMesh Team