This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch main-site-stg-out
in repository https://gitbox.apache.org/repos/asf/logging-parent.git
The following commit(s) were added to refs/heads/main-site-stg-out by this push:
new e581a5b Add website content generated from
`20e23163e8047e1e460c0b9c1a858c52dc3b60fe`
e581a5b is described below
commit e581a5bd70a08e16f1fa7a014e4c9825ec05582d
Author: ASF Logging Services RM <[email protected]>
AuthorDate: Fri Apr 12 07:45:52 2024 +0000
Add website content generated from
`20e23163e8047e1e460c0b9c1a858c52dc3b60fe`
---
release-instructions-project.html | 70 ++++++++++++++------
sitemap.xml | 12 ++--
usage.html | 136 ++++++++++++++++++++++++++++++++++++++
3 files changed, 190 insertions(+), 28 deletions(-)
diff --git a/release-instructions-project.html
b/release-instructions-project.html
index 67514f8..54f5959 100644
--- a/release-instructions-project.html
+++ b/release-instructions-project.html
@@ -152,7 +152,12 @@ For instance, <code>site-project.version</code> needs to
be updated for <code>lo
</div>
</li>
<li>
-<p>Release the changelog: <code>./mvnw -N changelog-release</code></p>
+<p>Release the changelog:</p>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-bash hljs"
data-lang="bash">./mvnw -N changelog-release</code></pre>
+</div>
+</div>
</li>
<li>
<p>Edit the release notes (i.e.,
<code>src/changelog/7.8.0/.release-notes.adoc.ftl</code>)</p>
@@ -198,7 +203,7 @@ You can iterate on the <code>release/7.8.0</code> branch to
perfect it.</p>
<p><strong>Signed distribution and its checksum</strong> (e.g.,
<code>apache-logging-parent-7.8.0-{bin,src}.{zip,.zip.asc,.zip.sha512}</code>)
are uploaded to <a
href="https://dist.apache.org/repos/dist/dev/logging/logging-parent";>dist.apache.org/repos/dist/<strong>dev</strong>/logging/logging-parent/7.8.0</a>
Subversion repository (along with auxiliary files; website, email texts,
etc.)</p>
</li>
<li>
-<p><a href="https://logging.staged.apache.org/logging-parent";>The project
<strong>staging</strong> website</a> is deployed</p>
+<p><a href="https://logging.staged.apache.org/logging-parent-7.8.0";>The
release staging website</a> is deployed using the freshly populated
<code>release/7.8.0-site-stg-out</code> branch</p>
</li>
</ol>
</div>
@@ -336,6 +341,14 @@ git push --delete origin release/7.8.0</code></pre>
</div>
</div>
</li>
+<li>
+<p>Delete the release staging website branch:</p>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-bash hljs"
data-lang="bash">git push --delete origin
release/7.8.0-site-stg-out</code></pre>
+</div>
+</div>
+</li>
</ol>
</div>
</div>
@@ -403,45 +416,55 @@ svn commit -m 'Remove `logging-parent` version `7.8.0`
files released'</code></p
</div>
<div class="sect2">
<h3 id="publish-release-github"><a class="anchor"
href="#publish-release-github"></a>In GitHub</h3>
-<div class="olist arabic">
-<ol class="arabic">
-<li>
-<p>Run the <a
href="https://github.com/apache/logging-parent/actions/workflows/deploy-site-pro.yaml";><code>deploy-site-pro</code></a>
GitHub Actions workflow:</p>
-<div class="olist loweralpha">
-<ol class="loweralpha" type="a">
+<div class="paragraph">
+<p><a href="https://github.com/apache/logging-parent/releases/new";>Create a
new release in GitHub</a>:</p>
+</div>
+<div class="ulist">
+<ul>
<li>
<p>Use the <code>rel/7.8.0</code> tag</p>
</li>
<li>
-<p>Verify that <a href="https://logging.apache.org/logging-parent";>the project
website</a> is updated</p>
+<p>Copy release notes from the generated emails</p>
</li>
-</ol>
+</ul>
</div>
-</li>
-<li>
-<p><a href="https://github.com/apache/logging-parent/releases/new";>Create a
new release in GitHub</a></p>
-<div class="olist loweralpha">
-<ol class="loweralpha" type="a">
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="publish-release-website"><a class="anchor"
href="#publish-release-website"></a>Publish the release website</h2>
+<div class="sectionbody">
+<div class="olist arabic">
+<ol class="arabic">
<li>
-<p>Use the <code>rel/7.8.0</code> tag</p>
+<p>Merge the <code>rel/7.8.0</code> tag (<strong>not</strong> the
<code>release/7.8.0</code> branch!) to <code>main-site-pro</code> and push
it</p>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-bash hljs"
data-lang="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</code></pre>
+</div>
+</div>
</li>
<li>
-<p>Copy release notes from the generated emails</p>
+<p>Verify that <a
href="https://github.com/apache/logging-parent/actions/workflows/deploy-site.yaml";>the
<code>deploy-site</code> workflow</a> successfully runs the
<code>deploy-site-pro</code> job</p>
</li>
-</ol>
-</div>
+<li>
+<p>Verify that <a href="https://logging.apache.org/logging-parent";>the project
website</a> is updated</p>
</li>
</ol>
</div>
</div>
</div>
-</div>
<div class="sect1">
<h2 id="announce-release"><a class="anchor"
href="#announce-release"></a>Announce the release</h2>
<div class="sectionbody">
-<div class="paragraph">
+<div class="olist arabic">
+<ol class="arabic">
+<li>
<p>Send the announcement email uploaded to the <a
href="https://dist.apache.org/repos/dist/dev/logging/logging-parent";>dist.apache.org/repos/dist/<strong>dev</strong>/logging/logging-parent/7.8.0</a>
Subversion repository</p>
-</div>
<div class="admonitionblock warning">
<table>
<tr>
@@ -457,6 +480,9 @@ If you are using GMail, enable the <em>"Plain text
mode"</em> while composing yo
</tr>
</table>
</div>
+</li>
+</ol>
+</div>
</div>
</div>
</article>
diff --git a/sitemap.xml b/sitemap.xml
index a87b26b..bb4a6e5 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,26 +2,26 @@
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9";>
<url>
<loc>https://logging.apache.org/logging-parent/features.html</loc>
-<lastmod>2024-04-11T13:18:35.635Z</lastmod>
+<lastmod>2024-04-12T07:45:51.134Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/logging-parent/index.html</loc>
-<lastmod>2024-04-11T13:18:35.635Z</lastmod>
+<lastmod>2024-04-12T07:45:51.134Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/logging-parent/release-instructions-project.html</loc>
-<lastmod>2024-04-11T13:18:35.635Z</lastmod>
+<lastmod>2024-04-12T07:45:51.134Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/logging-parent/release-instructions-xml-schema.html</loc>
-<lastmod>2024-04-11T13:18:35.635Z</lastmod>
+<lastmod>2024-04-12T07:45:51.134Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/logging-parent/release-notes.html</loc>
-<lastmod>2024-04-11T13:18:35.635Z</lastmod>
+<lastmod>2024-04-12T07:45:51.134Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/logging-parent/usage.html</loc>
-<lastmod>2024-04-11T13:18:35.635Z</lastmod>
+<lastmod>2024-04-12T07:45:51.134Z</lastmod>
</url>
</urlset>
diff --git a/usage.html b/usage.html
index 6c1bb0a..68d3690 100644
--- a/usage.html
+++ b/usage.html
@@ -92,6 +92,8 @@
</aside>
<article class="doc">
<h1 class="page">Usage</h1>
+<div id="preamble">
+<div class="sectionbody">
<div class="paragraph">
<p>You can use Logging Parent as follows:</p>
</div>
@@ -162,6 +164,140 @@
</li>
</ol>
</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_website_deployment"><a class="anchor"
href="#_website_deployment"></a>Website deployment</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Using <code>deploy-site-reusable.yaml</code> reusable GitHub Actions
workflow, you can automate the website deployments for staging and production
environments.
+See how <a
href="https://github.com/apache/logging-parent/blob/main/.github/workflows/deploy.yaml";><code>deploy.yaml</code></a>
and <a
href="https://github.com/apache/logging-parent/blob/main/.github/workflows/deploy-site.yaml";><code>deploy-site.yaml</code></a>
of Logging Parent achieves that using the following repository branching
scheme:</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1">Staging website</dt>
+<dd>
+<p><a href="https://logging.staged.apache.org/logging-parent";
class="bare">https://logging.staged.apache.org/logging-parent</a></p>
+</dd>
+<dt class="hdlist1">Production website</dt>
+<dd>
+<p><a href="https://logging.apache.org/logging-parent";
class="bare">https://logging.apache.org/logging-parent</a></p>
+</dd>
+<dt class="hdlist1">Release staging website</dt>
+<dd>
+<p><a href="https://logging.staged.apache.org/logging-parent-<version>";
class="bare">https://logging.staged.apache.org/logging-parent-<version></a></p>
+</dd>
+<dt class="hdlist1">Branch <code>main</code></dt>
+<dd>
+<p>Contains the <em>sources</em> (i.e., AsciiDoc files) to build <em>the
staging website</em>.</p>
+</dd>
+<dt class="hdlist1">Branch <code>main-site-stg-out</code></dt>
+<dd>
+<p>Populated automatically by the workflow triggered for changes on
<code>main</code>.
+It contains the <em>contents</em> (i.e., HTML files) of the <em>the staging
website</em>.
+In short, CI builds <code>main</code> and copies the generated
<code>target/site</code> to <code>main-site-stg-out</code>.</p>
+</dd>
+<dt class="hdlist1">Branch <code>main-site-pro</code></dt>
+<dd>
+<p>Contains the <em>sources</em> (i.e., AsciiDoc files) to build the <em>the
production website</em>.
+It is <em>manually populated</em> by maintainers. For instance,</p>
+<div class="ulist">
+<ul>
+<li>
+<p>after a release, the release tag is merged to <code>main-site-pro</code></p>
+</li>
+<li>
+<p>when there are minor website fixes in <code>main</code> that can also go to
the production website, they are <code>cherry-pick</code>ed onto the
<code>main-site-pro</code></p>
+</li>
+<li>
+<p>when there are production-only website fixes, they are committed to
<code>main-site-pro</code></p>
+</li>
+</ul>
+</div>
+</dd>
+<dt class="hdlist1">Branch <code>main-site-pro-out</code></dt>
+<dd>
+<p>Populated automatically by the workflow triggered for changes on
<code>main-site-pro</code>.
+It contains the <em>contents</em> (i.e., HTML files) of <em>the production
website</em>.
+In short, CI builds <code>main-site-pro</code> and copies the generated
<code>target/site</code> to <code>main-site-pro-out</code>.</p>
+</dd>
+<dt class="hdlist1">Branch <code>release/<version></code></dt>
+<dd>
+<p>Contains the <em>sources</em> (i.e., AsciiDoc files) to build <em>the
release staging website</em>.
+It is <em>manually populated</em> by the release manager during a release.</p>
+</dd>
+<dt class="hdlist1">Branch
<code>release/<version>-site-stg-out</code></dt>
+<dd>
+<p>Populated automatically by the workflow triggered for changes on
<code>release/<version></code>.
+It contains the <em>contents</em> (i.e., HTML files) of <em>the release
staging website</em>.
+In short, CI builds <code>release/<version></code> and copies the
generated <code>target/site</code> to
<code>release/<version>-site-stg-out</code>.</p>
+</dd>
+</dl>
+</div>
+<div class="paragraph">
+<p>Note that this branching scheme allows to</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>host multiple websites in a single repository</p>
+</li>
+<li>
+<p>deploy staging websites of multiple releases in parallel</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>For instance, the following branching scheme is used for the Log4j
project:</p>
+</div>
+<table class="tableblock frame-all grid-all stretch">
+<caption class="title">Table 1. Log4j branching scheme for website
deployments</caption>
+<colgroup>
+<col style="width: 46.6666%;">
+<col style="width: 26.6666%;">
+<col style="width: 26.6668%;">
+</colgroup>
+<tbody>
+<tr>
+<th class="tableblock halign-center valign-middle" rowspan="2"><p
class="tableblock">Description</p></th>
+<th class="tableblock halign-center valign-top" colspan="2"><p
class="tableblock">Branch name</p></th>
+</tr>
+<tr>
+<th class="tableblock halign-center valign-top"><p class="tableblock">Log4j
2</p></th>
+<th class="tableblock halign-center valign-top"><p class="tableblock">Log4j
3</p></th>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Staging
website sources</p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>2.x</code></p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>main</code></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Staging
website contents</p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>2.x-site-stg-out</code></p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>main-site-stg-out</code></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Production
website sources</p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>2.x-site-pro</code></p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>main-site-pro</code></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Production
website contents</p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>2.x-site-pro-out</code></p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>main-site-pro-out</code></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Release
staging website sources</p></td>
+<td class="tableblock halign-left valign-top" colspan="2"><p
class="tableblock"><code>release/<version></code></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Release
staging website contents</p></td>
+<td class="tableblock halign-left valign-top" colspan="2"><p
class="tableblock"><code>release/<version>-site-stg-out</code></p></td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
</article>
</div>
</main>
