This is an automated email from the ASF dual-hosted git repository.
weibin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-graphar-website.git
The following commit(s) were added to refs/heads/main by this push:
new 4584bfe Update the release and verify document, and add development
document (#18)
4584bfe is described below
commit 4584bfe340e9dd589c8a0e449ba4aa10b3132f3e
Author: Weibin Zeng <[email protected]>
AuthorDate: Fri Jun 7 11:44:57 2024 +0800
Update the release and verify document, and add development document (#18)
---
community/committers/release.md | 408 ++++++++++++++++++++++++++++++++++++++--
community/committers/verify.md | 180 ++++++++++++++++++
community/development.md | 47 +++++
3 files changed, 621 insertions(+), 14 deletions(-)
diff --git a/community/committers/release.md b/community/committers/release.md
index cc59ab8..5dca493 100644
--- a/community/committers/release.md
+++ b/community/committers/release.md
@@ -1,10 +1,10 @@
---
-title: Create a release (Work in Progress)
+title: Create a release
sidebar_position: 1
---
This document mainly introduces how the release manager
-releases a new version of Apache GraphAr in accordance with the Apache
requirements.
+releases a new version in accordance with the Apache requirements.
## Introduction
@@ -43,15 +43,15 @@ Start a discussion about the next release via sending email
to: [email protected]
Title:
```
-[DISCUSS] Release Apache GraphAr(incubating) ${release_version}
+[DISCUSS] Release Apache GraphAr (incubating) ${graphar_version}
```
Content:
```
-Hello, Apache GraphAr(incubating) Community,
+Hello, GraphAr Community,
-This is a call for a discussion to release Apache GraphAr(incubating) version
${graphar_version}.
+This is a call for a discussion to release Apache GraphAr (incubating) version
${graphar_version}.
The change lists about this release:
@@ -91,18 +91,14 @@ This issue is used to track tasks of the graphar
${graphar_version} release.
- [ ] Bump version in project
- [ ] cpp
- - [ ] java
- - [ ] spark
- - [ ] pyspark
+ - [ ] scala
- [ ] Update docs
-- [ ] Generate dependencies list
- [ ] Push release candidate tag to GitHub
#### ASF Side
- [ ] Create an ASF Release
- [ ] Upload artifacts to the SVN dist repo
-- [ ] Close the Nexus staging repo
### Voting
@@ -114,7 +110,6 @@ This issue is used to track tasks of the graphar
${graphar_version} release.
- [ ] Push the release git tag
- [ ] Publish artifacts to SVN RELEASE branch
- [ ] Change GraphAr Website download link
-- [ ] Release Maven artifacts
- [ ] Send the announcement
For details of each step, please refer to:
https://graphar.apache.org/community/committers/release
@@ -128,15 +123,400 @@ Bump all components' version in the project to the new
graphar version.
Please note that this version is the exact version of the release, not the
release candidate version.
- cpp library: bump version in `cpp/CMakeLists.txt`
-- java library: bump version in `java/pom.xml`
-- spark library: bump version in `spark/pom.xml`
-- pyspark library: bump version in `pyspark/poetry.toml`
+- scala with spark library: bump version in `maven-projects/pom.xml`
### Update docs
+- Update `CHANGELOG.md` with the new version and the changes.
+
### Push release candidate tag
After bump version PR gets merged, we can create a GitHub release for the
release candidate:
- Create a tag at `main` branch on the `Bump Version` / `Patch up version`
commit: `git tag -s "v0.12.0-rc.1"`, please correctly check out the
corresponding commit instead of directly tagging on the main branch.
- Push tags to GitHub: `git push --tags`.
+
+
+## ASF Side
+
+If any step in the ASF Release process fails and requires code changes,
+we will abandon that version and prepare for the next one.
+Our release page will only display ASF releases instead of GitHub Releases.
+
+### Create an ASF Release
+
+After GitHub Release has been created, we can start to create ASF Release.
+
+- Checkout to released tag. (e.g. `git checkout v0.12.0-rc.1`, tag is created
in the previous step)
+- create a new branch for the release: `git checkout -b release-0.12.0-rc.1`
+- Use the release script to create a new release: `python
./dev/release/release.py`
+ - This script will generate the release candidate artifacts under `dist`,
including:
+ - `apache-graphar-{version}-incubating-src.tar.gz`
+ - `apache-graphar-{version}-incubating-src.tar.gz.asc`
+ - `apache-graphar-{version}-incubating-src.tar.gz.sha512`
+- Push the newly created branch to GitHub
+
+### Upload artifacts to the SVN dist repo
+
+:::info
+
+SVN is required for this step.
+
+:::
+
+The svn repository of the dev branch is:
https://dist.apache.org/repos/dist/dev/incubator/graphar
+
+First, checkout GraphAr to local directory:
+
+```shell
+# 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/incubator/graphar
graphar-dist-dev
+```
+
+Then, upload the artifacts:
+
+> The `${release_version}` here should be like `0.12.0-rc.1`
+
+```shell
+cd graphar-dist-dev
+# create a directory named by version
+mkdir ${release_version}
+# copy source code and signature package to the versioned directory
+cp ${repo_dir}/dist/* ${release_version}/
+# check svn status
+svn status
+# add to svn
+svn add ${release_version}
+# check svn status
+svn status
+# commit to SVN remote server
+svn commit -m "Prepare for ${release_version}"
+```
+
+Visit https://dist.apache.org/repos/dist/dev/incubator/graphar/ to make sure
the artifacts are uploaded correctly.
+
+### Rescue
+
+If you accidentally published wrong or unexpected artifacts, like wrong
signature files, wrong sha256 files,
+please cancel the release for the current `release_version`,
+_increase th RC counting_ and re-initiate a release with the new
`release_version`.
+And remember to delete the wrong artifacts from the SVN dist repo.
+
+## Voting
+
+GraphAr requires votes from both the GraphAr Community and the Incubator
Community.
+
+### GraphAr Community Vote
+
+GraphAr Community Vote should send email to:
[[email protected]](mailto:[email protected])
+
+Title:
+
+```
+[VOTE] Release Apache GraphAr(incubating) ${release_version} - GraphAr Vote
Round 1
+```
+
+Content:
+
+```
+Hello, Apache GraphAr(incubating) Community,
+
+This is a call for a vote to release Apache GraphAr(incubating) version
${graphar_version}.
+
+The tag to be voted on is ${graphar_version}.
+
+The release candidate:
+
+https://dist.apache.org/repos/dist/dev/incubator/graphar/${release_version}/
+
+Keys to verify the release candidate:
+
+https://downloads.apache.org/incubator/graphar/KEYS
+
+Git tag for the release:
+
+https://github.com/apache/incubator-graphar/releases/tag/v${release_version}
+
+Please download, verify, and test.
+
+The VOTE will be open for at least 72 hours and until the necessary
+number of votes are reached.
+
+[ ] +1 approve
+[ ] +0 no opinion
+[ ] -1 disapprove with the reason
+
+To learn more about apache graphar, please see https://graphar.apache.org/
+
+Checklist for reference:
+
+[ ] Download links are valid.
+[ ] Checksums and PGP signatures are valid.
+[ ] Source code distribution have correct names matching the current release.
+[ ] LICENSE/NOTICE files exist and are correct.
+[ ] No unexpected binary files bundled in the source archive.
+[ ] All source files have ASF headers.
+[ ] Can compile from source.
+
+More detailed checklist please refer to:
+
+https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist
+
+Use our verify.py to assist in the verify process:
+
+svn co
https://dist.apache.org/repos/dist/dev/incubator/graphar/${release_version}/
graphar-dev
+cd graphar-dev
+curl -sSL
https://github.com/apache/incubator-graphar/raw/v${release_version}/scripts/verify.py
-o verify.py
+python verify.py
+
+How to Build:
+
+
+Thanks
+
+${name}
+```
+
+> Tips: The 72 hours is the minimum time for voting, so we can ensure that
community members from various time zones can participate in the verification
process.
+
+After at least 3 `+1` binding vote ([from GraphAr Podling PMC
member](https://people.apache.org/phonebook.html?podling=graphar)) and no veto,
claim the vote result:
+
+Title:
+
+```
+[RESULT][VOTE] Release Apache GraphAr(incubating) ${release_version} - GraphAr
Vote Round 1
+```
+
+Content:
+
+```
+Hello, Apache GraphAr(incubating) Community,
+
+The vote to release Apache GraphAr(incubating) ${release_version} has passed.
+
+The vote PASSED with 3 +1 binding and 1 +1 non-binding votes, no +0 or -1
votes:
+
+Binding votes:
+
+- xxx
+- yyy
+- zzz
+
+Non-Binding votes:
+
+- aaa
+
+Vote thread: ${vote_thread_url}
+
+Thanks
+
+${name}
+```
+
+It's better to use the real name or the public name which is displayed on the
voters' profile page,
+or Apache ID of the voter, to show who voted in the vote result email,
+and avoid using nicknames, it will make the vote result hard for others to
track the voter.
+We should make sure the binding votes are from the people who have the right
to vote the binding one.
+
+### Incubator Community Vote
+
+Incubator Community Vote should send email to:
[[email protected]](mailto:[email protected]):
+
+Title:
+
+```
+[VOTE] Release Apache GraphAr(incubating) ${release_version} - Incubator Vote
Round 1
+```
+
+Content:
+
+```
+Hello Incubator PMC,
+
+The Apache GraphAr community has voted and approved the release of Apache
+GraphAr(incubating) ${release_version}. We now kindly request the IPMC members
+review and vote for this release.
+
+ is a data access layer that allows users to easily and efficiently
+retrieve data from various storage services in a unified way.
+
+GraphAr community vote thread:
+
+${community_vote_thread_url}
+
+Vote result thread:
+
+${community_vote_result_thread_url}
+
+The release candidate:
+
+https://dist.apache.org/repos/dist/dev/incubator/graphar/${release_version}/
+
+This release has been signed with a PGP available here:
+
+https://downloads.apache.org/incubator/graphar/KEYS
+
+Git tag for the release:
+
+https://github.com/apache/incubator-graphar/releases/tag/${release_version}
+
+Please download, verify, and test.
+
+The VOTE will be open for at least 72 hours and until the necessary
+number of votes are reached.
+
+[ ] +1 approve
+[ ] +0 no opinion
+[ ] -1 disapprove with the reason
+
+To learn more about apache graphar, please see https://graphar.apache.org/
+
+Checklist for reference:
+
+[ ] Download links are valid.
+[ ] Checksums and signatures.
+[ ] LICENSE/NOTICE files exist
+[ ] No unexpected binary files
+[ ] All source files have ASF headers
+[ ] Can compile from source
+
+More detailed checklist please refer to:
+https://github.com/apache/incubator-graphar/tree/main/scripts
+
+To compile from source, please refer to:
+https://github.com/apache/incubator-graphar/blob/main/CONTRIBUTING.md
+
+Here is python script in release to help you verify the release candidate:
+
+./scripts/verify.py
+
+Thanks
+
+${name}
+```
+
+After at least 72 hours with at least 3 +1 binding vote (from Incubator PMC
member) and no veto, claim the vote result:
+
+Title:
+
+```
+[RESULT][VOTE] Release Apache GraphAr(incubating) ${release_version} -
Incubator Vote Round 1
+```
+
+Content:
+
+```
+Hi Incubator PMC,
+
+The vote to release Apache GraphAr(incubating) ${release_version} has passed
with
+4 +1 binding and 3 +1 non-binding votes, no +0 or -1 votes.
+
+Binding votes：
+
+- xxx
+- yyy
+- zzz
+
+Non-Binding votes:
+
+- aaa
+
+Vote thread: ${incubator_vote_thread_url}
+
+Thanks for reviewing and voting for our release candidate.
+
+We will proceed with publishing the approved artifacts and sending out the
announcement soon.
+```
+
+## Official Release
+
+### Push the release git tag
+
+```shell
+# Checkout the tags that passed VOTE
+git checkout ${release_version}
+# Tag with the graphar version
+git tag -s ${graphar_version}
+# Push tags to GitHub to trigger releases
+git push origin ${graphar_version}
+```
+
+### Publish artifacts to SVN RELEASE branch
+
+```shell
+svn mv
https://dist.apache.org/repos/dist/dev/incubator/graphar/${release_version}
https://dist.apache.org/repos/dist/release/incubator/graphar/${opendal_version}
-m "Release ${opendal_version}"
+```
+
+### Create a GitHub Release
+
+- Click [here](https://github.com/apache/incubator-graphar/releases/new) to
create a new release.
+- Pick the git tag of this release version from the dropdown menu.
+- Make sure the branch target is `main`.
+- Generate the release note by clicking the `Generate release notes` button.
+- Add the release note from every component's `upgrade.md` if there are
breaking changes before the content generated by GitHub. Check them carefully.
+- Publish the release.
+
+### Send the announcement
+
+Send the release announcement to `[email protected]` and CC
`[email protected]`.
+
+> Tips: Please follow the [Committer
Email](https://infra.apache.org/committer-email.html) guide to make sure you
have already set up the email SMTP. Otherwise, your email cannot be sent to the
announcement mailing list.
+
+Instead of adding breaking changes, let's include the new features as "notable
changes" in the announcement.
+
+Title:
+
+```
+[ANNOUNCE] Release Apache GraphAr(incubating) ${graphar_version}
+```
+
+Content:
+
+```
+Hi all,
+
+The Apache GraphAr(incubating) community is pleased to announce
+that Apache GraphAr(incubating) ${graphar_version} has been released!
+
+GraphAr is a data access layer that allows users to easily and efficiently
+retrieve data from various storage services in a unified way.
+
+The notable changes since ${graphar_version} include:
+1. xxxxx
+2. yyyyyy
+3. zzzzzz
+
+Please refer to the change log for the complete list of changes:
+https://github.com/apache/incubator-graphar/releases/tag/v${graphar_version}
+
+Apache GraphAr website: https://graphar.apache.org/
+
+Download Links: https://graphar.apache.org/download
+
+GraphAr Resources:
+- Issue: https://github.com/apache/incubator-graphar/issues
+- Mailing list: [email protected]
+
+Thanks
+On behalf of Apache GraphAr community
+
+---
+Apache GraphAr (incubating) is an effort undergoing incubation at the Apache
+Software Foundation (ASF), sponsored by the Apache Incubator PMC.
+
+Incubation is required of all newly accepted projects until a further review
+indicates that the infrastructure, communications, and decision making process
+have stabilized in a manner consistent with other successful ASF projects.
+
+While incubation status is not necessarily a reflection of the completeness
+or stability of the code, it does indicate that the project has yet to be
+fully endorsed by the ASF.
+```
+
+## Post release
+
+After the official release out, you may perform a few post actions.
+
+---
+
+This doc refer from [Apache OpenDAL](https://opendal.apache.org/)
diff --git a/community/committers/verify.md b/community/committers/verify.md
new file mode 100644
index 0000000..e5230fc
--- /dev/null
+++ b/community/committers/verify.md
@@ -0,0 +1,180 @@
+---
+title: Verify a candidate version
+sidebar_position: 1
+---
+
+## Introduction
+For detailed check list, please refer to the official [check
list](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist)
+
+Version content accessible in browser
https://dist.apache.org/repos/dist/dev/incubator/graphar/
+
+## Download the candidate version
+
+Download the candidate version to be released to the local environment Need to
rely on gpg tool, if not, it is recommended to install `gpg2`.
+
+:::caution
+
+If the network is poor, downloading may be time-consuming. The download is
completed normally in about 20 minutes, please wait patiently.
+
+:::
+
+```shell
+#If there is svn locally, you can clone to the local
+$ svn co
https://dist.apache.org/repos/dist/dev/incubator/graphar/${release_version}/
+#or download the material file directly
+$ wget
https://dist.apache.org/repos/dist/dev/incubator/graphar/${release_version}/xxx.xxx
+```
+
+## Verify that the uploaded version is compliant
+
+Start the verification process, which includes but is not limited to the
following content and forms.
+
+### Check whether the release package is complete
+
+The package uploaded to dist must include the source code package, and the
binary package is optional.
+
+1. Whether to include the source code package
+2. Whether to include the signature of the source code package
+3. Whether to include the sha512 of the source code package
+4. If the binary package is uploaded, also check the contents listed in (1)-(3)
+
+
+### Check gpg signature
+
+First import the publisher's public key. Import KEYS from the svn repository
to the local environment. (The person who releases the version does not need to
import it again, the person who helps to do the verification needs to import
it, and the user name is enough for the person who issued the version)
+
+#### Import public key
+
+```shell
+$ curl https://downloads.apache.org/incubator/graphar/KEYS > KEYS # Download
KEYS
+$ gpg --import KEYS # Import KEYS to local
+```
+#### Trust the public key
+
+Trust the KEY used in this version:
+
+```shell
+$ gpg --edit-key xxxxxxxxxx #KEY user used in this version
+gpg (GnuPG) 2.2.21; 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.
+
+Secret key is available.
+gpg> trust #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 #choose 5
+Do you really want to set this key to ultimate trust? (y/N) y #choose y
+
+gpg>
+
+```
+
+#### Check the gpg signature
+
+```shell
+$ for i in *.tar.gz; do echo $i; gpg --verify $i.asc $i; done
+```
+
+check result
+
+> If something like the following appears, it means the signature is correct.
Keyword: **`Good signature`**
+
+```shell
+apache-hertzbeat-xxx-incubating-src.tar.gz
+gpg: Signature made XXXX
+gpg: using RSA key XXXXX
+gpg: Good signature from "xxx @apache.org>"
+```
+
+### Check sha512 hash
+
+```shell
+$ for i in *.tar.gz; do echo $i; sha512sum --check $i.sha512; done
+```
+
+### Check the source package
+
+unzip `apache-graphar-${release.version}-incubating-src.tar.gz`
+
+```shell
+tar -xzvf apache-graphar-${release.version}-incubating-src.tar.gz
+```
+
+check as follows:
+
+- [ ] Check whether the source package contains unnecessary files, which makes
the tar package too large
+- [ ] Folder contains the word `incubating`
+- [ ] There are `LICENSE` and `NOTICE` files
+- [ ] There is a `DISCLAIMER` or `DISCLAIMER-WIP` file
+- [ ] The year in the `NOTICE` file is correct
+- [ ] Only text files exist, not binary files
+- [ ] All files have ASF license at the beginning
+- [ ] Able to compile correctly
+- [ ] .....
+
+You can refer to this article: [ASF Third Party License
Policy](https://apache.org/legal/resolved.html)
+
+compile the source code: [Build HertzBeat Binary
Package](https://hertzbeat.apache.org/docs/community/development/#build-hertzbeat-binary-package)
+
+
+## 3. Email reply
+
+If you initiate a posting vote, you can refer to this response example to
reply to the email after verification
+<font color="red">
+When replying to the email, you must bring the information that you have
checked by yourself. Simply replying to `+1 approve` is invalid.
+
+When PPMC votes in the [email protected] GraphAr community, Please bring
the binding suffix to indicate that it has a binding vote for the vote in the
GraphAr community, and it is convenient to count the voting results.
+
+When IPMC votes in the [email protected] incubator community.
Please bring the binding suffix to indicate that the voting in the incubator
community has a binding vote, which is convenient for counting the voting
results.
+</font>
+
+:::caution
+If you have already voted on [email protected], you can take it directly
to the incubator community when you reply to the vote, such as:
+
+```html
+//Incubator community voting, only IPMC members have binding binding，PPMC
needs to be aware of binding changes
+Forward my +1 from dev@listgrapharnkis (non-binding)
+Copy my +1 from graphar DEV ML (non-binding)
+````
+:::
+
+
+Non-PPMC/Non-IPMC member:
+
+```text
++1 (non-binding)
+I checked:
+ 1. All download links are valid
+ 2. Checksum and signature are OK
+ 3. LICENSE and NOTICE are exist
+ 4. Build successfully on macOS(Big Sur)
+ 5.
+````
+
+PPMC/IPMC member:
+
+```text
+//Incubator community voting, only IPMC members have binding binding
++1 (binding)
+I checked:
+ 1. All download links are valid
+ 2. Checksum and signature are OK
+ 3. LICENSE and NOTICE are exist
+ 4. Build successfully on macOS(Big Sur)
+ 5.
+````
+
+
+
+---
+
+This doc refer from [Apache StreamPark](https://streampark.apache.org/)
\ No newline at end of file
diff --git a/community/development.md b/community/development.md
new file mode 100644
index 0000000..c67135e
--- /dev/null
+++ b/community/development.md
@@ -0,0 +1,47 @@
+---
+title: Development
+sidebar_position: 2
+id: development
+---
+
+# How to build GraphAr
+
+Please checkout the source tree from
https://github.com/apache/incubator-graphar.
+
+## Build GraphAr C++ library
+
+### System setup
+
+Building GraphAr C++ library requires:
+
+- A C++17-enabled compiler. On Linux, gcc 7.1 and higher should be
+ sufficient. For MacOS, at least clang 5 is required
+- CMake 3.5 or higher
+- On Linux and macOS, ``make`` build utilities
+- Apache Arrow C++ (>= 12.0.0, requires `arrow-dev`, `arrow-dataset`,
`arrow-acero` and `parquet` modules) for Arrow filesystem support. You can
refer to [Apache Arrow Installation](https://arrow.apache.org/install/) to
install the required modules.
+- [Catch2 v3](https://github.com/catchorg/Catch2) for unit testing if
`BUILD_TESTS` is enabled
+- [Google Benchmark](https://github.com/google/benchmark) (>= 1.6.0) for
benchmarking if `BUILD_BENCHMARKS` is enabled
+
+### Building
+
+```bash
+$ cd cpp
+$ cmake -S . -B build
+$ cmake --build build
+```
+
+## Build GraphAr Scala with Spark library
+
+### System setup
+
+Building requires:
+
+- JDK 8 or JDK 11
+- Maven 3.2.0 or higher
+
+### Building
+
+```bash
+$ cd maven-projects/spark
+$ mvn clean -DskipTests
+```
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
