This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/logging-parent.git
commit 5277f72d0b5e4656407c6e6fb21842865f603887
Author: Volkan Yazıcı <vol...@yazi.ci>
AuthorDate: Thu Apr 11 23:11:10 2024 +0200
Update website deployment docs
---
.../ROOT/pages/release-instructions-project.adoc | 29 ++++++++++++-----
src/site/antora/modules/ROOT/pages/usage.adoc | 37 ++++++++++++++++++++++
2 files changed, 58 insertions(+), 8 deletions(-)
diff --git
a/src/site/antora/modules/ROOT/pages/release-instructions-project.adoc
b/src/site/antora/modules/ROOT/pages/release-instructions-project.adoc
index 59f09b0..9f7c6d4 100644
--- a/src/site/antora/modules/ROOT/pages/release-instructions-project.adoc
+++ b/src/site/antora/modules/ROOT/pages/release-instructions-project.adoc
@@ -192,18 +192,31 @@ svn commit -m 'Remove `{project-id}` version `7.8.0`
files released'
[#publish-release-github]
=== In GitHub
-. Run the
{project-github-url}/actions/workflows/deploy-site-pro.yaml[`deploy-site-pro`]
GitHub Actions workflow:
-.. Use the `rel/7.8.0` tag
-.. Verify that {site-url}[the project website] is updated
-. {project-github-url}/releases/new[Create a new release in GitHub]
-.. Use the `rel/7.8.0` tag
-.. Copy release notes from the generated emails
+{project-github-url}/releases/new[Create a new release in GitHub]:
+
+* Use the `rel/7.8.0` tag
+* Copy release notes from the generated emails
+
+[#publish-release-website]
+== Publish the release website
+
+. Merge the `rel/7.8.0` tag (**not** the `release/7.8.0` branch!) to
`main-site-pro` and push it
++
+[source,bash]
+----
+git checkout main-site-pro
+git rebase origin/main-site-pro # Sync with the remote repository
+git merge rel/7.8.0 # Pull changes up to the newly created tag
+git push origin main-site-pro
+----
+. Verify that {project-github-url}/actions/workflows/deploy-site.yaml[the
`deploy-site` workflow] successfully runs the `deploy-site-pro` job
+. Verify that {site-url}[the project website] is updated
[#announce-release]
== Announce the release
-Send the announcement email uploaded to the
https://dist.apache.org/repos/dist/dev/logging/{project-id}[dist.apache.org/repos/dist/**dev**/logging/{project-id}/7.8.0]
Subversion repository
-
+1. Send the announcement email uploaded to the
https://dist.apache.org/repos/dist/dev/logging/{project-id}[dist.apache.org/repos/dist/**dev**/logging/{project-id}/7.8.0]
Subversion repository
++
[WARNING]
====
Make sure your email is sent in plain text, that is,
https://infra.apache.org/contrib-email-tips#nohtml[no HTML]!
diff --git a/src/site/antora/modules/ROOT/pages/usage.adoc
b/src/site/antora/modules/ROOT/pages/usage.adoc
index d4f2fc0..a8e51e9 100644
--- a/src/site/antora/modules/ROOT/pages/usage.adoc
+++ b/src/site/antora/modules/ROOT/pages/usage.adoc
@@ -36,3 +36,40 @@ You can use {project-name} as follows:
*** `src/site/antora/modules/ROOT/pages/release-notes.adoc`
.. Build the website using `./mvnw site`
.. Check out the website generated to `target/site` by pointing a browser to it
+
+== Website deployment
+
+Using `deploy-site-reusable.yaml` reusable GitHub Actions workflow, you can
automate the website deployments for staging and production environments.
+See how
{project-github-url}/blob/main/.github/workflows/deploy-site.yaml[`deploy-site.yaml`
of {project-name}] achieves that using the following repository branching
scheme:
+
+`main`::
+Contains the _sources_ (i.e., AsciiDoc files) to build {site-url-staging}[the
staging website].
+
+`main-site-stg-out`::
+It is populated automatically by the workflow triggered for changes on `main`.
+It contains the _contents_ (i.e., HTML files) of the {site-url-staging}[the
staging website].
+In a nutshell, CI builds `main` and copies the generated `target/site` to
`main-site-stg-out`.
+
+`main-site-pro`::
+Contains the _sources_ (i.e., AsciiDoc files) to build the {site-url}[the
production website].
+It is _manually populated_ by maintainers. For instance,
+** after a release, the release tag is merged to `main-site-pro`
+** when there are minor website fixes in `main` that can also go to the
production website, they are ``cherry-pick``ed onto the `main-site-pro`
+** when there are production-only website fixes, they are committed to
`main-site-pro`
+
+`main-site-pro-out`::
+It is populated automatically by the workflow triggered for changes on
`main-site-pro`.
+It contains the _contents_ (i.e., HTML files) of the {site-url}[the production
website].
+In a nutshell, CI builds `main-site-pro` and copies the generated
`target/site` to `main-site-pro-out`.
+
+Note that this branching scheme allows to host multiple websites in a
repository.
+For instance, the following branching scheme is used for the Log4j project:
+
+`2.x`:: Log4j 2 staging website sources
+`2.x-site-stg-out`:: Log4j 2 staging website contents
+`2.x-site-pro`:: Log4j 2 production website sources
+`2.x-site-pro-out`:: Log4j 2 production website contents
+`main`:: Log4j 3 staging website sources
+`main-site-stg-out`:: Log4j 3 staging website contents
+`main-site-pro`:: Log4j 3 production website sources
+`main-site-pro-out`:: Log4j 3 production website contents
