michaelmior commented on a change in pull request #2708: URL: https://github.com/apache/calcite/pull/2708#discussion_r798811722
########## File path: site/README.md ########## @@ -19,10 +19,21 @@ limitations under the License. # Apache Calcite docs site -This directory contains the code for the Apache Calcite web site, -[calcite.apache.org](https://calcite.apache.org/). - -You can build the site manually using your environment or use the docker compose file. +This directory contains the code and templates for generating the Apache Calcite website, +[calcite.apache.org](https://calcite.apache.org/). The actual generated content of the website +is present in [calcite-site](https://github.com/apache/calcite-site) repository. + +We want to deploy project changes (for example, new committers, PMC members or upcoming talks) +immediately, but we want to deploy documentation of project features only when that feature appears +in a release. + +The procedure for deploying the changes to the website is outlined below: Review comment: I would change this to "…deploying changes…" (delete "the") ########## File path: site/README.md ########## @@ -19,10 +19,21 @@ limitations under the License. # Apache Calcite docs site -This directory contains the code for the Apache Calcite web site, -[calcite.apache.org](https://calcite.apache.org/). - -You can build the site manually using your environment or use the docker compose file. +This directory contains the code and templates for generating the Apache Calcite website, +[calcite.apache.org](https://calcite.apache.org/). The actual generated content of the website +is present in [calcite-site](https://github.com/apache/calcite-site) repository. + +We want to deploy project changes (for example, new committers, PMC members or upcoming talks) +immediately, but we want to deploy documentation of project features only when that feature appears +in a release. + +The procedure for deploying the changes to the website is outlined below: +1. Push the commit with the changes to the `master` branch of this repository. +2. Cherry-pick the commit from the `master` branch to the `site` branch of this repository. +3. Checkout the `site` branch and build the website either [manually](#manually) or using +[docker compose](#using-docker) (preferred). Review comment: I would write "docker compose" as either "`docker-compose`" the name of the CLI command or "Docker Compose", the natural language name of the tool. ########## File path: site/_docs/howto.md ########## @@ -949,7 +948,9 @@ Add a release announcement by copying Generate the javadoc, and [preview](http://localhost:4000/news/) the site by following the instructions in [site/README.md]({{ site.sourceRoot }}/site/README.md). Ensure the announcement, javadoc, and release note appear correctly and then publish the site following the instructions -in the same file. +in the same file. Rebase `site` branch with `master` (e.g., `git checkout site && git rebase master`); +at this point there shouldn't be any commits in `site` that are not in `master` so the rebase is Review comment: "…that are not in `master`, so the rebase…" (add comma) ########## File path: site/README.md ########## @@ -19,10 +19,21 @@ limitations under the License. # Apache Calcite docs site -This directory contains the code for the Apache Calcite web site, -[calcite.apache.org](https://calcite.apache.org/). - -You can build the site manually using your environment or use the docker compose file. +This directory contains the code and templates for generating the Apache Calcite website, +[calcite.apache.org](https://calcite.apache.org/). The actual generated content of the website +is present in [calcite-site](https://github.com/apache/calcite-site) repository. Review comment: I would change this to "in *the* …" ########## File path: site/README.md ########## @@ -19,10 +19,21 @@ limitations under the License. # Apache Calcite docs site -This directory contains the code for the Apache Calcite web site, -[calcite.apache.org](https://calcite.apache.org/). - -You can build the site manually using your environment or use the docker compose file. +This directory contains the code and templates for generating the Apache Calcite website, +[calcite.apache.org](https://calcite.apache.org/). The actual generated content of the website +is present in [calcite-site](https://github.com/apache/calcite-site) repository. + +We want to deploy project changes (for example, new committers, PMC members or upcoming talks) +immediately, but we want to deploy documentation of project features only when that feature appears +in a release. + +The procedure for deploying the changes to the website is outlined below: +1. Push the commit with the changes to the `master` branch of this repository. +2. Cherry-pick the commit from the `master` branch to the `site` branch of this repository. +3. Checkout the `site` branch and build the website either [manually](#manually) or using +[docker compose](#using-docker) (preferred). +4. Commit the generated content to the `master` branch of`calcite-site` repository following the Review comment: "…branch of *the* `calcite-site` respostiory…" ########## File path: site/_docs/howto.md ########## @@ -949,7 +948,9 @@ Add a release announcement by copying Generate the javadoc, and [preview](http://localhost:4000/news/) the site by following the instructions in [site/README.md]({{ site.sourceRoot }}/site/README.md). Ensure the announcement, javadoc, and release note appear correctly and then publish the site following the instructions -in the same file. +in the same file. Rebase `site` branch with `master` (e.g., `git checkout site && git rebase master`); Review comment: "Rebase *the* `site` branch…" -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
