You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by da...@apache.org on 2023/03/13 12:09:12 UTC
[causeway] branch master updated: CAUSEWAY-3255: addresses a documentation todo
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/causeway.git
The following commit(s) were added to refs/heads/master by this push:
new 753bd3b91a CAUSEWAY-3255: addresses a documentation todo
753bd3b91a is described below
commit 753bd3b91ad8ab9dd7826838e1955ca18f12b7a6
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Mon Mar 13 07:03:05 2023 +0000
CAUSEWAY-3255: addresses a documentation todo
---
.../comguide/modules/ROOT/pages/about.adoc | 25 ---
.../ROOT/pages/antora-publish-procedure.adoc | 170 ---------------------
.../publishing/log/ObjectRenderedLogger.java | 0
.../publishing/spi/ObjectRenderSubscriber.java | 63 ++++++++
4 files changed, 63 insertions(+), 195 deletions(-)
diff --git a/antora/components/comguide/modules/ROOT/pages/about.adoc b/antora/components/comguide/modules/ROOT/pages/about.adoc
index fa1a80e0b5..bc9152ed9c 100644
--- a/antora/components/comguide/modules/ROOT/pages/about.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/about.adoc
@@ -6,28 +6,3 @@
This committers' guide is for committers of Apache Causeway itself who want guidance on release process, publishing documents and other related procedures.
-//include::applying-patches.adoc[leveloffset=+1]
-//
-//include::merging-a-pull-request.adoc[leveloffset=+1]
-//
-//include::cutting-a-release.adoc[leveloffset=+1]
-//
-//include::verifying-releases.adoc[leveloffset=+1]
-//
-//include::post-release-successful.adoc[leveloffset=+1]
-//
-//include::post-release-unsuccessful.adoc[leveloffset=+1]
-//
-//include::antora-publish-procedure.adoc[leveloffset=+1]
-//
-//include::key-generation.adoc[leveloffset=+1]
-//
-//include::release-process-prereqs.adoc[leveloffset=+1]
-//
-//include::policies.adoc[leveloffset=+1]
-//include::policies/versioning-policy.adoc[leveloffset=+2]
-//include::policies/git-policy.adoc[leveloffset=+2]
-//
-//include::pmc-notes.adoc[leveloffset=+1]
-
-//include::starter-apps.adoc[leveloffset=+1]
diff --git a/antora/components/comguide/modules/ROOT/pages/antora-publish-procedure.adoc b/antora/components/comguide/modules/ROOT/pages/antora-publish-procedure.adoc
deleted file mode 100644
index e5810444da..0000000000
--- a/antora/components/comguide/modules/ROOT/pages/antora-publish-procedure.adoc
+++ /dev/null
@@ -1,170 +0,0 @@
-[[antora-publish-procedure]]
-= Publishing the Docs
-
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-:page-partial:
-
-
-WARNING: TODO: v2 - not yet updated.
-There is relevant material in xref:post-release-successful.adoc[Post Release (Successful)], specifically:
- xref:post-release-successful.adoc#generate-website[Generate website] and
- xref:post-release-successful.adoc#publish-website[Publish website].
-
-
-
-Apache Causeway' documentation (meaning the website and the users' guide, the reference guide and this contributors' guide) is written using link:https://asciidoctor.org/[Asciidoctor] syntax, and organized to be published as an link:https://antora.org[Antora] website.
-
-The website and guides are created by running build tools (documented below) which create the HTML version of the site and guides.
-You can therefore easily check the documentation before raising a pull request (as a contributor) or publishing the site (if a committer).
-
-For details of authoring/updating the documents and website, see the xref:conguide:documentation:about.adoc[Contributors' Guide].
-
-Publishing is performed by copying the generated HTML to a different git repository (link:https://github.com/apache/causeway-site.git[causeway-site]).
-This is synced by ASF infrastructure over to link:https://causeway.apache.org[causeway.apache.org].
-This can only be done by Apache Causeway committers, and is discussed below.
-
-== One-time setup
-
-The generated site is published by copying into the `content/` directory of the https://github.com/apache/causeway-site.git[causeway-site] git repo.
-You therefore need to check this out this repo.
-
-The procedure assumes that two git repos (for https://github.com/apache/causeway[causeway] itself on github, and for causeway-site) are checked out into the same parent directory, eg:
-
-[source]
-----
-/GITHUB/
- apache/
- causeway/ # <1>
- adocs
- documentation/
- README.adoc
- ...
- causeway-site/ # <2>
- content/ # <3>
-----
-<1> checkout of causeway.git
-<2> checkout of causeway-site.git
-<3> the published website
-
-One oddity; ASF's script to upload the documentation to the web server checks out from the 'asf-site' branch, NOT from the 'master' branch.
-Therefore, in the `causeway.git` repo site:
-
-[source,bash]
-----
-git checkout asf-site
-----
-
-== Preview
-
-
-To preview changes (ignoring PDFs), run:
-
-[source,bash]
-----
-sh preview-html.sh
-----
-
-This will update the documentation and start a (Python) webserver so that the documents can be viewed.
-
-If you want to also view the PDFs, use:
-
-[source,bash]
-----
-sh preview-pdf.sh
-----
-
-There's generally little point in doing this, however.
-
-== Publishing (full build)
-
-WARNING: TODO: v2 - not yet updated.
-Need to figure out how to merge the v1 docs (as an archive) with Antora.
-Also, need to use Antora versioning rather than just 'master'
-
-The `content` directory for the published website contains not only the "current version" of the docs, but also has an archive of older versions of the document from earlier releases:
-
-[source]
-----
-/GITHUB/
- apache/
- causeway-site/
- content/ # <1>
- index.html # <2>
- * # <3>
- versions/
- current/ # <4>
- SNAPSHOT/ # <5>
- ... # <6>
- latest/ # <7>
-----
-<1> the published website
-<2> home page.
-This has a drop-down to access older versions of the documentation, but most links are through to the "current version"
-<3> documentation for the current release version
-<4> also holds documentation for the current release version
-<5> documentation for the next snapshot version, ie work-in-progress
-<6> other versions, by version number (eg `1.16.2`, `1.16.1`, etc)
-<7> not checked into git, this is a working directory that contains the results of the latest publication build.
-This is an implementation detail actually, so this directory need not be considered further.
-
-The earlier versions of the documentation are (obviously) not recreated when the documentation is published, only the current version is updated.
-
-To publish the current version of the documents, switch to the `adocs/documentation` directory of the main `causeway-git.repo`.
-Then run:
-
-[source,bash]
-----
-sh publish.sh "CAUSEWAY-nnnn: a custom commit message"
-----
-
-This does the following:
-
-* deletes everything under `content` (except `content/versions`)
-* generates documentation and copies to `content/versions/SNAPSHOT`
-+
-Including fixing up line endings, standardizing on unix-style LFs.
-* copies over current home page (`index.html`)
-* reinstates `content/*` with the contents of `content/versions/current`
-
-In other words, the effect of running `publish.sh` is in essence to overwrite `content/versions/SNAPSHOT` and to overwrite `index.html`, but leave everything else as it is.
-
-[NOTE]
-====
-The version on the header of each generated document is hard-coded in the `adocs/template/document.html.erb` file.
-
-This should therefore be updated whenever working on a new release.
-====
-
-=== New release
-
-WARNING: TODO: v2 - not yet updated.
-Need to figure out how to merge the v1 docs (as an archive) with Antora.
-Also, need to use Antora versioning rather than just 'master'
-
-When a new release is published, we therefore need to do a little extra work:
-
-* run `publish.sh` a first time
-+
-This will update `content/versions/SNAPSHOT`
-* delete `content/versions/current`
-* rename `content/versions/SNAPSHOT` to `content/versions/current`
-* run `publish.sh` a second time.
-+
-This has the effect of "promoting" `content/versions/current` to `content/*`
-
-* (optionally) also copy `content/versions/current` to `content/versions/N.N.N`
-+
-where `N.N.N` is the release number
-
-Ensure in doing this that the dropdown for the home page correctly references the versions.
-
-When ready, then stage, commit and push the changes (in the `causeway-site.git` directory, of course):
-
-[source,bash]
-----
-git commit -am "CAUSEWAY-nnnn: updating docs"
-git push
-----
-
-
-
diff --git a/api/applib/src/main/java/org/apache/causeway/applib/services/publishing/log/ObjectRenderedLogger.java b/api/applib/src/main/java/org/apache/causeway/applib/services/publishing/log/ObjectRenderedLogger.java
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/api/applib/src/main/java/org/apache/causeway/applib/services/publishing/spi/ObjectRenderSubscriber.java b/api/applib/src/main/java/org/apache/causeway/applib/services/publishing/spi/ObjectRenderSubscriber.java
new file mode 100644
index 0000000000..f4ca48fd65
--- /dev/null
+++ b/api/applib/src/main/java/org/apache/causeway/applib/services/publishing/spi/ObjectRenderSubscriber.java
@@ -0,0 +1,63 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.causeway.applib.services.publishing.spi;
+
+import org.apache.causeway.applib.services.command.Command;
+import org.apache.causeway.commons.having.HasEnabling;
+
+/**
+ * Part of the <i>Publishing SPI</i>. A component to receive {@link Command}s
+ * (with publishing enabled) that just completed.
+ *
+ * @since 2.0 {@index}
+ */
+public interface CommandSubscriber extends HasEnabling {
+
+ /**
+ * Notifies that the command will be published, and has transitioned to {@link org.apache.causeway.applib.services.command.Command.CommandPublishingPhase#READY}.
+ *
+ * <p>
+ * This is an opportunity for implementations to process the command,
+ * for example to persist an initial representation of it.
+ * </p>
+ */
+ void onReady(Command command);
+
+ /**
+ * Notifies that the command has started to execute, and has transitioned to {@link org.apache.causeway.applib.services.command.Command.CommandPublishingPhase#STARTED}.
+ *
+ * <p>
+ * This is an opportunity for implementations to process the command,
+ * for example to update any persisted representation of it.
+ * </p>
+ */
+ void onStarted(Command command);
+
+
+ /**
+ * Notifies that the command has completed and has transitioned to {@link org.apache.causeway.applib.services.command.Command.CommandPublishingPhase#COMPLETED}
+ *
+ * <p>
+ * This is an opportunity for implementations to process the command,
+ * for example to update any persisted representations of it.
+ * </p>
+ */
+ void onCompleted(Command command);
+
+}