[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151862&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151862 ]
ASF GitHub Bot logged work on BEAM-4501: ---------------------------------------- Author: ASF GitHub Bot Created on: 05/Oct/18 21:06 Start Date: 05/Oct/18 21:06 Worklog Time Spent: 10m Work Description: udim 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_r223080429 ########## 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: I wanted to make the instructions as clear and as simple to understand as possible. I guess we could just tell people to look at the file history on github. ---------------------------------------------------------------- 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: 151862) Time Spent: 5h 20m (was: 5h 10m) > 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: 5h 20m > Remaining Estimate: 0h > -- This message was sent by Atlassian JIRA (v7.6.3#76005)