You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@plc4x.apache.org by cd...@apache.org on 2020/12/14 09:24:33 UTC
[plc4x] branch develop updated: - Updated the release documentation
for the build tools to auto-update itself
This is an automated email from the ASF dual-hosted git repository.
cdutz pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/plc4x.git
The following commit(s) were added to refs/heads/develop by this push:
new 15925f6 - Updated the release documentation for the build tools to auto-update itself
15925f6 is described below
commit 15925f65d0eebcddd52a489157acb4fe8a0a8fbf
Author: cdutz <ch...@c-ware.de>
AuthorDate: Mon Dec 14 10:24:25 2020 +0100
- Updated the release documentation for the build tools to auto-update itself
---
src/main/script/preSiteGeneration.groovy | 29 +++-
.../asciidoc/developers/release/build-tools.adoc | 150 ++++++---------------
2 files changed, 68 insertions(+), 111 deletions(-)
diff --git a/src/main/script/preSiteGeneration.groovy b/src/main/script/preSiteGeneration.groovy
index d40da48..a2ee3ff 100644
--- a/src/main/script/preSiteGeneration.groovy
+++ b/src/main/script/preSiteGeneration.groovy
@@ -25,7 +25,7 @@ def currentYear = Calendar.getInstance().get(Calendar.YEAR) as String
print "\nCurrent year: " + currentYear
project.properties['current-year'] = currentYear
-// Calculate some version related stuff
+// Calculate some version related stuff for the main project
def currentVersion = project.version as String
def match = (currentVersion =~ /(\d+)\.(\d+)\.(\d+)(-SNAPSHOT)?/)
print "\nCurrent version: " + currentVersion
@@ -49,6 +49,33 @@ if (match.count >= 1) {
project.properties['current-next-minor-version'] = currentNextMinorVersion
}
+// Get the version of the code-generation
+codeGenerationVersion = project.properties['plc4x-code-generation.version']
+def codeGenMatch = (codeGenerationVersion =~ /(\d+)\.(\d+)\.(\d+)(-SNAPSHOT)?/)
+if (codeGenMatch.count >= 1) {
+ def codeGenMajorVersion = codeGenMatch[0][1] as Integer
+ def codeGenMinorVersion = codeGenMatch[0][2] as Integer
+ def codeGenBugfixVersion = codeGenMatch[0][3] as Integer
+ // If this is not a snapshot version, increment the minor version
+ if(codeGenMatch[0][4] == null) {
+ codeGenMinorVersion++
+ }
+
+ def codeGenerationReleaseFullVersion = codeGenMajorVersion + "." + codeGenMinorVersion + "." + codeGenBugfixVersion
+ def codeGenerationReleaseShortVersion = codeGenMajorVersion + "." + codeGenMinorVersion
+ def codeGenerationNextDevelopmentVersion = codeGenMajorVersion + "." + (codeGenMinorVersion + 1) + ".0"
+ def codeGenerationBugfixShortVersion = codeGenMajorVersion + "." + codeGenMinorVersion + "." + (codeGenBugfixVersion + 1)
+
+ print "\nNext code-generation full version: " + codeGenerationReleaseFullVersion + " (code-generation-full-version)"
+ project.properties['code-generation-full-version'] = codeGenerationReleaseFullVersion
+ print "\nNext code-generation short version: " + codeGenerationReleaseShortVersion + " (code-generation-short-version)"
+ project.properties['code-generation-short-version'] = codeGenerationReleaseShortVersion
+ print "\nNext code-generation development version: " + codeGenerationNextDevelopmentVersion + " (code-generation-development-version)"
+ project.properties['code-generation-development-version'] = codeGenerationNextDevelopmentVersion
+ print "\nNext code-generation bugfix version: " + codeGenerationBugfixShortVersion + " (code-generation-bugfix-version)"
+ project.properties['code-generation-bugfix-version'] = codeGenerationBugfixShortVersion
+}
+
// Get the latest released version from our doap file.
def plc4xDoapFile = new File(project.getBasedir(), "src/site/resources-filtered/plc4x-doap.rdf")
if (plc4xDoapFile.exists()) {
diff --git a/src/site/asciidoc/developers/release/build-tools.adoc b/src/site/asciidoc/developers/release/build-tools.adoc
index 91d6b83..269e961 100644
--- a/src/site/asciidoc/developers/release/build-tools.adoc
+++ b/src/site/asciidoc/developers/release/build-tools.adoc
@@ -14,7 +14,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.
//
-:imagesdir: ../images/
+:imagesdir: ../../images/
:icons: font
== Releasing PLC4X Build-Tools
@@ -36,7 +36,7 @@ According to SemVer, we have: Major, Minor and Bugfix releases.
For each new Major and Minor release we create a new branch at the beginning of a code-freeze phase.
-So if currently the project version in develop is `{current-full-version}-SNAPSHOT`, we create a branch `release/{current-short-version}`.
+So if currently the project version in develop is `{code-generation-full-version}-SNAPSHOT`, we create a branch `release/{code-generation-short-version}`.
When creating the branch is exactly the moment in which the version in `develop` is incremented to the next minor version.
@@ -48,25 +48,25 @@ This is the version the `develop` branch will be changed to.
mvn release:branch -DbranchName=releases/code-generation/{minor-version}
Per default the plugin suggests the next bugfix version as working version, however we want it to use the next minor version.
-So in case of preparing the release branch for `{project.version}` the command would be the following:
+So in case of preparing the release branch for `{code-generation-full-version}` the command would be the following:
[subs="verbatim,attributes"]
----
- mvn release:branch -DbranchName=releases/code-generation/{current-short-version}
+ mvn release:branch -DbranchName=releases/code-generation/{code-generation-short-version}
----
The plugin will then aks for the version:
[subs="verbatim,attributes"]
----
- What is the new working copy version for "PLC4X Build Tools: Code Generation"? (org.apache.plc4x.plugins:plc4x-code-generaton) {current-next-incremental-version}-SNAPSHOT: : {current-next-minor-version}-SNAPSHOT
+ What is the new working copy version for "PLC4X Build Tools: Code Generation"? (org.apache.plc4x.plugins:plc4x-code-generaton) {code-generation-bugfix-version}-SNAPSHOT: : {code-generation-development-version}-SNAPSHOT
----
Where the suggested default is manually overridden.
This step now should perform quite quickly as no build and no tests are involved.
-However in the end the versions of the `develop` branch are updated and a new `releases/code-generation/{current-short-version}` branch is created.
+However in the end the versions of the `develop` branch are updated and a new `releases/code-generation/{code-generation-short-version}` branch is created.
=== Preparing `develop` for the next iteration
@@ -77,7 +77,7 @@ Here comes a template:
[subs="verbatim,attributes"]
----
==============================================================
-(Unreleased) Apache PLC4X {current-next-minor-version}-SNAPSHOT
+(Unreleased) Apache PLC4X {code-generation-development-version}-SNAPSHOT
==============================================================
New Features
@@ -93,6 +93,8 @@ Bug Fixes
----
+After that please remove the `(Unreleased)` from the following section, as we are currently working on its release.
+
Also be sure to do a quick full-text-search to check if the version was updated correctly everywhere.
WARNING: If you find anything here, you will need to pay attention during the release.
@@ -103,7 +105,7 @@ Now usually comes a phase in which last tests and checks should be performed.
If any problems are found they, have to be fixed in the release branch.
-Changes should either be re applied in `develop` or `cherry-picked`, however merging things back can cause a lot of problems and we no longer have the same versions.
+Changes should either be re applied in `develop` or `cherry-picked`, however merging things back can cause a lot of problems, and we no longer have the same versions.
=== Preparing a release
@@ -117,7 +119,7 @@ As especially when switching a lot between different branches, it is recommended
Otherwise, a lot of directories can be left over, which would be included in the source-release zip.
In order to prepare a release-candidate, the first step is switching to the corresponding release-branch.
-NOTE: Be sure to ensure you have switched to the release branch before continuing.
+NOTE: Again, just in case you missed the first warning: Be sure to ensure you have switched to the release branch before continuing.
After that, the following command will to all preparation steps for the release:
@@ -125,8 +127,8 @@ After that, the following command will to all preparation steps for the release:
In general the plugin will now ask you 3 questions:
-1. The version we want to release as (It will suggest the version you get by omitting the `-SNAPSHOT` suffix)
-2. The name of the tag the release commit will be tagged with in the SCM (Name it `releases/code-generation/{release-version}` (`releases/code-generation/{current-full-version}` in our case)
+1. The version we want to release as (It will suggest the version you get by omitting the `-SNAPSHOT` suffix, keep it as it is)
+2. The name of the tag the release commit will be tagged with in the SCM (Name it `releases/code-generation/{release-version}` (`releases/code-generation/{code-generation-full-version}` in our case)
3. The next development version (The version present in the pom after the release) (leave it as it is suggested by the plugin)
Usually for 1 and 3 the defaults are just fine, make sure the tag name is correct as this usually is different.
@@ -138,7 +140,7 @@ What the plugin now does, is automatically to execute the following operations:
1. Check we aren't referencing any `SNAPSHOT` dependencies.
2. Update all pom versions to the release version.
3. Run a build with all tests
-4. Commit the changes (commit message: `[maven-release-plugin] prepare release releases/code-generation/{current-full-version}`)
+4. Commit the changes (commit message: `[maven-release-plugin] prepare release releases/code-generation/{code-generation-full-version}`)
5. Push the commit
6. Tag the commit
7. Update all poms to the next development version.
@@ -152,7 +154,7 @@ is in the correct state. Please select the release branch and verify the commit
image::release-git-history.png[]
-It is important that the commit with the message "[maven-release-plugin] prepare release releases/code-generation/{current-full-version}" is tagged with the release tag (in this case releases/code-generation/{current-full-version})
+It is important that the commit with the message "[maven-release-plugin] prepare release releases/code-generation/{code-generation-full-version}" is tagged with the release tag (in this case releases/code-generation/{code-generation-full-version})
If you check the commit itself, it should mainly consist of version updates like this:
@@ -164,7 +166,7 @@ After that should come a second commit:
image::release-git-diff-next-development-iteration.png[]
-This now updates the versions again, but this time from the release version to the one we selected for the next development iteration (in this case `{current-next-minor-version}-SNAPSHOT`)
+This now updates the versions again, but this time from the release version to the one we selected for the next development iteration (in this case `{code-generation-bugfix-version}-SNAPSHOT`)
NOTE: If the commit history doesn't look like this, something went wrong.
@@ -226,19 +228,20 @@ The directory structure of this directory is as follows:
[subs="verbatim,attributes"]
----
./KEYS
- ./build-tools/code-generation/{current-full-version}
- ./build-tools/code-generation/{current-full-version}/rc1
- ./build-tools/code-generation/{current-full-version}/rc1/README
- ./build-tools/code-generation/{current-full-version}/rc1/RELEASE_NOTES
- ./build-tools/code-generation/{current-full-version}/rc1/apache-plc4x-code-generation-{current-full-version}-source-release.zip
- ./build-tools/code-generation/{current-full-version}/rc1/apache-plc4x-code-generation-{current-full-version}-source-release.zip.asc
- ./build-tools/code-generation/{current-full-version}/rc1/apache-plc4x-code-generation-{current-full-version}-source-release.zip.sha512
+ ./build-tools/code-generation/{code-generation-full-version}
+ ./build-tools/code-generation/{code-generation-full-version}/rc1
+ ./build-tools/code-generation/{code-generation-full-version}/rc1/README
+ ./build-tools/code-generation/{code-generation-full-version}/rc1/RELEASE_NOTES
+ ./build-tools/code-generation/{code-generation-full-version}/rc1/apache-plc4x-code-generation-{code-generation-full-version}-source-release.zip
+ ./build-tools/code-generation/{code-generation-full-version}/rc1/apache-plc4x-code-generation-{code-generation-full-version}-source-release.zip.asc
+ ./build-tools/code-generation/{code-generation-full-version}/rc1/apache-plc4x-code-generation-{code-generation-full-version}-source-release.zip.sha512
----
-I usually prepare exactly the same directory structure, starting with the {current-full-version} locally and then just import everything using the following command:
+I usually prepare exactly the same directory structure, starting with the {code-generation-full-version} locally and then just import everything using the following command:
+[subs="verbatim,attributes"]
----
-svn import {current-full-version} https://dist.apache.org/repos/dist/dev/plc4x/build-tools/code-generation/{current-full-version} -m"Staging of rc1 of PLC4X Build-Tools (Code-Generation) {current-full-version}"
+svn import {code-generation-full-version} https://dist.apache.org/repos/dist/dev/plc4x/build-tools/code-generation/{code-generation-full-version} -m"Staging of rc1 of PLC4X Build-Tools (Code-Generation) {code-generation-full-version}"
----
The `KEYS` file contains the PGP public key which belongs to the private key used to sign the release artifacts.
@@ -264,10 +267,10 @@ The following would be the one used to do our first TLP release:
[subs="verbatim,attributes"]
----
E-Mail Topic:
- [VOTE] Apache PLC4X Build-Tools Code-Generation {current-full-version RC1
+ [VOTE] Apache PLC4X Build-Tools Code-Generation {code-generation-full-version} RC1
Message:
- Apache PLC4X Build-Tools Code-Generation {current-full-version} has been staged under [2]
+ Apache PLC4X Build-Tools Code-Generation {code-generation-full-version} has been staged under [2]
and it’s time to vote on accepting it for release.
All Maven artifacts are available under [1]. Voting will be open for 72hr.
@@ -276,7 +279,7 @@ The following would be the one used to do our first TLP release:
are required to pass.
Repository: https://gitbox.apache.org/repos/asf/plc4x-build-tools.git
- Release tag: releases/code-generation/{current-full-version}
+ Release tag: releases/code-generation/{code-generation-full-version}
Hash for the release tag: {replacethiswiththerealgitcommittag}
Per [3] "Before voting +1 PMC members are required to download
@@ -292,7 +295,7 @@ The following would be the one used to do our first TLP release:
[1] https://repository.apache.org/content/repositories/orgapacheplc4x-{somefourdigitnumber}
- [2] https://dist.apache.org/repos/dist/dev/plc4x/build-tools/code-generation/{current-full-version}/rc1/
+ [2] https://dist.apache.org/repos/dist/dev/plc4x/build-tools/code-generation/{code-generation-full-version}/rc1/
[3] https://www.apache.org/dev/release/validation.html#approving-a-release
[4] https://plc4x.apache.org/developers/release/validation.html
----
@@ -303,7 +306,7 @@ As it is sometimes to do the vote counting, if voting and discussions are going
[subs="verbatim,attributes"]
----
E-Mail Topic:
- [DISCUSS] Apache PLC4X Build-Tools Code-Generation {current-full-version} RC1
+ [DISCUSS] Apache PLC4X Build-Tools Code-Generation {code-generation-full-version} RC1
Message:
This is the discussion thread for the corresponding VOTE thread.
@@ -324,7 +327,7 @@ After the 72-our minimum wait period is over, and we have fulfilled the requirem
[subs="verbatim,attributes"]
----
E-Mail Topic:
- [RESULT] [VOTE] Apache PLC4X {current-full-version} RC1
+ [RESULT] [VOTE] Apache PLC4X Build-Tools Code-Generation {code-generation-full-version} RC1
Message:
So, the vote passes with 3 +1 votes by PMC members and one +1 vote by a non PMC member.
@@ -339,9 +342,9 @@ This is done by moving them inside the Apache SVN.
[subs="verbatim,attributes"]
----
- svn move -m "Release Apache PLC4X {current-full-version}" \
- https://dist.apache.org/repos/dist/dev/plc4x/{current-full-version}/rc1 \
- https://dist.apache.org/repos/dist/release/plc4x/{current-full-version}
+ svn move -m "Release Apache PLC4X {code-generation-full-version}" \
+ https://dist.apache.org/repos/dist/dev/plc4x/build-tools/code-generation/{code-generation-full-version}/rc1 \
+ https://dist.apache.org/repos/dist/release/plc4x/build-tools/code-generation/{code-generation-full-version}
----
This will make the release artifacts available and will trigger them being copied to mirror sites.
@@ -376,92 +379,19 @@ This has to be done with git
[subs="verbatim,attributes"]
----
git checkout release
-git merge release/{current-full-version}
+git merge releases/code-generation/{code-generation-full-version}
----
-When there are conflicts it could help to use the "theirs" merge strategy, i.e.,
+When there are conflicts it could help to use the `theirs` merge strategy, i.e.,
[subs="verbatim,attributes"]
----
-git merge -X theirs release/{current-full-version}
+git merge -X theirs releases/code-generation/{code-generation-full-version}
----
Possibly a manual conflict resolution has to be done afterwards. After that, changes need to
be pushed.
-=== Updating Jira
-
-1. Set the released version to "released" and set the "release-date"
-2. Add the next version to the versions.
-
-=== Update the download site
-
-The URL http://plc4x.apache.org/users/download.html has to be changed and the current release
-has to be listed there.
-This is done by changing the `download.adoc` under `src/site/users/` (**in the develop branch, as this is where the site is generated from!**)
-
-1. Copy the last release down to _Previous Releases_
-2. Point the download links of the last release to archive, e.g. `http://archive.apache.org/dist/plc4x/{current-full-version}/apache-plc4x-{current-full-version}-source-release.zip`
-3. Add the new Release under _Current Releases_ and change all links.
-_Note: Please add an anchor for the toc_
-4. Update the sections for the changes according to the _RELEASE_NOTES_ from the release
-_Note: Transfer all to ascii-doc notation to ensure correct rendering of the site_
-_Also remove the JIRA TICKET ids in Front_
-
-=== Notifying the world
-
-Make sure you have given the Apache mirrors time to fetch the release files by waiting at least 24 hours after moving the release candidate to the release part of the SVN.
-
-After that it is time to announce your release to the world:
-
-[subs="verbatim,attributes"]
-----
- From:
-your apache email address
- To:
-announce@apache.org
-
- CC:
-dev@plc4x.apache.org
-
- E-Mail Topic:
-[ANNOUNCE] Apache PLC4X {current-full-version} released
-
- Message:
-The Apache PLC4X team is pleased to announce the release of Apache PLC4X {current-full-version}
-
-PLC4X is a set of libraries for communicating with industrial programmable
-logic controllers (PLCs) using a variety of protocols but with a shared API.
-
-The current release contains drivers able to communicate with industrial PLCs using one of the following protocols:
-
- * Siemens S7 (0x32)
- * Beckhoff ADS
- * Modbus
- * EtherNet/IP
-
-Beyond that we also provide integration modules for the following Apache projects and frameworks:
-
- * Apache Edgent (Incubating)
- * Apache Camel
- * Apache Kafka (Kafka Connect)
-
-Visit the Apache PLC4X website [1] for general information or
-the downloads page [2] for release notes and download information.
-
-Regards,
-The Apache PLC4X team
-
-[1] http://plc4x.apache.org
-[2] http://plc4x.apache.org/users/download.html
-----
-
-It is important to note that you have to send this email from your apache email address or it will be rejected.
-This wasn't very simple for me to setup.
-A general description can be found here:
-https://reference.apache.org/committer/email
-Here's what I did in google mail to allow sending of emails:
-https://gmail.googleblog.com/2009/07/send-mail-from-another-address-without.html
-Note ... you will be able to select the alternate sending address if you click into the recipients line of a new email (Not very intuitive).
+In contrast to main releases of PLC4X we won't do any JIRA version updates, updating of the download page or notifying of the world email to announce@apache.org
-After that email is out the door, you're done. Congrats!
\ No newline at end of file
+So now you're done. Congrats!
\ No newline at end of file