[camel] 02/02: Asynchronous release process and more details

[dj...@apache.org]

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

djencks pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git

commit 0adc0eb28f62a750aa897e4ed8b21954d6ea2b3c
Author: David Jencks <dj...@apache.org>
AuthorDate: Sat Nov 13 10:33:17 2021 -0800

    Asynchronous release process and more details
---
 .../modules/ROOT/pages/release-guide-website.adoc  | 71 ++++++++++++++++++----
 1 file changed, 60 insertions(+), 11 deletions(-)

diff --git a/docs/user-manual/modules/ROOT/pages/release-guide-website.adoc b/docs/user-manual/modules/ROOT/pages/release-guide-website.adoc
index 5e2f36b..47671ba 100644
--- a/docs/user-manual/modules/ROOT/pages/release-guide-website.adoc
+++ b/docs/user-manual/modules/ROOT/pages/release-guide-website.adoc
@@ -17,10 +17,10 @@ Since we are marking the main branch as prerelease, this will never be the main
 == After a new release branch is created
 
 This will always be a branch from `main`.
-Changes to both `main` and the new branch, say `camel-3.12.x`, will be needed.
+Changes to the new branch, say `camel-3.13.x`, will be needed.
 The changes are almost the same whether the new branch is LTS or not.
 
-=== Changes to the new branch (`3.12.x`)
+=== Changes to the new branch (`3.13.x`) in synchronized projects
 
 For each of the projects, `camel`, `camel-karaf`, `camel-spring-boot`, locate the section for the project in the `camel-website` `antora-playbook.yml` and adjust the version in the component descriptor for each start path.
 As of writing this consists of:
@@ -33,9 +33,9 @@ In `camel-spring-boot/core/antora.yml`::
 In `camel-spring-boot/docs/components/antora.yml`::
 In `camel-spring-boot/docs/spring-boot/antora.yml`::
 
-* Change `version` to the branch name e.g. `3.12.x`
+* Change `version` to the branch name e.g. `3.13.x`
 * Remove the `prerelease` flag line
-* If the new branch is LTS, set the display-version to e.g. `3.12.x (LTS)`.
+* If the new branch is LTS, set the display-version to e.g. `3.13.x (LTS)`.
 * If the new branch is not LTS, remove the `display-version` line.
 
 In `camel-karaf:tooling/camel-karaf-docs-maven-plugin/src/main/java/org/apache/camel/karaf/maven/ExtMvelHelper.java`::
@@ -48,13 +48,22 @@ private final static String CAMEL_VERSION = "next";`
 to e.g.
 +
 [source,java]
-private final static String CAMEL_VERSION = "3.12.x";
+private final static String CAMEL_VERSION = "3.13.x";
 
 At this point, build each project (`mvn clean install -Pfastinstall`) and check for generated changes that should be committed.
 
 NOTE: TODO: Is there a step of setting up CI or the regen bot?
 Should maven snapshots be deployed?
 
+=== Changes to other subprojects
+
+Be sure the subprojects using the latest release of main camel are aware that they need to update to the latest version, including documentation updates.
+Any reference to the main camel documentation should use a version set in the subproject antora.yml component descriptor(s).
+This may be set automatically from another source such as a maven `pom.xml`.
+
+Subproject changes are likely to involve code as well as documentation changes and need to be done by a subproject expert.
+This section only attempts to describe the documentation changes needed.
+
 In the `camel-quarkus` project examine the root `pom.xml` of every version used in the website.
 There will be a property entry like:
 
@@ -68,19 +77,59 @@ If changed, follow the instructions and run mvn validate in the docs directory.
 
 === Changes to the Antora playbook
 
+This must be done in three steps:
+
+. Add the new documentation version to the published website, leaving the previous version.
+. Wait for all subprojects such as camel-quarkus to update to using the new version, as appropriate.
+. Remove the old, previous, documentation version from the website, if appropriate.
+
 NOTE: After a release, consider whether any LTS versions are now out of service and should be removed from the documentation.
 
+==== Step 1
+
+Add the new branch to `camel-website:antora-playbook.yml` for the `content.sources` for `camel` 3 docs, `camel-karaf`, and `camel-spring-boot`.
+Add the new branch near the top of the list after the `main` branch to keep the branches listed in reverse chronological order.
+
+Test your work locally and with a PR... once it is approved and committed go on to step 2.
+
+==== Step 2
+
+Make sure all subproject participants are aware of the new release and wait for them to update the subprojects to use the new release as appropriate.
+
+==== Step 3
+
 There are two cases to consider in modifying `camel-website:antora-playbook.yml`.
 
 New LTS version::
 Release after a non-LTS release::
-* Change the branch of the last release to that of the new release in the sources sections for camel, camel-karaf, and camel-spring-boot.
-Branches should be listed in reverse release order, newest first, preceded by the `main` prerelease branch.
+* Remove the previous release branch from the sources sections for camel, camel-karaf, and camel-spring-boot.
 
 First release after an LTS release::
-* Add a new branch in the sources sections for camel, camel-karaf, and camel-spring-boot between `main` and the last LTS release branch.
+* Nothing to do.
+
+=== How to test your work
+
+This process should be followed for any documentation change and is especially important for new releases.
+
+. The documentation changes will be on one or more branches in your GitHub fork(s) of camel projects.
+Make sure that the modified branch(es), say `3.13.x-feature`, and all unmodified branches are up to date in your fork.
+There may be better ways, but one way is to, in your local clone, fetch from origin, pull into each unmodified branch, and push these to your fork.
+
+. In your clone of the camel-website project, modify the playbook to use your forks of the changed branches as urls and the changed branches.
+Since you've updated your fork on unchanged branches to match origin, the other branches should be up to date.
+
+. Build the site locally.
+.. (one time) You may need to compile platform specific Node dependencies if you are not on a Linux x86 system by running `yarn workspaces foreach install`.
+.. (one time) You may need to build the Antora ui by running `yarn build-all` or `cd antora-ui-camel && yarn build`
+.. After this running `yarn build:antora` or `yarn build` is sufficient.
+
+. Your playbook and other website changes are on a branch of the `camel-website` project.
+Push this branch to your `camel-website` fork and open a PR.
+Wait for the PR preview build on Netlify and check that the build succeeded and the results look as you expect.
+
+. After appropriate approvals merge your documentation source branch PRs.
 
-=== Test your work!
+. Update your Antora playbook by switching back to the `apache` urls and the merged branches.
+Push the result to your fork and wait for the PR preview build.
 
-Create branches for each changed branch, push them, use those branches in your playbook, commit the playbook in a branch and push it, and open a PR for the playbook to find out if you missed anything.
-Wait for the PR build and netlify preview and check that the build succeeded and the preview looks good.
+. Once this is satisfactory and you have the appropriate approvals merge your `camel-website` PR.