[calcite] 38/41: Site: Reorganise website update process in README & howto

[li...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

liyafan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/calcite.git

commit 7a117c76073f4fde3e572d5115a7c46a93614881
Author: Stamatis Zampetakis <za...@gmail.com>
AuthorDate: Tue Feb 1 10:51:30 2022 +0100

    Site: Reorganise website update process in README & howto
    
    1. Highlight the role & existence of two repos at the beginning of
    README.
    2. Provide a high-level overview of the update procedure early on.
    3. Move RM related instructions from README to the appropriate howto
    sections.
    4. Remove git reset/rebase related commands for syncing master & site
    branches from the beginning of the release process cause it is too
    early to rebase then. Mention rebase later towards the end of the
    process.
    
    Close apache/calcite#2708
---
 site/README.md      | 38 +++++++++++++++-----------------------
 site/_docs/howto.md |  7 ++++---
 2 files changed, 19 insertions(+), 26 deletions(-)

diff --git a/site/README.md b/site/README.md
index 90c5fa2..ec9c092 100644
--- a/site/README.md
+++ b/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 sources/templates for generating the Apache Calcite website,
+[calcite.apache.org](https://calcite.apache.org/). The actual generated content of the website
+is present in the [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 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 the `calcite-site` repository following
+the [Pushing to site](#pushing-to-site) instructions.
 
 ## Manually
 
@@ -117,22 +128,3 @@ generate files to `site/target/avatica`, which becomes an
 [avatica](https://calcite.apache.org/avatica)
 sub-directory when deployed. See
 [Avatica site README](../avatica/site/README.md).
-
-## Site branch
-
-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. For this reason, we generally edit the site on the "site" git
-branch.
-
-Before making a release, release manager must ensure that "site" is in
-sync with "master". Immediately after a release, the release manager
-will publish the site, including all of the features that have just
-been released. When making an edit to the site, a Calcite committer
-must commit the change to the git "master" branch (as well as
-git, to publish the site, of course). If the edit is to appear
-on the site immediately, the committer should then cherry-pick the
-change into the "site" branch.  If there have been no feature-related
-changes on the site since the release, then "site" should be a
-fast-forward merge of "master".
diff --git a/site/_docs/howto.md b/site/_docs/howto.md
index ecc9d50..c5d1df1 100644
--- a/site/_docs/howto.md
+++ b/site/_docs/howto.md
@@ -694,8 +694,7 @@ Before you start:
 * Set up signing keys as described above.
 * Make sure you are using JDK 8 (not 9 or 10).
 * Make sure `master` branch and `site` branch are in sync, i.e. there is no commit on `site` that has not
-  been applied also to `master`.
-  This can be achieved by doing `git switch site && git rebase --empty=drop master && git switch master && git reset --hard site`.
+  been applied also to `master`. If you spot missing commits then port them to `master`.
 * Check that `README` and `site/_docs/howto.md` have the correct version number.
 * Check that `site/_docs/howto.md` has the correct Gradle version.
 * Check that `NOTICE` has the current copyright year.
@@ -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 the `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
+essentially a noop.
 
 In JIRA, search for
 [all issues resolved in this release](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CALCITE%20and%20fixVersion%20%3D%201.5.0%20and%20status%20%3D%20Resolved%20and%20resolution%20%3D%20Fixed),