[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151681&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151681
]
ASF GitHub Bot logged work on BEAM-4501:
----------------------------------------
Author: ASF GitHub Bot
Created on: 05/Oct/18 16:45
Start Date: 05/Oct/18 16:45
Worklog Time Spent: 10m
Work Description: swegner commented on a change in pull request #6533:
[BEAM-4501] Update website contribution and release docs
URL: https://github.com/apache/beam/pull/6533#discussion_r223071424
##########
File path: website/src/contribute/release-guide.md
##########
@@ -547,41 +562,54 @@ Make sure you have ```tox``` installed:
```
pip install tox
-
```
Create the Python SDK documentation using sphinx by running a helper script.
```
cd sdks/python && tox -e docs
```
By default the Pydoc is generated in `sdks/python/target/docs/_build`. Let
`${PYDOC_ROOT}` be the absolute path to `_build`.
-#### Propose a pull request for website updates
+#### Propose pull requests for website updates
-The final step of building the candidate is to propose a website pull request.
+Beam publishes API reference manuals for each release on the website. For Java
+and Python SDKs, that’s Javadoc and PyDoc, respectively. The final step of
+building the candidate is to propose website pull requests that update these
+manuals.
-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.
+Merge the pull requests only after finalizing the release. To avoid invalid
+redirects for the 'current' version, merge these PRs in the order listed. Once
+the PR is merged, the new contents will get picked up automatically and served
+to the Beam website, usually within an hour.
-Beam publishes API reference manual for each release on the website. For Java
SDK, that’s Javadoc.
+**PR 1: apache/beam-site**
-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.
+This pull request is against the `apache/beam-site` repo, on the `release-docs`
+branch.
-Add the new Javadoc to [SDK API Reference
page](https://beam.apache.org/releases/javadoc/) page, as follows:
+* Add the new Javadoc to [SDK API Reference
page](https://beam.apache.org/releases/javadoc/) page, as follows:
+ * 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} javadoc/${RELEASE}`.
+* Add the new Pydoc to [SDK API Reference
page](https://beam.apache.org/releases/pydoc/) page, as follows:
+ * Copy the generated Pydoc into the website repository: `cp -r ${PYDOC_ROOT}
pydoc/${RELEASE}`.
+ * Remove `.doctrees` directory.
+* Stage files using: `git add --all javadoc/ pydoc/`.
-* 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} src/documentation/sdks/javadoc/${RELEASE}`.
-* 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/current.md`).
+**PR 2: apache/beam**
-##### Create Pydoc
-Add the new Pydoc to [SDK API Reference
page](https://beam.apache.org/releases/pydoc/) page, as follows:
+This pull request is against the `apache/beam` repo, on the `master` branch.
-* Copy the generated Pydoc into the website repository: `cp -r ${PYDOC_ROOT}
src/documentation/sdks/pydoc/${RELEASE}`.
-* Remove `.doctrees` directory.
-* Update the Pydoc link on this page to point to the new version (in
`src/documentation/sdks/pydoc/current.md`).
+* Update the `release_latest` version flag in `/website/_config.yml`, and list
+ the new release in `/website/src/get-started/downloads.md`, linking to the
+ source code download and the Release Notes in JIRA.
+* Update the `RedirectMatch` rule in `/website/src/.htaccess` to point to the
+ new release.
-Finally, propose a pull request with these changes. (Don’t merge before
finalizing the release.)
+ ```
+ For example, change:
Review comment:
Do you think it's necessary to show the code change here? I'm afraid it will
get stale. Alternatively, we can point to an actual PR for the 2.7.0 release.
(I don't see one open yet but I can make one today)
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
Issue Time Tracking
-------------------
Worklog Id: (was: 151681)
Time Spent: 4h 10m (was: 4h)
> Update contribution guide for new website contribution process
> --------------------------------------------------------------
>
> Key: BEAM-4501
> URL: https://issues.apache.org/jira/browse/BEAM-4501
> Project: Beam
> Issue Type: Sub-task
> Components: website
> Reporter: Scott Wegner
> Assignee: Udi Meiri
> Priority: Major
> Labels: beam-site-automation-reliability
> Time Spent: 4h 10m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
