gemmellr commented on code in PR #4573:
URL: https://github.com/apache/activemq-artemis/pull/4573#discussion_r1281596556
##########
RELEASING.md:
##########
@@ -315,26 +315,15 @@ Once the mirrors are up-to-date then update the following:
with the HTML from the bottom of the release notes url you sent out with
your VOTE email (appending `&styleName=Text`).
2. Copy `src/_artemis_releases/artemis-<old-version>-release.md` to
`src/_artemis_releases/artemis-<new-version>-release.md`. Update the versions
and dates.
3. Update the _artemis_ list within the `src/_data/current_releases.yml` file
if needed.
-4. Copy `src/components/artemis/documentation/latest` to
`src/components/artemis/documentation/<old-version>`.
+4. Rename `src/components/artemis/documentation/latest` to
`src/components/artemis/documentation/<old-version>`.
5. Build the `artemis-website` module from the new-version release sources
with `mvn clean package -Prelease`.
-6. Create `src/components/artemis/documentation/latest` and copy these files
into it:
- 1. the contents of user-manual from
`apache-artemis-<new-version>/web/user-manual`
- 2. book.pdf version of user-manual (generated from the new-version sources
at `artemis-website/target/scratch/user-manual/` with the command `gitbook pdf`)
- 3. book.epub version of user-manual (generated from the new-version
sources at `artemis-website/target/scratch/user-manual/` with the command
`gitbook epub`)
- 4. book.mobi version of user-manual (generated from the new-version
sources at `artemis-website/target/scratch/user-manual/` with the command
`gitbook mobi`)
-7. Create `src/components/artemis/documentation/hacking-guide` and copy these
files into it:
- 1. the contents of hacking-guide from
`apache-artemis-<new-version>/web/hacking-guide`
- 2. book.pdf version of hacking-guide (generated with `gitbook pdf`)
-8. Copy `src/components/artemis/documentation/javadocs/javadoc-latest` to
`src/components/artemis/documentation/javadocs/javadoc-<old-version>`.
-9. Create `src/components/artemis/documentation/javadocs/javadoc-latest` and
copy the contents of `apache-artemis-<new-version>/web/api` into it.
+6. Create `src/components/artemis/documentation/latest` and copy into it the
contents of `target/user-manual` from the `artemis-website` module which you
just built.
+7. Rename `src/components/artemis/documentation/javadocs/javadoc-latest` to
`src/components/artemis/documentation/javadocs/javadoc-<old-version>`.
+8. Create `src/components/artemis/documentation/javadocs/javadoc-latest` and
copy into it the contents of `target/apidocs` from the `artemis-website` module
which you just built.
Review Comment:
We no longer do this quite the same way described, as we discussed keeping
only the latest Javadoc (instead of the proposals to remove it entirely, or
just link to an archive), but must have not updated the instructions to reflect
it. Needs tweaked accordingly (I'll suggest her rather than creating a conflict
you need to resolve), e.g:
```suggestion
7. Delete `src/components/artemis/documentation/javadocs/javadoc-latest` to
clear the old/existing content (in case any files are being moved/removed by
the new version).
8. Create `src/components/artemis/documentation/javadocs/javadoc-latest`
again and copy into it the contents of `target/apidocs` from the
`artemis-website` module which you just built.
```
##########
.gitignore:
##########
@@ -31,12 +31,9 @@
artemis-native/src/main/c/org_apache_activemq_artemis_jlibaio_LibaioContext.h
# generated by shade
**/dependency-reduced-pom.xml
-# gitbook output
-docs/user-manual/en/_book
-docs/hacking-guide/en/_book
-
# overlay outpit
**/overlays/**/*
-# result of gitbook pdf under docs
-docs/user-manual/en/book.pdf
+# generated by the `artemis-website` build
+/docs/user-manual/client-classpath-jakarta.adoc
+/docs/user-manual/client-classpath-jms.adoc
Review Comment:
We shouldn't really be generating stuff inside the source/non-target tree to
begin with, especially not into _other_ modules trees. It will also be left
behind and put in the source release archive unless explicitly excluded \[1\].
The existing stuff made a scratch copy of the docs in the artemis-website
target dir to work on, and do some filtering around placeholders for versions
etc. We could probably just continue to do that even if we dont need the
filtering anymore.
\[1\] On this exclusions point, there are some similar 'creating stuff
outside target' related exclusions for the old docs build stuff that can
presumably be removed along with it, e.g:
[here](https://github.com/apache/activemq-artemis/blob/2.30.0/artemis-distribution/src/main/assembly/source-assembly.xml#L55-L57)
and
[here](https://github.com/apache/activemq-artemis/blob/2.30.0/artemis-distribution/src/main/assembly/source-assembly.xml#L148-L149).
##########
artemis-website/pom.xml:
##########
@@ -29,24 +29,20 @@
<properties>
<activemq.basedir>${project.basedir}/..</activemq.basedir>
- <webapp-dir>${project.artifactId}-${project.version}</webapp-dir>
-
<src-dir-user-manual>${basedir}/../docs/user-manual/en</src-dir-user-manual>
-
<scratch-dir-user-manual>${basedir}/target/scratch/user-manual</scratch-dir-user-manual>
-
<webapp-outdir-user-manual>${basedir}/target/classes/user-manual</webapp-outdir-user-manual>
-
<webapp-outdir-hacking-guide>${basedir}/target/classes/hacking-guide</webapp-outdir-hacking-guide>
-
<webapp-outdir-migration-guide>${basedir}/target/classes/migration-guide</webapp-outdir-migration-guide>
-
- <frontend-maven-plugin-version>1.12.1</frontend-maven-plugin-version>
- <nodeVersion>v18.15.0</nodeVersion>
- <npmVersion>9.6.2</npmVersion>
+
<asciidoctor.maven.plugin.version>2.2.4</asciidoctor.maven.plugin.version>
+ <asciidoctorj.pdf.version>2.3.9</asciidoctorj.pdf.version>
Review Comment:
Lets stick these in the root pom this time, along with everything else
similar.
##########
artemis-website/pom.xml:
##########
@@ -29,24 +29,20 @@
<properties>
<activemq.basedir>${project.basedir}/..</activemq.basedir>
- <webapp-dir>${project.artifactId}-${project.version}</webapp-dir>
-
<src-dir-user-manual>${basedir}/../docs/user-manual/en</src-dir-user-manual>
-
<scratch-dir-user-manual>${basedir}/target/scratch/user-manual</scratch-dir-user-manual>
-
<webapp-outdir-user-manual>${basedir}/target/classes/user-manual</webapp-outdir-user-manual>
-
<webapp-outdir-hacking-guide>${basedir}/target/classes/hacking-guide</webapp-outdir-hacking-guide>
-
<webapp-outdir-migration-guide>${basedir}/target/classes/migration-guide</webapp-outdir-migration-guide>
-
- <frontend-maven-plugin-version>1.12.1</frontend-maven-plugin-version>
- <nodeVersion>v18.15.0</nodeVersion>
- <npmVersion>9.6.2</npmVersion>
+
<asciidoctor.maven.plugin.version>2.2.4</asciidoctor.maven.plugin.version>
+ <asciidoctorj.pdf.version>2.3.9</asciidoctorj.pdf.version>
<skipWebsiteDocGeneration>false</skipWebsiteDocGeneration>
<skipWebsiteJavadocGeneration>false</skipWebsiteJavadocGeneration>
+ <skipWebsitePdfGeneration>false</skipWebsitePdfGeneration>
Review Comment:
I'd be inclined to default this to the existing skipWebsiteDocGeneration
property. Otherwise, anyone who already knows and enables
skipWebsiteDocGeneration currently, will now find it still then goes and builds
the documentation PDF now.
##########
docs/user-manual/_diagrams/client-classpath-jms.adoc:
##########
@@ -1 +1 @@
-This file will be generated/replaced in compile time by artemis-website
\ No newline at end of file
+This file will be generated/replaced in compile time by artemis-website
Review Comment:
Ditto
##########
artemis-website/pom.xml:
##########
@@ -29,24 +29,20 @@
<properties>
<activemq.basedir>${project.basedir}/..</activemq.basedir>
- <webapp-dir>${project.artifactId}-${project.version}</webapp-dir>
-
<src-dir-user-manual>${basedir}/../docs/user-manual/en</src-dir-user-manual>
-
<scratch-dir-user-manual>${basedir}/target/scratch/user-manual</scratch-dir-user-manual>
-
<webapp-outdir-user-manual>${basedir}/target/classes/user-manual</webapp-outdir-user-manual>
-
<webapp-outdir-hacking-guide>${basedir}/target/classes/hacking-guide</webapp-outdir-hacking-guide>
-
<webapp-outdir-migration-guide>${basedir}/target/classes/migration-guide</webapp-outdir-migration-guide>
-
- <frontend-maven-plugin-version>1.12.1</frontend-maven-plugin-version>
- <nodeVersion>v18.15.0</nodeVersion>
- <npmVersion>9.6.2</npmVersion>
+
<asciidoctor.maven.plugin.version>2.2.4</asciidoctor.maven.plugin.version>
+ <asciidoctorj.pdf.version>2.3.9</asciidoctorj.pdf.version>
<skipWebsiteDocGeneration>false</skipWebsiteDocGeneration>
<skipWebsiteJavadocGeneration>false</skipWebsiteJavadocGeneration>
+ <skipWebsitePdfGeneration>false</skipWebsitePdfGeneration>
+
+ <!-- these only need to be generated occasionally, not every release -->
+
<skipWebsiteMigrationGuideGeneration>true</skipWebsiteMigrationGuideGeneration>
+
<skipWebsiteHackingGuideGeneration>true</skipWebsiteHackingGuideGeneration>
Review Comment:
Not enabling them means they wont be in the produced output as they are
currently however, which is kind of nice to have the whole 'website docs
collection' from the point in time of the release.
Unless they are _really_ slow to produce (which they weren't before) it
would seem simpler just to generate them as before rather than having to
specify options to get things to build. I'd then also default these to the
skipWebsiteDocGeneration so existing usage skips all the docs as before.
Anyone wanting to mix-and-match can the the various properties explicitly to
get what they want can do if needed. Given they should be relatively quick to
produce I dont see anyone needing to bother with that, except maybe disabling
PDF generation and keeping the rest.
EDIT: To the starting jar content comment....actually turns out the module
jar no longer contains _any_ of the HTML output as before, presumably as it
isnt generated into the classes dir as before or otherwise added to the jar. So
it just has some metadata stuff but is otherwise empty.
We should either restore the jar contents so it is in line with previously,
or just stop deploying it entirely.
##########
docs/user-manual/index.adoc:
##########
@@ -0,0 +1,136 @@
+:idprefix:
+:idseparator: -
+
Review Comment:
Should probably have a note comment in here, indicating people need to
update the separate *_book.adoc* file as well for the PDF, mirroring the
comment in that file.
##########
docs/user-manual/_diagrams/client-classpath-jakarta.adoc:
##########
@@ -1 +1 @@
-This file will be generated/replaced in compile time by artemis-website
\ No newline at end of file
+This file will be generated/replaced in compile time by artemis-website
Review Comment:
Is this meant to be in the diagrams dir now?
--
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]
