You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by dj...@apache.org on 2021/11/16 00:17:24 UTC
[camel] branch main updated (fbb485b -> 0adc0eb)
This is an automated email from the ASF dual-hosted git repository.
djencks pushed a change to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git.
from fbb485b camel-elasticsearch - Polished
new 9c0eaf6 update guide to updating website on releases
new 0adc0eb Asynchronous release process and more details
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.../modules/ROOT/pages/release-guide-website.adoc | 103 +++++++++++++++++----
1 file changed, 84 insertions(+), 19 deletions(-)
[camel] 02/02: Asynchronous release process and more details
Posted by 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.
[camel] 01/02: update guide to updating website on releases
Posted by 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 9c0eaf6167e400001882351806c9105e6fce22cd
Author: David Jencks <dj...@apache.org>
AuthorDate: Fri Nov 12 20:01:56 2021 -0800
update guide to updating website on releases
---
.../modules/ROOT/pages/release-guide-website.adoc | 42 +++++++++++++++-------
1 file changed, 29 insertions(+), 13 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 f8127b3..5e2f36b 100644
--- a/docs/user-manual/modules/ROOT/pages/release-guide-website.adoc
+++ b/docs/user-manual/modules/ROOT/pages/release-guide-website.adoc
@@ -8,11 +8,11 @@ For instance, `camel:docs/components/antora.yml` for the `docs/components/antora
== Notes on versions
Within an Antora component, xrefs to content in the same component, whether or not they are in the same source tree or repository, should never include the `version` or `component` segment of the page id.
-Including the version will make the page non-relocatable to another version: for instance specifying `latest` in the main branch will break the link when main is branched for a release.
+Including the version will make the page non-relocatable to another version: for instance specifying `next` in the main branch will break the link when main is branched for a release.
Including the `component` segment will redirect to the (Antora) latest version, which will typically be the last released version.
Antora calculates the latest version as the last non-prerelease version.
-Since we are marking the main branch as prerelease, this will never be the main branch, although the version is currently 'latest'.
+Since we are marking the main branch as prerelease, this will never be the main branch.
== After a new release branch is created
@@ -20,30 +20,30 @@ This will always be a branch from `main`.
Changes to both `main` and the new branch, say `camel-3.12.x`, will be needed.
The changes are almost the same whether the new branch is LTS or not.
-=== Changes to `main` branch
-
-In `camel:docs/components/antora.yml`::
-In `camel-karaf:docs/antora.yml`::
-In `camel-spring-boot:docs/antora.yml`::
-Increment the display-version, e.g. `3.12.x (Prerelease)` to `3.13.x (Prerelease)`
-
=== Changes to the new branch (`3.12.x`)
+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:
+
In `camel:docs/components/antora.yml`::
+In `camel:core/camel-core-engine/src/main/docs/antora.yml`::
In `camel-karaf:docs/antora.yml`::
-In `camel-spring-boot:docs/antora.yml`::
+In `camel-spring-boot/components-starter/antora.yml`::
+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`
* 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 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`::
-In `camel-spring-boot:tooling/camel-spring-boot-docs-maven-plugin/src/main/java/org/apache/camel/springboot/maven/ExtMvelHelper.java`::
change
+
[source,java]
-private final static String CAMEL_VERSION = "latest";`
+private final static String CAMEL_VERSION = "next";`
+
to e.g.
+
@@ -55,6 +55,17 @@ At this point, build each project (`mvn clean install -Pfastinstall`) and check
NOTE: TODO: Is there a step of setting up CI or the regen bot?
Should maven snapshots be deployed?
+In the `camel-quarkus` project examine the root `pom.xml` of every version used in the website.
+There will be a property entry like:
+
+[source,xml]
+ <!-- Primary dependencies - maintained manually -->
+ <camel.major.minor>3.13</camel.major.minor> <!-- run after each change: cd docs && mvnd validate -->
+
+If the camel version is removed from documentation by this release, update it to the new version.
+If the camel version is LTS consider whether it is appropriate to update it to the new version.
+If changed, follow the instructions and run mvn validate in the docs directory.
+
=== Changes to the Antora playbook
NOTE: After a release, consider whether any LTS versions are now out of service and should be removed from the documentation.
@@ -67,4 +78,9 @@ Release after a non-LTS release::
Branches should be listed in reverse release order, newest first, preceded by the `main` prerelease branch.
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.
\ No newline at end of file
+* Add a new branch in the sources sections for camel, camel-karaf, and camel-spring-boot between `main` and the last LTS release branch.
+
+=== Test your work!
+
+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.