[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=152357=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-152357 ] ASF GitHub Bot logged work on BEAM-4501: Author: ASF GitHub Bot Created on: 08/Oct/18 18:43 Start Date: 08/Oct/18 18:43 Worklog Time Spent: 10m Work Description: udim opened a new pull request #6605: [BEAM-4501] Update a few more apache/beam-site references URL: https://github.com/apache/beam/pull/6605 Follow this checklist to help us incorporate your contribution quickly and easily: - [ ] Format the pull request title like `[BEAM-XXX] Fixes bug in ApproximateQuantiles`, where you replace `BEAM-XXX` with the appropriate JIRA issue, if applicable. This will automatically link the pull request to the issue. - [ ] If this contribution is large, please file an Apache [Individual Contributor License Agreement](https://www.apache.org/licenses/icla.pdf). It will help us expedite review of your Pull Request if you tag someone (e.g. `@username`) to look at it. Post-Commit Tests Status (on master branch) Lang | SDK | Apex | Dataflow | Flink | Gearpump | Samza | Spark --- | --- | --- | --- | --- | --- | --- | --- Go | [](https://builds.apache.org/job/beam_PostCommit_Go_GradleBuild/lastCompletedBuild/) | --- | --- | --- | --- | --- | --- Java | [](https://builds.apache.org/job/beam_PostCommit_Java_GradleBuild/lastCompletedBuild/) | [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Apex_Gradle/lastCompletedBuild/) | [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Dataflow_Gradle/lastCompletedBuild/) | [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Flink_Gradle/lastCompletedBuild/) | [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Gearpump_Gradle/lastCompletedBuild/) | [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Samza_Gradle/lastCompletedBuild/) | [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Spark_Gradle/lastCompletedBuild/) Python | [](https://builds.apache.org/job/beam_PostCommit_Python_Verify/lastCompletedBuild/) | --- | [](https://builds.apache.org/job/beam_PostCommit_Py_VR_Dataflow/lastCompletedBuild/) [](https://builds.apache.org/job/beam_PostCommit_Py_ValCont/lastCompletedBuild/) | [](https://builds.apache.org/job/beam_PostCommit_Python_VR_Flink/lastCompletedBuild/) | --- | --- | --- 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: 152357) Time Spent: 6h (was: 5h 50m) > 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:
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151865=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151865 ] 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: swegner commented on issue #6533: [BEAM-4501] Update website contribution and release docs URL: https://github.com/apache/beam/pull/6533#issuecomment-427498891 LGTM 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: 151865) Time Spent: 5h 40m (was: 5.5h) > 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 40m > Remaining Estimate: 0h > -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151862=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
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151864=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151864 ] 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_r223138077 ## File path: website/README.md ## @@ -1,72 +1,57 @@ -# Apache Beam website - -_**The website source code is currently being migrated from -https://github.com/apache/beam-site, but is not yet ready. Please -continue to contribute changes at -[apache/beam-site](https://github.com/apache/beam-site) according to -the [website contribution guide](https://beam.apache.org/contribute/#contributing-to-the-website). -You can track migration progress via -[[BEAM-4493]](https://issues.apache.org/jira/browse/BEAM-4493).**_ - -This is the website for [Apache Beam](https://beam.apache.org/), hosted at: - -https://beam.apache.org/ + + +These are the main sources of the website for Apache Beam, hosted at +https://beam.apache.org/. ## About this site The Beam website is built using [Jekyll](http://jekyllrb.com/). Additionally, for additional formatting capabilities, this website uses [Twitter Bootstrap](http://getbootstrap.com/). -### Repository Structure - -This repository contains: - -1. `src/`: the source of the site, including markdown files containing the bulk of the content -1. `content/`: html generated from the markdown (which is what is actually hosted on the website) - -## Development Workflow - -### Setup - -You need Ruby version >= 2.2.0 to build the project. - -Install [Ruby Gems](https://rubygems.org/pages/download), a package management framework for Ruby. +Documentation generated from source code, such as Javadoc and Pydoc, is stored +separately on the [beam-site +repository](https://github.com/apache/beam-site/tree/release-docs). -Install [Bundler](http://bundler.io/v1.3/rationale.html), which we use to specify dependencies and ensure -a consistent environment for building the website, even across multiple developers on different machines: +## Active development -$ gem install bundler +Website development requires Docker installed if you wish to preview changes and +run website tests. -Use Bundler to download the versions of each dependency specified in the website's `Gemfile.lock`, -including [Jekyll](https://jekyllrb.com/): +The following command is used to build and serve the website locally. -$ bundle install --deployment +$ ./gradlew -PpublishJekyllPort :beam-website:serveWebsite Review comment: I don't know of a better way to do this. 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: 151864) Time Spent: 5.5h (was: 5h 20m) > 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: 5.5h > Remaining Estimate: 0h > -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151860=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151860
]
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: 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_r223138843
##
File path: website/build.gradle
##
@@ -65,8 +65,12 @@ task createDockerContainer(type: Exec) {
ext.containerId = {
return standardOutput.toString().trim()
}
+ def extraOptions = ''
+ if (project.hasProperty('publishJekyllPort')) {
+extraOptions = '-p 127.0.0.1:4000:4000'
Review comment:
Sounds good; we can revisit this later if it's a burden.
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: 151860)
Time Spent: 5h 10m (was: 5h)
> 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 10m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151863=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151863
]
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_r223137961
##
File path: website/src/contribute/release-guide.md
##
@@ -167,8 +167,23 @@ please submit your GPG public key into [MIT PGP Public
Key Server](http://pgp.mi
Website development setup
-Prepare to update the Beam website by following the [website development
-instructions]({{ site.baseurl }}/contribute/website-contributions/).
+Updating the Beam website requires submitting PRs to both the main
`apache/beam`
+repo and the `apache/beam-site` repo. The first contains most of the website
Review comment:
done
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: 151863)
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)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151866=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151866 ] 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: swegner closed pull request #6533: [BEAM-4501] Update website contribution and release docs URL: https://github.com/apache/beam/pull/6533 This is a PR merged from a forked repository. As GitHub hides the original diff on merge, it is displayed below for the sake of provenance: As this is a foreign pull request (from a fork), the diff is supplied below (as it won't show otherwise due to GitHub magic): diff --git a/website/README.md b/website/README.md index 0fe188268bb..acf79f91c4a 100644 --- a/website/README.md +++ b/website/README.md @@ -1,16 +1,24 @@ -# Apache Beam website - -_**The website source code is currently being migrated from -https://github.com/apache/beam-site, but is not yet ready. Please -continue to contribute changes at -[apache/beam-site](https://github.com/apache/beam-site) according to -the [website contribution guide](https://beam.apache.org/contribute/#contributing-to-the-website). -You can track migration progress via -[[BEAM-4493]](https://issues.apache.org/jira/browse/BEAM-4493).**_ - -This is the website for [Apache Beam](https://beam.apache.org/), hosted at: - -https://beam.apache.org/ + + +These are the main sources of the website for Apache Beam, hosted at +https://beam.apache.org/. ## About this site @@ -18,55 +26,32 @@ The Beam website is built using [Jekyll](http://jekyllrb.com/). Additionally, for additional formatting capabilities, this website uses [Twitter Bootstrap](http://getbootstrap.com/). -### Repository Structure - -This repository contains: - -1. `src/`: the source of the site, including markdown files containing the bulk of the content -1. `content/`: html generated from the markdown (which is what is actually hosted on the website) - -## Development Workflow - -### Setup - -You need Ruby version >= 2.2.0 to build the project. - -Install [Ruby Gems](https://rubygems.org/pages/download), a package management framework for Ruby. +Documentation generated from source code, such as Javadoc and Pydoc, is stored +separately on the [beam-site +repository](https://github.com/apache/beam-site/tree/release-docs). -Install [Bundler](http://bundler.io/v1.3/rationale.html), which we use to specify dependencies and ensure -a consistent environment for building the website, even across multiple developers on different machines: +## Active development -$ gem install bundler +Website development requires Docker installed if you wish to preview changes and +run website tests. -Use Bundler to download the versions of each dependency specified in the website's `Gemfile.lock`, -including [Jekyll](https://jekyllrb.com/): +The following command is used to build and serve the website locally. -$ bundle install --deployment +$ ./gradlew -PpublishJekyllPort :beam-website:serveWebsite -This will install a number of gems in a local `./vendor` directory. +Any changes made locally will trigger a rebuild of the website. -### Active development +Websites tests may be run using this command: -Launch Jekyll via Bundler in order to guarantee that the appropriate versions of the dependencies are used: +$ ./gradlew :beam-website:testWebsite -$ bundle exec jekyll serve +## Website push -Jekyll will start a webserver on port `4000`. As you make changes to the -content, Jekyll will rebuild it automatically. This is helpful if you want to see -how your changes will render in realtime. - -In addition, check for dead links and the like by running the tests via: - -$ bundle exec rake test - -Running Jekyll may cause the `content/` directory to be generated. -Merging autogenerated content can get tricky, so regenerating content is -responsibility of the committer doing the final merge of your PR, and -your PR should not contain changes to that directory. - -Before sending the PR for review, please run: - -$ git checkout -- content +After a PR is merged, a background Jenkins job will automatically generate and +push [website +content](https://github.com/apache/beam/tree/asf-site/website/generated-content) +to the asf-site branch. This content is later picked up and pushed to +https://beam.apache.org/. ## Additional Information @@ -87,19 +72,3 @@ and then run `bundle update`, which will regenerate the complete `Gemfile.lock`. Make sure that the updated `Gemfile.lock` is included in your pull request. For more information, see the Bundler [documentation](http://bundler.io/v1.3/rationale.html). -## Apache License - -Except as otherwise noted this software is licensed under the -[Apache License,
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151731=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151731 ] ASF GitHub Bot logged work on BEAM-4501: Author: ASF GitHub Bot Created on: 05/Oct/18 17:14 Start Date: 05/Oct/18 17:14 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_r223079424 ## File path: website/README.md ## @@ -1,72 +1,57 @@ -# Apache Beam website - -_**The website source code is currently being migrated from -https://github.com/apache/beam-site, but is not yet ready. Please -continue to contribute changes at -[apache/beam-site](https://github.com/apache/beam-site) according to -the [website contribution guide](https://beam.apache.org/contribute/#contributing-to-the-website). -You can track migration progress via -[[BEAM-4493]](https://issues.apache.org/jira/browse/BEAM-4493).**_ - -This is the website for [Apache Beam](https://beam.apache.org/), hosted at: - -https://beam.apache.org/ + + +These are the main sources of the website for Apache Beam, hosted at +https://beam.apache.org/. ## About this site The Beam website is built using [Jekyll](http://jekyllrb.com/). Additionally, for additional formatting capabilities, this website uses [Twitter Bootstrap](http://getbootstrap.com/). -### Repository Structure - -This repository contains: - -1. `src/`: the source of the site, including markdown files containing the bulk of the content -1. `content/`: html generated from the markdown (which is what is actually hosted on the website) - -## Development Workflow - -### Setup - -You need Ruby version >= 2.2.0 to build the project. - -Install [Ruby Gems](https://rubygems.org/pages/download), a package management framework for Ruby. +Documentation generated from source code, such as Javadoc and Pydoc, is stored +separately on the [beam-site +repository](https://github.com/apache/beam-site/tree/release-docs). -Install [Bundler](http://bundler.io/v1.3/rationale.html), which we use to specify dependencies and ensure -a consistent environment for building the website, even across multiple developers on different machines: +## Active development -$ gem install bundler +Website development requires Docker installed if you wish to preview changes and +run website tests. -Use Bundler to download the versions of each dependency specified in the website's `Gemfile.lock`, -including [Jekyll](https://jekyllrb.com/): +The following command is used to build and serve the website locally. -$ bundle install --deployment +$ ./gradlew -PpublishJekyllPort :beam-website:serveWebsite Review comment: I think it's simple: you just copy and paste the line. 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: 151731) Time Spent: 5h (was: 4h 50m) > 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 > Remaining Estimate: 0h > -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151724=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151724
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 05/Oct/18 17:11
Start Date: 05/Oct/18 17:11
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_r223078705
##
File path: website/build.gradle
##
@@ -65,8 +65,12 @@ task createDockerContainer(type: Exec) {
ext.containerId = {
return standardOutput.toString().trim()
}
+ def extraOptions = ''
+ if (project.hasProperty('publishJekyllPort')) {
+extraOptions = '-p 127.0.0.1:4000:4000'
Review comment:
I'm not that Gradle fluent. :)
What I wanted was to set this option for createDockerContainer, but only if
gradle is asked to run task serveWebsite. So the option wouldn't be set on
pre/post-commits, where it might cause them to fail (if port 4000 is already
taken).
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: 151724)
Time Spent: 4h 50m (was: 4h 40m)
> 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 50m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151682=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151682
]
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_r223070024
##
File path: website/build.gradle
##
@@ -65,8 +65,12 @@ task createDockerContainer(type: Exec) {
ext.containerId = {
return standardOutput.toString().trim()
}
+ def extraOptions = ''
+ if (project.hasProperty('publishJekyllPort')) {
+extraOptions = '-p 127.0.0.1:4000:4000'
Review comment:
Can you add a quick comment about what this does? I assume website
contributors are not all Docker fluent (I'm not).
[Docker
docs](https://docs.docker.com/v17.09/engine/reference/commandline/create/)
describe it as "Publish a container’s port(s) to the host", although I don't
find that totally intuitive.
Would it be correct to say something like: "Specify `-PpublishJekyllPort` on
the Gradle commandline to serve the website locally at http://localhost:4000; ?
Is my understanding correct that if this option isn't specified, the served
website is inaccessible? That seems not very usable.
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: 151682)
Time Spent: 4h 20m (was: 4h 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: 4h 20m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151684=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151684 ] 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_r223068066 ## File path: website/README.md ## @@ -1,72 +1,57 @@ -# Apache Beam website - -_**The website source code is currently being migrated from -https://github.com/apache/beam-site, but is not yet ready. Please -continue to contribute changes at -[apache/beam-site](https://github.com/apache/beam-site) according to -the [website contribution guide](https://beam.apache.org/contribute/#contributing-to-the-website). -You can track migration progress via -[[BEAM-4493]](https://issues.apache.org/jira/browse/BEAM-4493).**_ - -This is the website for [Apache Beam](https://beam.apache.org/), hosted at: - -https://beam.apache.org/ + + +These are the main sources of the website for Apache Beam, hosted at +https://beam.apache.org/. ## About this site The Beam website is built using [Jekyll](http://jekyllrb.com/). Additionally, for additional formatting capabilities, this website uses [Twitter Bootstrap](http://getbootstrap.com/). -### Repository Structure - -This repository contains: - -1. `src/`: the source of the site, including markdown files containing the bulk of the content -1. `content/`: html generated from the markdown (which is what is actually hosted on the website) - -## Development Workflow - -### Setup - -You need Ruby version >= 2.2.0 to build the project. - -Install [Ruby Gems](https://rubygems.org/pages/download), a package management framework for Ruby. +Documentation generated from source code, such as Javadoc and Pydoc, is stored +separately on the [beam-site +repository](https://github.com/apache/beam-site/tree/release-docs). -Install [Bundler](http://bundler.io/v1.3/rationale.html), which we use to specify dependencies and ensure -a consistent environment for building the website, even across multiple developers on different machines: +## Active development -$ gem install bundler +Website development requires Docker installed if you wish to preview changes and +run website tests. -Use Bundler to download the versions of each dependency specified in the website's `Gemfile.lock`, -including [Jekyll](https://jekyllrb.com/): +The following command is used to build and serve the website locally. -$ bundle install --deployment +$ ./gradlew -PpublishJekyllPort :beam-website:serveWebsite Review comment: Is specifying `-PpublishJekyllPort` necessary? It would be nice to make the default invocation as simple as possible. 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: 151684) Time Spent: 4h 40m (was: 4.5h) > 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 40m > Remaining Estimate: 0h > -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151681=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
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151683=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151683
]
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_r223070725
##
File path: website/src/contribute/release-guide.md
##
@@ -167,8 +167,23 @@ please submit your GPG public key into [MIT PGP Public
Key Server](http://pgp.mi
Website development setup
-Prepare to update the Beam website by following the [website development
-instructions]({{ site.baseurl }}/contribute/website-contributions/).
+Updating the Beam website requires submitting PRs to both the main
`apache/beam`
+repo and the `apache/beam-site` repo. The first contains most of the website
Review comment:
Should be switched:
"The first contains reference manual generated from SDK code, while the
second contains most of the website sources."
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: 151683)
Time Spent: 4.5h (was: 4h 20m)
> 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: 4.5h
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151453=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151453
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 05/Oct/18 00:29
Start Date: 05/Oct/18 00:29
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_r222857134
##
File path: website/build.gradle
##
@@ -49,7 +49,7 @@ task createDockerContainer(type: Exec) {
return standardOutput.toString().trim()
}
commandLine '/bin/bash', '-c',
-"docker create -v $project.rootDir:$dockerWorkDir -u \$(id -u):\$(id -g)
$dockerImageTag"
+"docker create -v $project.rootDir:$dockerWorkDir -u \$(id -u):\$(id -g)
-p 127.0.0.1:4000:4000 $dockerImageTag"
Review comment:
It will fail if two of these tasks try to run concurrently (could happen on
Jenkins). I added a property to enable this port publishing, which should also
reduce any possible attack vectors on Jenkins machines.
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: 151453)
Time Spent: 3h 40m (was: 3.5h)
> 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: 3h 40m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151455=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151455
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 05/Oct/18 00:29
Start Date: 05/Oct/18 00:29
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_r222860478
##
File path: website/src/contribute/release-guide.md
##
@@ -555,33 +570,40 @@ 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 in `current.md` files, merge these PRs in the order listed.
-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.
+The second pull request is against the `apache/beam-site` repo, on the
+`asf-site` branch.
-Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/javadoc/) page, as follows:
+* Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/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} content/documentation/sdks/javadoc/${RELEASE}`.
+* Add the new Pydoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/pydoc/) page, as follows:
+ * Copy the generated Pydoc into the website repository: `cp -r ${PYDOC_ROOT}
content/documentation/sdks/pydoc/${RELEASE}`.
+ * Remove `.doctrees` directory.
+* Set up the necessary git commands to account for new and deleted files.
Review comment:
Yeah, I believe these should be brand new directories, so no deletions are
necessary.
(I copied this text from elsewhere.)
https://stackoverflow.com/a/26039014/63302
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: 151455)
Time Spent: 3h 50m (was: 3h 40m)
> 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: 3h 50m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151448=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151448
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 05/Oct/18 00:29
Start Date: 05/Oct/18 00:29
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_r222857674
##
File path: website/src/contribute/release-guide.md
##
@@ -167,8 +167,23 @@ please submit your GPG public key into [MIT PGP Public
Key Server](http://pgp.mi
Website development setup
-Prepare to update the Beam website by following the [website development
-instructions]({{ site.baseurl }}/contribute/website-contributions/).
+Updating the Beam website requires access to both the man `apache/beam` repo
and
+the `apache/beam-site` repo. The first contains most of the website sources,
+while the second contains reference manual generated from SDK code.
+
+You should already have setup access to `apache/beam`. Setting up access to
Review comment:
Clarified access to be 'submitting a PR'.
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: 151448)
Time Spent: 2h 50m (was: 2h 40m)
> 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: 2h 50m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151450=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151450 ] ASF GitHub Bot logged work on BEAM-4501: Author: ASF GitHub Bot Created on: 05/Oct/18 00:29 Start Date: 05/Oct/18 00:29 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_r222856901 ## File path: website/README.md ## @@ -68,6 +80,12 @@ Before sending the PR for review, please run: $ git checkout -- content +## Website generation + +After a PR is merged, a background Jenkins job will run and update the website's +[generated-content +directory](https://github.com/apache/beam/tree/asf-site/website/generated-content). Review comment: Done. 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: 151450) Time Spent: 3h 10m (was: 3h) > 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: 3h 10m > Remaining Estimate: 0h > -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151449=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151449
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 05/Oct/18 00:29
Start Date: 05/Oct/18 00:29
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_r222860561
##
File path: website/src/contribute/release-guide.md
##
@@ -555,33 +570,40 @@ 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 in `current.md` files, merge these PRs in the order listed.
-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.
+The second pull request is against the `apache/beam-site` repo, on the
+`asf-site` branch.
-Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/javadoc/) page, as follows:
+* Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/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} content/documentation/sdks/javadoc/${RELEASE}`.
+* Add the new Pydoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/pydoc/) page, as follows:
+ * Copy the generated Pydoc into the website repository: `cp -r ${PYDOC_ROOT}
content/documentation/sdks/pydoc/${RELEASE}`.
+ * Remove `.doctrees` directory.
+* Set up the necessary git commands to account for new and deleted files.
-* 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]({{ site.baseurl
}}/documentation/sdks/pydoc/) page, as follows:
+The first pull request is against the `apache/beam` repo, on the `master`
Review comment:
done
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: 151449)
Time Spent: 3h (was: 2h 50m)
> 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: 3h
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151452=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151452
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 05/Oct/18 00:29
Start Date: 05/Oct/18 00:29
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_r222859301
##
File path: website/src/contribute/release-guide.md
##
@@ -555,33 +570,40 @@ 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 in `current.md` files, merge these PRs in the order listed.
-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.
+The second pull request is against the `apache/beam-site` repo, on the
+`asf-site` branch.
-Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/javadoc/) page, as follows:
+* Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/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} content/documentation/sdks/javadoc/${RELEASE}`.
Review comment:
done
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: 151452)
Time Spent: 3.5h (was: 3h 20m)
> 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: 3.5h
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151458=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151458
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 05/Oct/18 00:29
Start Date: 05/Oct/18 00:29
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_r222861136
##
File path: website/src/contribute/release-guide.md
##
@@ -555,33 +570,40 @@ 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 in `current.md` files, merge these PRs in the order listed.
-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.
+The second pull request is against the `apache/beam-site` repo, on the
+`asf-site` branch.
-Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/javadoc/) page, as follows:
+* Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/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} content/documentation/sdks/javadoc/${RELEASE}`.
+* Add the new Pydoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/pydoc/) page, as follows:
+ * Copy the generated Pydoc into the website repository: `cp -r ${PYDOC_ROOT}
content/documentation/sdks/pydoc/${RELEASE}`.
+ * Remove `.doctrees` directory.
+* Set up the necessary git commands to account for new and deleted files.
Review comment:
Added above.
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: 151458)
Time Spent: 4h (was: 3h 50m)
> 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
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151457=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151457
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 05/Oct/18 00:29
Start Date: 05/Oct/18 00:29
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_r222863319
##
File path: website/src/contribute/release-guide.md
##
@@ -555,33 +570,40 @@ 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 in `current.md` files, merge these PRs in the order listed.
-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.
+The second pull request is against the `apache/beam-site` repo, on the
+`asf-site` branch.
-Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/javadoc/) page, as follows:
+* Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/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} content/documentation/sdks/javadoc/${RELEASE}`.
+* Add the new Pydoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/pydoc/) page, as follows:
+ * Copy the generated Pydoc into the website repository: `cp -r ${PYDOC_ROOT}
content/documentation/sdks/pydoc/${RELEASE}`.
+ * Remove `.doctrees` directory.
+* Set up the necessary git commands to account for new and deleted files.
-* 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]({{ site.baseurl
}}/documentation/sdks/pydoc/) page, as follows:
+The first 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 `redirect_to` in `/website/src/documentation/sdks/*/current.md` to
point to the
Review comment:
Changed to update .htaccess.
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: 151457)
> 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
>
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151454=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151454
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 05/Oct/18 00:29
Start Date: 05/Oct/18 00:29
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_r222857243
##
File path: website/src/contribute/release-guide.md
##
@@ -167,8 +167,23 @@ please submit your GPG public key into [MIT PGP Public
Key Server](http://pgp.mi
Website development setup
-Prepare to update the Beam website by following the [website development
-instructions]({{ site.baseurl }}/contribute/website-contributions/).
+Updating the Beam website requires access to both the man `apache/beam` repo
and
Review comment:
done
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: 151454)
Time Spent: 3h 40m (was: 3.5h)
> 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: 3h 40m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151456=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151456
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 05/Oct/18 00:29
Start Date: 05/Oct/18 00:29
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_r222857845
##
File path: website/src/contribute/release-guide.md
##
@@ -555,33 +570,40 @@ 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 in `current.md` files, merge these PRs in the order listed.
-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.
+The second pull request is against the `apache/beam-site` repo, on the
Review comment:
fixed
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: 151456)
Time Spent: 3h 50m (was: 3h 40m)
> 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: 3h 50m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151451=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151451
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 05/Oct/18 00:29
Start Date: 05/Oct/18 00:29
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_r222859211
##
File path: website/src/contribute/release-guide.md
##
@@ -555,33 +570,40 @@ 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 in `current.md` files, merge these PRs in the order listed.
-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.
+The second pull request is against the `apache/beam-site` repo, on the
+`asf-site` branch.
Review comment:
udpated
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: 151451)
Time Spent: 3h 20m (was: 3h 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: 3h 20m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151426=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151426 ] ASF GitHub Bot logged work on BEAM-4501: Author: ASF GitHub Bot Created on: 04/Oct/18 23:26 Start Date: 04/Oct/18 23:26 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_r222856609 ## File path: website/README.md ## @@ -18,14 +18,26 @@ The Beam website is built using [Jekyll](http://jekyllrb.com/). Additionally, for additional formatting capabilities, this website uses [Twitter Bootstrap](http://getbootstrap.com/). -### Repository Structure +Documentation generated from source code, such as Javadoc and Pydoc, is stored +separately on the [beam-site +repository](https://github.com/apache/beam-site/tree/asf-site/content/documentation/sdks). -This repository contains: +## Development Workflow with Docker -1. `src/`: the source of the site, including markdown files containing the bulk of the content -1. `content/`: html generated from the markdown (which is what is actually hosted on the website) +### Active development + +If you have Docker configured on your machine, the following command may be used +to build and serve the website locally. + +$ ./gradlew :beam-website:serveWebsite + +Any changes made locally will trigger a rebuild of the website. -## Development Workflow +You can also run website tests using this command: + +$ ./gradlew :beam-website:testWebsite + +## Development Workflow without Docker ### Setup Review comment: I'll go ahead and remove the more complicated non-docker steps. 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: 151426) Time Spent: 2h 40m (was: 2.5h) > 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: 2h 40m > Remaining Estimate: 0h > -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=151422=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-151422 ] ASF GitHub Bot logged work on BEAM-4501: Author: ASF GitHub Bot Created on: 04/Oct/18 23:05 Start Date: 04/Oct/18 23:05 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_r222853217 ## File path: website/README.md ## @@ -68,6 +80,12 @@ Before sending the PR for review, please run: $ git checkout -- content Review comment: If you run Jekyll manually, it'll still create a `./generated-content` directory in the CWD. The Gradle task takes care to run under `build/website`. I'll go ahead and remove the Jekyll commands to make this guide shorter and less TLDR-ish. 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: 151422) Time Spent: 2.5h (was: 2h 20m) > 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: 2.5h > Remaining Estimate: 0h > -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150535=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150535 ] ASF GitHub Bot logged work on BEAM-4501: Author: ASF GitHub Bot Created on: 02/Oct/18 21:34 Start Date: 02/Oct/18 21:34 Worklog Time Spent: 10m Work Description: tweise 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_r222119885 ## File path: website/README.md ## @@ -18,14 +18,26 @@ The Beam website is built using [Jekyll](http://jekyllrb.com/). Additionally, for additional formatting capabilities, this website uses [Twitter Bootstrap](http://getbootstrap.com/). -### Repository Structure +Documentation generated from source code, such as Javadoc and Pydoc, is stored +separately on the [beam-site +repository](https://github.com/apache/beam-site/tree/asf-site/content/documentation/sdks). -This repository contains: +## Development Workflow with Docker -1. `src/`: the source of the site, including markdown files containing the bulk of the content -1. `content/`: html generated from the markdown (which is what is actually hosted on the website) +### Active development + +If you have Docker configured on your machine, the following command may be used +to build and serve the website locally. + +$ ./gradlew :beam-website:serveWebsite + +Any changes made locally will trigger a rebuild of the website. -## Development Workflow +You can also run website tests using this command: + +$ ./gradlew :beam-website:testWebsite + +## Development Workflow without Docker ### Setup Review comment: Some of it may be of interest for maintaining the docker image itself, but should be moved out of the way for regular web site contributor. 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: 150535) Time Spent: 2h 20m (was: 2h 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: 2h 20m > Remaining Estimate: 0h > -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150427=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150427
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 02/Oct/18 15:58
Start Date: 02/Oct/18 15:58
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_r222006444
##
File path: website/src/contribute/release-guide.md
##
@@ -167,8 +167,23 @@ please submit your GPG public key into [MIT PGP Public
Key Server](http://pgp.mi
Website development setup
-Prepare to update the Beam website by following the [website development
-instructions]({{ site.baseurl }}/contribute/website-contributions/).
+Updating the Beam website requires access to both the man `apache/beam` repo
and
+the `apache/beam-site` repo. The first contains most of the website sources,
+while the second contains reference manual generated from SDK code.
+
+You should already have setup access to `apache/beam`. Setting up access to
Review comment:
Here and above, can you qualify what you mean by "access" to the repo? There
are different permission sets granted to different groups:
* Anyone can submit a PR to the repo
* Committers can merge PRs and push to branches
* PMC can update various repo settings 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: 150427)
Time Spent: 1h 20m (was: 1h 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: 1h 20m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150432=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150432
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 02/Oct/18 15:58
Start Date: 02/Oct/18 15:58
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_r222009824
##
File path: website/src/contribute/release-guide.md
##
@@ -555,33 +570,40 @@ 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 in `current.md` files, merge these PRs in the order listed.
-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.
+The second pull request is against the `apache/beam-site` repo, on the
+`asf-site` branch.
-Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/javadoc/) page, as follows:
+* Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/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} content/documentation/sdks/javadoc/${RELEASE}`.
+* Add the new Pydoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/pydoc/) page, as follows:
+ * Copy the generated Pydoc into the website repository: `cp -r ${PYDOC_ROOT}
content/documentation/sdks/pydoc/${RELEASE}`.
+ * Remove `.doctrees` directory.
+* Set up the necessary git commands to account for new and deleted files.
-* 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]({{ site.baseurl
}}/documentation/sdks/pydoc/) page, as follows:
+The first pull request is against the `apache/beam` repo, on the `master`
Review comment:
`first` -> `second`
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: 150432)
Time Spent: 2h (was: 1h 50m)
> 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: 2h
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150428=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150428 ] ASF GitHub Bot logged work on BEAM-4501: Author: ASF GitHub Bot Created on: 02/Oct/18 15:58 Start Date: 02/Oct/18 15:58 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_r222003798 ## File path: website/README.md ## @@ -68,6 +80,12 @@ Before sending the PR for review, please run: $ git checkout -- content Review comment: The `git checkout -- content` step is no longer necessary; this was to ensure generated content does not get committed, but this should now be covered in the .gitignore file. 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: 150428) Time Spent: 1.5h (was: 1h 20m) > 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: 1.5h > Remaining Estimate: 0h > -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150421=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150421
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 02/Oct/18 15:58
Start Date: 02/Oct/18 15:58
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_r222009074
##
File path: website/src/contribute/release-guide.md
##
@@ -555,33 +570,40 @@ 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 in `current.md` files, merge these PRs in the order listed.
-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.
+The second pull request is against the `apache/beam-site` repo, on the
+`asf-site` branch.
-Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/javadoc/) page, as follows:
+* Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/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} content/documentation/sdks/javadoc/${RELEASE}`.
+* Add the new Pydoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/pydoc/) page, as follows:
+ * Copy the generated Pydoc into the website repository: `cp -r ${PYDOC_ROOT}
content/documentation/sdks/pydoc/${RELEASE}`.
+ * Remove `.doctrees` directory.
+* Set up the necessary git commands to account for new and deleted files.
Review comment:
It's helpful to provide the exact commands so there is no ambiguity for the
release manager. I believe it should be `git add -A javadoc/ pydoc/`. There
should be no deleted files, right?
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: 150421)
Time Spent: 40m (was: 0.5h)
> 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: 40m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150431=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150431
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 02/Oct/18 15:58
Start Date: 02/Oct/18 15:58
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_r222004950
##
File path: website/build.gradle
##
@@ -49,7 +49,7 @@ task createDockerContainer(type: Exec) {
return standardOutput.toString().trim()
}
commandLine '/bin/bash', '-c',
-"docker create -v $project.rootDir:$dockerWorkDir -u \$(id -u):\$(id -g)
$dockerImageTag"
+"docker create -v $project.rootDir:$dockerWorkDir -u \$(id -u):\$(id -g)
-p 127.0.0.1:4000:4000 $dockerImageTag"
Review comment:
I'm still learning Docker, so just checking: this binding will work for
local execution and on Jenkins?
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: 150431)
Time Spent: 2h (was: 1h 50m)
> 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: 2h
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150423=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150423
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 02/Oct/18 15:58
Start Date: 02/Oct/18 15:58
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_r222007343
##
File path: website/src/contribute/release-guide.md
##
@@ -555,33 +570,40 @@ 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 in `current.md` files, merge these PRs in the order listed.
-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.
+The second pull request is against the `apache/beam-site` repo, on the
Review comment:
`second` -> `first` ?
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: 150423)
> 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: 50m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150424=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150424 ] ASF GitHub Bot logged work on BEAM-4501: Author: ASF GitHub Bot Created on: 02/Oct/18 15:58 Start Date: 02/Oct/18 15:58 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_r222004421 ## File path: website/README.md ## @@ -68,6 +80,12 @@ Before sending the PR for review, please run: $ git checkout -- content +## Website generation + +After a PR is merged, a background Jenkins job will run and update the website's +[generated-content +directory](https://github.com/apache/beam/tree/asf-site/website/generated-content). Review comment: Mention in text that this is on the `asf-site` branch? "After a PR is merged, a background Jenkins job will run to push generated HTML to the asf-site branch" 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: 150424) Time Spent: 1h (was: 50m) > 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: 1h > Remaining Estimate: 0h > -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150422=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150422
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 02/Oct/18 15:58
Start Date: 02/Oct/18 15:58
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_r222009753
##
File path: website/src/contribute/release-guide.md
##
@@ -555,33 +570,40 @@ 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 in `current.md` files, merge these PRs in the order listed.
-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.
+The second pull request is against the `apache/beam-site` repo, on the
+`asf-site` branch.
-Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/javadoc/) page, as follows:
+* Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/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} content/documentation/sdks/javadoc/${RELEASE}`.
+* Add the new Pydoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/pydoc/) page, as follows:
+ * Copy the generated Pydoc into the website repository: `cp -r ${PYDOC_ROOT}
content/documentation/sdks/pydoc/${RELEASE}`.
+ * Remove `.doctrees` directory.
+* Set up the necessary git commands to account for new and deleted files.
Review comment:
It's worth noting that there is a small delay for the publishing mechanism
to make new content live on the website. For example:
> Once the PR is merged, the new contents will get picked up automatically
and served to the Beam website, usually within an hour.
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: 150422)
Time Spent: 50m (was: 40m)
> 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: 50m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150430=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150430
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 02/Oct/18 15:58
Start Date: 02/Oct/18 15:58
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_r222007490
##
File path: website/src/contribute/release-guide.md
##
@@ -555,33 +570,40 @@ 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 in `current.md` files, merge these PRs in the order listed.
-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.
+The second pull request is against the `apache/beam-site` repo, on the
+`asf-site` branch.
Review comment:
Note: the plan is for javadocs / pydocs to live on the `release-docs` branch
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: 150430)
Time Spent: 1h 50m (was: 1h 40m)
> 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: 1h 50m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150420=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150420 ] ASF GitHub Bot logged work on BEAM-4501: Author: ASF GitHub Bot Created on: 02/Oct/18 15:58 Start Date: 02/Oct/18 15:58 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_r222002789 ## File path: website/README.md ## @@ -18,14 +18,26 @@ The Beam website is built using [Jekyll](http://jekyllrb.com/). Additionally, for additional formatting capabilities, this website uses [Twitter Bootstrap](http://getbootstrap.com/). -### Repository Structure +Documentation generated from source code, such as Javadoc and Pydoc, is stored +separately on the [beam-site +repository](https://github.com/apache/beam-site/tree/asf-site/content/documentation/sdks). -This repository contains: +## Development Workflow with Docker -1. `src/`: the source of the site, including markdown files containing the bulk of the content -1. `content/`: html generated from the markdown (which is what is actually hosted on the website) +### Active development + +If you have Docker configured on your machine, the following command may be used +to build and serve the website locally. + +$ ./gradlew :beam-website:serveWebsite + +Any changes made locally will trigger a rebuild of the website. -## Development Workflow +You can also run website tests using this command: + +$ ./gradlew :beam-website:testWebsite + +## Development Workflow without Docker ### Setup Review comment: Are these setup steps still necessary? I believe the website build all happens within a Docker container now. Also, do you think we should continue to document the raw bundle / jekyll commands, or recommend that users only build/test via the gradle wrapper? My preference would be to only use gradle so we can change what's underneath more easily. 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: 150420) Time Spent: 0.5h (was: 20m) > 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: 0.5h > Remaining Estimate: 0h > -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150425=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150425
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 02/Oct/18 15:58
Start Date: 02/Oct/18 15:58
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_r222008608
##
File path: website/src/contribute/release-guide.md
##
@@ -555,33 +570,40 @@ 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 in `current.md` files, merge these PRs in the order listed.
-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.
+The second pull request is against the `apache/beam-site` repo, on the
+`asf-site` branch.
-Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/javadoc/) page, as follows:
+* Add the new Javadoc to [SDK API Reference page]({{ site.baseurl
}}/documentation/sdks/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} content/documentation/sdks/javadoc/${RELEASE}`.
Review comment:
The planned directory after migration removes the
`content/documentation/sdks/` prefix. You can see the planned directory
structure here: https://github.com/swegner/beam-site/tree/release-docs
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: 150425)
> 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: 1h
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150429=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150429 ] ASF GitHub Bot logged work on BEAM-4501: Author: ASF GitHub Bot Created on: 02/Oct/18 15:58 Start Date: 02/Oct/18 15:58 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_r222001852 ## File path: website/README.md ## @@ -18,14 +18,26 @@ The Beam website is built using [Jekyll](http://jekyllrb.com/). Additionally, for additional formatting capabilities, this website uses [Twitter Bootstrap](http://getbootstrap.com/). -### Repository Structure +Documentation generated from source code, such as Javadoc and Pydoc, is stored +separately on the [beam-site +repository](https://github.com/apache/beam-site/tree/asf-site/content/documentation/sdks). Review comment: Eventually this will be migrated to a different path on a separate branch. The current plan is https://github.com/apache/beam-site/tree/release-docs. The reason I'm creating a new branch rather than re-use the existing `asf-site` branch is to ease the migration; currently we're publishing the contents of `asf-site`, so we're not able to easily restructure those contents without breaking the live site. 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: 150429) Time Spent: 1h 40m (was: 1.5h) > 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: 1h 40m > Remaining Estimate: 0h > -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[
https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150426=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150426
]
ASF GitHub Bot logged work on BEAM-4501:
Author: ASF GitHub Bot
Created on: 02/Oct/18 15:58
Start Date: 02/Oct/18 15:58
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_r222005608
##
File path: website/src/contribute/release-guide.md
##
@@ -167,8 +167,23 @@ please submit your GPG public key into [MIT PGP Public
Key Server](http://pgp.mi
Website development setup
-Prepare to update the Beam website by following the [website development
-instructions]({{ site.baseurl }}/contribute/website-contributions/).
+Updating the Beam website requires access to both the man `apache/beam` repo
and
Review comment:
Typo: `man` -> `main`
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: 150426)
Time Spent: 1h 10m (was: 1h)
> 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: 1h 10m
> Remaining Estimate: 0h
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150254=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150254 ] ASF GitHub Bot logged work on BEAM-4501: Author: ASF GitHub Bot Created on: 01/Oct/18 23:17 Start Date: 01/Oct/18 23:17 Worklog Time Spent: 10m Work Description: udim commented on issue #6533: [BEAM-4501] Update website contribution and release docs URL: https://github.com/apache/beam/pull/6533#issuecomment-426095130 R: @charlesccychen Fix for website test failure is pending: https://github.com/apache/beam/pull/6531/files CC: @alanmyrvold @swegner 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: 150254) Time Spent: 20m (was: 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: 20m > Remaining Estimate: 0h > -- This message was sent by Atlassian JIRA (v7.6.3#76005)
[jira] [Work logged] (BEAM-4501) Update contribution guide for new website contribution process
[ https://issues.apache.org/jira/browse/BEAM-4501?focusedWorklogId=150251=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-150251 ] ASF GitHub Bot logged work on BEAM-4501: Author: ASF GitHub Bot Created on: 01/Oct/18 23:12 Start Date: 01/Oct/18 23:12 Worklog Time Spent: 10m Work Description: udim opened a new pull request #6533: [BEAM-4501] Update website contribution and release docs URL: https://github.com/apache/beam/pull/6533 This also includes BEAM-4498 (which was accidentally closed). Follow this checklist to help us incorporate your contribution quickly and easily: - [ ] Format the pull request title like `[BEAM-XXX] Fixes bug in ApproximateQuantiles`, where you replace `BEAM-XXX` with the appropriate JIRA issue, if applicable. This will automatically link the pull request to the issue. - [ ] If this contribution is large, please file an Apache [Individual Contributor License Agreement](https://www.apache.org/licenses/icla.pdf). It will help us expedite review of your Pull Request if you tag someone (e.g. `@username`) to look at it. Post-Commit Tests Status (on master branch) Lang | SDK | Apex | Dataflow | Flink | Gearpump | Samza | Spark --- | --- | --- | --- | --- | --- | --- | --- Go | [](https://builds.apache.org/job/beam_PostCommit_Go_GradleBuild/lastCompletedBuild/) | --- | --- | --- | --- | --- | --- Java | [](https://builds.apache.org/job/beam_PostCommit_Java_GradleBuild/lastCompletedBuild/) | [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Apex_Gradle/lastCompletedBuild/) | [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Dataflow_Gradle/lastCompletedBuild/) | [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Flink_Gradle/lastCompletedBuild/) | [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Gearpump_Gradle/lastCompletedBuild/) | [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Samza_Gradle/lastCompletedBuild/) | [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Spark_Gradle/lastCompletedBuild/) Python | [](https://builds.apache.org/job/beam_PostCommit_Python_Verify/lastCompletedBuild/) | --- | [](https://builds.apache.org/job/beam_PostCommit_Py_VR_Dataflow/lastCompletedBuild/) [](https://builds.apache.org/job/beam_PostCommit_Py_ValCont/lastCompletedBuild/) | [](https://builds.apache.org/job/beam_PostCommit_Python_VR_Flink/lastCompletedBuild/) | --- | --- | --- 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: 150251) Time Spent: 10m Remaining Estimate: 0h > 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:
