beam-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [1/4] beam-site git commit: [BEAM-475] update release instructions for javadoc
Date Wed, 22 Feb 2017 20:25:46 GMT
Repository: beam-site
Updated Branches:
  refs/heads/asf-site 940eb0620 -> 845f589d3

[BEAM-475] update release instructions for javadoc


Branch: refs/heads/asf-site
Commit: bdb0ab465ba690a8c991e82b13699c42f88c33d8
Parents: 940eb06
Author: Benson Margulies <>
Authored: Tue Jan 31 15:40:11 2017 -0800
Committer: Dan Halperin <>
Committed: Wed Feb 22 12:10:53 2017 -0800

 src/contribute/ | 56 ++++++++++++++++++++++--------------
 1 file changed, 35 insertions(+), 21 deletions(-)
diff --git a/src/contribute/ b/src/contribute/
index c2fea8f..3e56a85 100644
--- a/src/contribute/
+++ b/src/contribute/
@@ -150,6 +150,31 @@ You should verify that the issues listed automatically by JIRA are appropriate
 Adjust any of the above properties to the improve clarity and presentation of the Release
+### Verify that a Release Build Works
+Run `mvn -Prelease` to ensure that the build processes that are specific to that
+profile are in good shape.
+### Update and Verify Javadoc
+The build with `-Prelease` creates the combined javadoc for the release in `sdks/java/javadoc`.
+In that directory, the file `sdks/java/javadoc/ant.xml` file contains a list of
+modules to include in and exclude, plus a list of offline URLs that populate
+links to Javadoc for other modules that Beam depends on.
+You should both examine the generated javadoc and look over the contents of that
+file to ensure that the javadoc is correct.
+Confirm that new modules added since the last release have been added to the
+inclusion list as appropriate.
+Confirm that the excluded package list is up to date.
+Verify the version numbers for offline links match the versions used by Beam. If
+the version number has changed, download a new version of the corresponding
+XX-docs/package-list file.
 ### Create a release branch
 Release candidates are built from a release branch. As a final step in preparation for the
release, you should create the release branch, push it to the code repository, and update
version information on the original branch.
@@ -197,6 +222,7 @@ The rest of this guide assumes that commands are run in the root of a
 1. JIRA release item for the subsequent release has been created
 1. There are no release blocking JIRA issues
 1. Release Notes in JIRA have been audited and adjusted
+1. Combined javadoc has the appropriate contents.
 1. Release branch has been created
 1. Originating branch has the version information updated to the new version
@@ -255,35 +281,23 @@ Copy the source release to the dev repository of ``.
 1. Verify that files are [present](
-### Build the API reference
-Beam publishes API reference manual for each release on the website. For Java SDK, that’s
-Check out release candidate, as follows:
-    git checkout ${TAG}
-Use Maven Javadoc plugin to generate the new Java reference manual, as follows:
-    mvn -DskipTests clean package javadoc:aggregate \
-        -Ddoctitle="Apache Beam SDK for Java, version ${VERSION}" \
-        -Dwindowtitle="Apache Beam SDK for Java, version ${VERSION}" \
-        -Dmaven.javadoc.failOnError=false \
-        -DexcludePackageNames="org.apache.beam.examples,org.apache.beam.runners.dataflow.internal,org.apache.beam.runners.flink.examples,org.apache.beam.runners.flink.translation,org.apache.beam.runners.spark.examples,org.apache.beam.runners.spark.translation,org.apache.beam.runners.apex.translation,org.apache.beam.sdk.microbenchmarks.coders.generated,org.apache.beam.sdk.microbenchmarks.transforms.generated,org.openjdk.jmh.infra.generated"
-By default, the Javadoc will be generated in `target/site/apidocs/`. Let `${JAVADOC_ROOT}`
be the absolute path to `apidocs`. ([Pull request #1015](
will hopefully simplify this process.)
-Please carefully review the generated Javadoc. Check for completeness and presence of all
relevant packages and ``; consider adding less relevant packages to the `excludePackageNames`
configuration. The index page is generated at `${JAVADOC_ROOT}/index.html`.
 ### Propose a pull request for website updates
 The final step of building the candidate is to propose a website pull request.
 Start by updating `release_latest` version flag in the top-level `_config.yml`, and list
the new release in the [Apache Beam Downloads]({{ site.baseurl }}/get-started/downloads/),
linking to the source code download and the Release Notes in JIRA.
+Beam publishes API reference manual for each release on the website. For Java SDK, that’s
+One of the artifacts created in the release contains the Javadoc for the website: 
+. To update the website, you must unpack
+this jar file from the release candidate into the source tree of the website.
 Add the new Javadoc to [SDK API Reference page]({{ site.baseurl }}/documentation/sdks/javadoc/)
page, as follows:
-* Copy the generated Javadoc into the website repository: `cp -r ${JAVADOC_ROOT} documentation/sdks/javadoc/${VERSION}`.
+* Unpack the Maven artifact `org.apache.beam:beam-sdks-java-javadoc` into some temporary
location. Call this `${JAVADOC_TMP}`.
+* Copy the generated Javadoc into the website repository: `cp -r ${JAVADOC_TMP} documentation/sdks/javadoc/${VERSION}`.
+* Set up the necessary git commands to account for the new and deleted files from the javadoc.
 * Update the Javadoc link on this page to point to the new version (in `src/documentation/sdks/javadoc/`).
 Finally, propose a pull request with these changes. (Don’t merge before finalizing the

View raw message