This is an automated email from the ASF dual-hosted git repository.
aw pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/yetus.git
The following commit(s) were added to refs/heads/main by this push:
new 95d3be59 YETUS-1042. Post-0.13.0 release docs updates (#258)
95d3be59 is described below
commit 95d3be597f3f18518298f82144c97d967c922317
Author: Allen Wittenauer <[email protected]>
AuthorDate: Mon Apr 25 13:40:02 2022 -0700
YETUS-1042. Post-0.13.0 release docs updates (#258)
---
.gitignore | 1 +
asf-site-src/pom.xml | 13 ++-
asf-site-src/source/contribute/releases.html.md | 103 +++++++++++----------
.../documentation/in-progress/precommit/apidocs | 1 -
4 files changed, 69 insertions(+), 49 deletions(-)
diff --git a/.gitignore b/.gitignore
index 480fc922..58163492 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,3 +20,4 @@ publish
asf-site-src/source/documentation/0*
asf-site-src/source/documentation/in-progress/CHANGELOG.md
asf-site-src/source/documentation/in-progress/RELEASENOTES.md
+asf-site-src/source/documentation/in-progress/precommit/apidocs
diff --git a/asf-site-src/pom.xml b/asf-site-src/pom.xml
index ad66a00f..37849883 100644
--- a/asf-site-src/pom.xml
+++ b/asf-site-src/pom.xml
@@ -115,7 +115,7 @@
<!-- AUTOMATED_EDIT_END -->
<execution>
<!-- we create a symlink of current version->in-progress. This
will cause
- middle man to generate two copies of the output. -->
+ middleman to generate two copies of the output. -->
<id>in-progress</id>
<phase>pre-site</phase>
<goals>
@@ -126,6 +126,17 @@
<newLink>${basedir}/source/documentation/${project.version}</newLink>
</configuration>
</execution>
+ <execution>
+ <id>apidocs</id>
+ <phase>pre-site</phase>
+ <goals>
+ <goal>symlink</goal>
+ </goals>
+ <configuration>
+
<target>../../../../target/in-progress/precommit/apidocs/</target>
+
<newLink>${basedir}/source/documentation/in-progress/precommit/apidocs</newLink>
+ </configuration>
+ </execution>
</executions>
</plugin>
diff --git a/asf-site-src/source/contribute/releases.html.md
b/asf-site-src/source/contribute/releases.html.md
index 515ac6eb..ed7603dc 100644
--- a/asf-site-src/source/contribute/releases.html.md
+++ b/asf-site-src/source/contribute/releases.html.md
@@ -24,6 +24,7 @@
- [Dependencies](#dependencies)
- [Setup](#setup)
+- [Verify Changelog and Release Notes](#verify-changelog-and-release-notes)
- [Release Candidate\(s\)](#release-candidates)
- [Verification](#verification)
- [Cleanup](#cleanup)
@@ -112,7 +113,8 @@ Like the rest of our project activity, we'll use an issue
in JIRA to track manag
### Work in Git
-Once you have an issue to track things, you can create the git branch for
staging our release. This separate branch will allow you to polish the release
while regular work continues on the main branch. For non-micro releases, you
will need to update main for the next SNAPSHOT version and the branch for the
release.
+Once you have an issue to track things, git branches will be needed in order
to make the necessary
+PRs. A script is provided to make this easier:
- Major Release:
@@ -134,18 +136,28 @@ Once you have an issue to track things, you can create
the git branch for stagin
These commands will create one or two branches:
-- JIRA-release with updated poms that match the release you are working on
-- JIRA-main with updated poms that match the next SNAPSHOT release
+- _JIRA_-release with updated poms that match the release you are working on
+- _JIRA_-main with updated poms that match the next SNAPSHOT release
-Verify these branches are correct and create the necessary PRs. Once
approved, merge to their respective branches.
+Verify the automated commits to these branches are correct and create the
necessary PRs.
+Once Apache Yetus checks finish, merge to their respective branches. (You do
not need approval.)
+
+## Verify Changelog and Release Notes
+
+Before starting work on the release candidate, it is generally a good idea to
look over
+the changelog and release notes. These files are part of our distribution and
if they
+are incorrect, will require a new RC. Therefore, before cutting a new release,
make sure
+they do not have errors or missing information. The easiest way to do this
check is to
+run through the [website](../website) directions to update the live website.
After doing
+that work, they should be listed [here](/downloads/releasenotes/) as the top
entry.
## Release Candidate(s)
Depending on how candidate evaluation goes, you may end up performing these
steps multiple times. Before you start, you'll need to decide when you want
each candidate's vote thread to end. ASF policy requires a minimum voting
period of 72 hours (ref [ASF Voting
Policy](https://www.apache.org/foundation/voting.html)), so you should ensure
enough padding to complete the candidate generation process in time. Ideally,
you would plan to post the vote thread on a Friday morning (US time) with [...]
-1. Update JIRA version release date. Browse to the JIRA project version
management page
<https://issues.apache.org/jira/plugins/servlet/project-config/YETUS/versions>,
mark the version as 'Release', and set the release date. Our generated release
notes will use this date.
+1. Update JIRA version release date. Browse to the JIRA project version
management page
<https://issues.apache.org/jira/plugins/servlet/project-config/YETUS/versions>,
mark the version as 'Release', and set the release date. Our generated release
notes will use this date. Note that this will close the version and no one will
be able to assign new JIRA issues to it. However it is required for the
`build-and-sign` step below.
1. Update your `${HOME}/.m2/settings.xml` file to include the Maven snapshot
information as indicated on
<https://www.apache.org/dev/publishing-maven-artifacts.html>
-1. Build release artifacts. Run the following from the _release staging
branch_ created by the `release/initial-patches.sh` script and run these
commands:
+1. Build release artifacts. Run the following from the _release staging
branch_ (`JIRA-release`) created by the `release/initial-patches.sh` script and
run these commands:
```bash
$ git checkout YETUS-XXX-release
@@ -155,11 +167,12 @@ Depending on how candidate evaluation goes, you may end
up performing these step
$ ls -lah yetus-dist/target/artifacts/*
```
+1. Before exiting the container, peruse the `/tmp/build-log` directory to see
if any relevant errors occurred.
1. Exit the container.
1. Check out the staging area for release candidates and make a directory for
this candidate, somewhere outside of your working directory. Copy the artifacts
from the previous step into place. For example, when working on RC1 for the
0.7.0 release
```bash
- $ svn co `https://dist.apache.org/repos/dist/dev/yetus/` yetus-dist-dev
+ $ svn co https://dist.apache.org/repos/dist/dev/yetus/ yetus-dist-dev
$ cd yetus-dist-dev
$ mkdir 0.7.0-RC1
$ cd 0.7.0-RC1
@@ -288,13 +301,13 @@ ASF policies require that binding votes on releases be
cast only after verifying
- Our software may only have a runtime dependency on a product with a
prohibit license if its use is optional; read [the Licensing Policy's Category
X list for prohibited
licenses](https://www.apache.org/legal/resolved#category-x) and [the Licensing
Policy's explanation of optional runtime
dependencies](https://www.apache.org/legal/resolved#optional).
1. You SHOULD make sure the source release artifact corresponds to the
referenced commit hash in the [VOTE] thread. (This ASF policy is currently in
DRAFT status.) The release tag is how we'll provide long-term provenance
information for our downstream users. Since the release's source code artifact
will be the canonical representation of the release we vote on, it is essential
that it matches the contents of the version control system's tag. Given our
example above, you can check this w [...]
+ NOTE: The `maven` plug-in that we use does not include some git control
files like `.gitignore` and `.gitattributes`. Additionally, it adds a
`DEPENDENCIES` file.
+
```bash
$ mkdir apache-yetus-0.7.0-src_unpack
$ tar -C apache-yetus-0.7.0-src_unpack -xzf apache-yetus-0.7.0-src.tar.gz
$ git clone --single-branch --depth=1 --branch YETUS-585
'https://github.com/apache/yetus.git' apache-yetus-0.7.0-RC1-tag
- $ diff -r apache-yetus-0.7.0-RC1-tag
apache-yetus-0.7.0-src_unpack/yetus-project-0.7.0
- $ echo $?
- 0
+ $ diff -r apache-yetus-0.7.0-RC1-tag
apache-yetus-0.7.0-src_unpack/apache-yetus-0.7.0
```
1. You MUST make sure any non-source artifacts can be derived from the source
artifact. Since the source artifact is the canonical representation of our
release, any other artifacts we distribute must be just for the convenience of
our downstream users. As such, one must be able to derive them from the source
artifact. Currently, you can generate all of the artifacts we distribute for
convenience using the same commands used to create the release artifacts.
@@ -302,7 +315,7 @@ ASF policies require that binding votes on releases be cast
only after verifying
```bash
$ mkdir apache-yetus-0.7.0-src_unpack
$ tar -C apache-yetus-0.7.0-src_unpack -xzf apache-yetus-0.7.0-src.tar.gz
- $ cd apache-yetus-0.7.0-src_unpack/yetus-project-0.7.0
+ $ cd apache-yetus-0.7.0-src_unpack/apache-yetus-0.7.0
$ mvn clean install
```
@@ -434,6 +447,25 @@ Once a release candidate obtains majority approval from
the PMC, there are sever
### Core Release Tasks
+1. Update the documentation in the git main branch for the new release.
Remove the oldest release and add the latest.
+
+ ```bash
+ $ release/update-doc-versions.sh --version=<x.y.z -- version WITHOUT the
rel/!>
+ $ git add -p
+ $ git add asf-site-src/pom.xml
+ $ git commit
+ ```
+
+ - Example commit message:
+
+ ```text
+ YETUS-XXX. add release 0.7.0.
+
+ - list in releases
+ - remove 0.4.0, add 0.7.0 to pom.xml
+ ```
+
+1. Commit the patch to the ASF source repo immediately, but do not update the
website just yet.
1. Create shortcut links to the vote thread (e.g.,
<https://s.apache.org/yetus-0.7.0-rc1-vote>) and the result (e.g.,
<https://s.apache.org/yetus-0.7.0-vote-passes>) that point to the archives on
mail-archives.apache.org. Be aware that it may take several hours for the
archive to get the posts that need to be referenced.
1. Produce a signed release tag. You should create a signed tag and push it to
the asf repo. The tag's message should include ASF-shortened links to the vote
and results. It should be named 'rel/_version_' so that it will be immutable
due to ASF infra's git configuration. Presuming we're working on the 0.7.0
release and the RC1 example above has passed:
@@ -457,7 +489,6 @@ Once a release candidate obtains majority approval from the
PMC, there are sever
$ cp path/to/yetus-dist-dev/0.7.0-RC1/* 0.7.0
$ svn add 0.7.0
$ svn commit -m "Publish Apache Yetus 0.7.0"
- It may take up to 24 hours for the artifacts to make their way to the
various mirrors. You should not announce the release until after this period.
1. Add the release to the ASF reporter tool. To make our project reports for
the ASF Board easier, you should include the release in the [Apache Committee
Report Helper website](https://reporter.apache.org/addrelease.html?yetus). Be
sure to use the date release artifacts first were pushed to the distribution
area, which should be the same release date as in JIRA. Note that this website
is only available to PMC members. If you are not yet in the PMC, please ask
them to add the release inf [...]
1. Remove candidates from the staging area. Once you have moved the artifacts
into the distribution area, they no longer need to be in the staging area and
should be cleaned up as a courtesy to future release managers.
@@ -552,37 +583,16 @@ Once a release candidate obtains majority approval from
the PMC, there are sever
Meg Smith
Apache Yetus PMC
If you'd like feedback on the draft, feel free to post it for review on
your release issue.
-1. Wait 24 hours for mirrors to get properly updated.
+1. Wait 24 hours for mirrors to get properly updated before continuing.
### Documentation
-1. Update the documentation in the git main branch for the new release.
Remove the oldest release and add the latest.
-
- ```bash
- $ release/update-doc-versions.sh --version=<x.y.z -- version WITHOUT the
rel/!>
- $ git add -p
- $ git add asf-site-src/pom.xml
- $ git commit
- ```
-
- - Example commit message:
-
- ```text
- YETUS-XXX. add release 0.7.0.
-
- - list in releases
- - remove 0.4.0, add 0.7.0 to pom.xml
- ```
-
-1. You should then post this patch for review. Once you've gotten feedback,
it's fine to push the patch to the ASF source repo immediately so long as the
updated website is not published.
-1. 24 hours after the distribution repo has been updated, publish website
updates. See [Maintaining the Yetus Website](../website).
+1. Publish website updates. See [Maintaining the Yetus Website](../website).
1. Verify that https://yetus.apache.org/latest.tgz and
https://yetus.apache.org/latest.tgz.asc download the newly released version.
### Homebrew
-24 Hours after the distribution repo has been updated, update Homebrew to
point to the new release:
-
-1. Update the `yetus-homebrew` repo by using the release script:
+1. Update the `yetus-homebrew` repo by using the release script. It will tag
_and sign_ (so GPG needs to work!) the top of the tree to point to the release.
(Homebrew only uses top of tree, so branches are pointless.)
```bash
$ ./release.sh YETUS-XXX <x.y.z -- version WITHOUT the rel/!>
@@ -601,31 +611,30 @@ Once a release candidate obtains majority approval from
the PMC, there are sever
### Github Marketplace Action
-24 Hours after the distribution repo has been updated, update the Github
Marketplace.
-
-1. Update the `yetus-test-patch-action` repo by using the release script to
create a branch which will then tag that branch:
+1. Verify that the [Github Container
Registry](https://github.com/orgs/apache/packages?repo_name=yetus) has both
repositories updated with the tagged release.
+1. Update the `yetus-test-patch-action` repo by using the release script to
create a branch which will then tag _and sign_ (so GPG needs to work!) that
branch:
```bash
$ ./release.sh YETUS-XXX <x.y.z -- version WITHOUT the rel/!>
```
1. Verify the branch and the tag match and that the container version matches
the Apache Yetus release.
+1. Push the branch:
+
+ ```bash
+ $ git push origin x.y.z
+ ```
+
+1. Verify that the tag built in Github Actions.
1. Go to [Draft a
release](https://github.com/aw-was-here/yetus-test-patch-action/releases/new?marketplace=true)
1. Type the tag that you just pushed into the 'tag' box.
1. Use categories 'Code quality' and 'Continuous integration'
1. Release Title should reflect the version
-1. Describe this release should be a cut-down version of the announcement
email (drop SHA and direct download links. main page, github actions, and
release notes should be mentioned)
+1. Describe this release should be a cut-down version of the announcement
email (drop SHA and direct download links. main page, github actions, and
release notes should be mentioned). See
[Releases](https://github.com/apache/yetus-test-patch-action/releases) for
examples.
1. Mark 'This is a pre-release'
1. Verify everything looks good.
1. Publish release
### Make it Official
-1. Did you wait 24 hours for the release artifacts to get everywhere?
1. Send announcement emails. The email should come from your apache.org email
address and at a minimum should go to the [email protected] list. For
details see [the ASF Release Policy section How Should Releases Be
Announced?](https://www.apache.org/dev/release.html#release-announcements).
Additionally, you may want to send the announcement to the development lists of
downstream projects we know are using Yetus components.
-1. Send tweet. Once the message to [email protected] has made it to the
public archive, you should draft a tweet with a link to the announcement. You
should use the ASF link shortener and a descriptive name. For example, the
0.7.0 release could use
-
- Apache Yetus 0.7.0 has been released:
-
- https://s.apache.org/yetus-0.7.0-announce
- This tweet should come from the official
[@ApacheYetus](https://twitter.com/ApacheYetus/) account. Currently, only PMC
members have access to it. If you are not yet on the PMC, please ask for the
PMC to post the tweet once your email is available in the archives.
diff --git a/asf-site-src/source/documentation/in-progress/precommit/apidocs
b/asf-site-src/source/documentation/in-progress/precommit/apidocs
deleted file mode 120000
index 38e80e1b..00000000
--- a/asf-site-src/source/documentation/in-progress/precommit/apidocs
+++ /dev/null
@@ -1 +0,0 @@
-../../../../target/in-progress/precommit/apidocs/
\ No newline at end of file
