[UIMA-6436] Move maintainer documentation from website into maintainer guide

uima-doc-v3-maintainers-guide/src/docs/asciidoc/common_book_info.adoc

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-Copyright © 2006, 2021 The Apache Software Foundation
+Copyright © 2006, 2023 The Apache Software Foundation
 
 Copyright © 2004, 2006 International Business Machines Corporation
 

uima-doc-v3-maintainers-guide/src/docs/asciidoc/uv3.maven.adoc

@@ -22,14 +22,16 @@ This section describes various functionalities provided by the UIMA Parent POM a
 == Issues fixed report
 
 In order for your project to generate an **issues fixed** report from the ASF Jira, add 
-an empty file called `marker-file-identifying-parent-pom` to the root of your Maven project.
-This activates the `mavenJirareport` profile from the parent POM.
+an empty file called `marker-file-enabling-changes-report` to the root of your Maven project.
+This activates the `generate-changes-report` profile from the parent POM.
 
-Additionally, set the property `jiraVersion` in the `pom.xml` at your project's root to
+You can also generate this report manually (for instance, if you want to have a look at what it will produce) by going to top level project being released (e.g., `uima-uimaj`) and issuing the maven command:
 
-    <jiraVersion>${parsedVersion.majorVersion}.${parsedVersion.minorVersion}.${parsedVersion.incrementalVersion}SUFFIX</jiraVersion>
+----
+mvn changes:github-report -N
+----
 
-The properties are provided by the `build-helper-maven-plugin` in the UIMA Parent POM. You just need to add the `SUFFIX` for your project depending on how it is called in Jira, e.g. `SDK` for the Apache Java SDK or `uimaFIT` for uimaFIT.
+Each time this profile/plugin is run, it creates an updated report in the top level of this project. This report doesn't need to be checked into source control.
 
 
 == Auto-staging of release candidates
@@ -42,7 +44,12 @@ Below is an example of how to copy the release artifacts to the local staging sp
 
     <profiles>
       <profile>
-        <id>apache-release</id>
+        <id>apache-release-rc-auto-staging-config</id>
+        <activation>
+          <property>
+            <name>!disable-rc-auto-staging</name>
+          </property>
+        </activation>
         <build>
           <plugins>
             <plugin>

uima-doc-v3-maintainers-guide/src/docs/asciidoc/uv3.one-time-setup.adoc

@@ -21,22 +21,25 @@
 
 Most Apache UIMA code is written in Java. To build it, you need a recent Java Development Kit (JDK) which can be obtained from the link:https://adoptium.net[Eclipse Adoptium] project - but there are also plenty of other JDK vendors offering free JDKs (or even ones with commercial support).
 
-The minimum Java version required for Apache UIMA is: **1.8**
+The minimum Java version required for building Apache UIMA is: **17**
+The minimum Java version required for using Apache UIMA as a library is: **1.8**
 
 It is recommended to install the latest long term support (LTS) Java version and use it for development. When performing a release, a minimum-version JDK should be used to ensure compatibility for downstream users.
 
 == Version control: Git and Subversion
 
-Apache UIMA projects use Subversion as well as Git. Thus, you should install a Subversion client as well as a Git client - best the latest available version.
-If you are using an IDE, you should also install a suitable Subversion and Git plugin for the IDE. Most IDEs come with Git plugins already pre-installed. If you are lucky, it might be enough for you. If you need to work with one of the older Subversion repositories of the project, having the Subversion plugin is handy as well.
+Apache UIMA projects use Git although some projects still reside in Subversion and releases are
+staged to the ASF Subversion repository. Thus, you should install a Subversion client as well as a
+Git client - best the latest available version.
+If you are using an IDE, you may also care to install a suitable Subversion in addition to the Git plugin for the IDE. Most IDEs come with Git plugins already pre-installed. If you are lucky, it might be enough for you. If you need to work with one of the older Subversion repositories of the project, having the Subversion plugin is handy as well.
 
 NOTE: Configure your SVN client to set the eol-style to native, for newly created files; see https://apache.org/dev/svn-eol-style.txt for instructions on how to do this.
 
 == IDE: Eclipse or another one
 
 Eclipse is usually the IDE of choice for UIMA developers because UIMA provides several Eclipse plugins to facilitate editing UIMA XML descriptor files and the example projects are also currently provided as Eclipse projects.
 
-NOTE: You can also use another IDE like IntelliJ, Netbeans or even VSCode because the builds themselves is largely driven by Maven - **but for building the Eclipse update sites as part of the release process, also an Eclipse installation is required.**
+NOTE: You can also use another IDE like IntelliJ, Netbeans or even VSCode because the builds themselves are largely driven by Maven.
 
 == Build tool: Maven
 
@@ -45,7 +48,7 @@ Most Apache UIMA sub-projects are built using Apache Maven version 3 or higher.
 You can download the latest Maven version from https://maven.apache.org/download.html or install it using your favourite package manager. Most Java IDEs already come with Maven support pre-installed. If your IDE does not offer Maven support out-of-the-box, you may want to install a suitable plugin.
 
 * Download the latest Apache Maven from .
-* Set up your `PATH`` to use this version.
+* Set up your `PATH` to use this version.
 * (Optional, but is needed for some JVM/platforms, to give the JVM enough room to build things). Set the environment variable `MAVEN_OPTS` to `-Xmx800m  -XX:MaxPermSize=256m`
 
 === Maven toolchains

uima-doc-v3-maintainers-guide/src/docs/asciidoc/uv3.release.adoc

@@ -26,9 +26,7 @@ Releases show up in the Maven central repository and/or as downloadable artifact
 
 == Release planning
 
-Release planning happens in the issue tracker:
-
-* link:https://issues.apache.org/jira/projects/UIMA/[Apache UIMA Issue Tracker]
+Release planning happens in the issue tracker of the particular project on GitHub.
 
 As part of the planning, new issues are created and typically one somebody assigns the issue to themselves, they also set target version to the next bugfix or feature release in line.
 
@@ -78,38 +76,6 @@ The Maven release plugin will complain if there are still any `SNAPSHOT` depende
 ====
 * {empty}
 +
-.Update Jira version in POM for fixed-issues report **(deprecated)**
-[%collapsible]
-====
-**Deprecated**
-
-Set the property to based on version variables to avoid having to update it every time.
-
-    <jiraVersion>${parsedVersion.majorVersion}.${parsedVersion.minorVersion}.${parsedVersion.incrementalVersion}SUFFIX</jiraVersion>
-
-
-----
-
-Edit the POM of the top level thing being released, to add the property:
-
-----
-<jiraVersion>2.10.2SDK</jiraVersion>
-----
-
-replacing the `2.10.2SDK` with the actual Jira version name for the Jira release being done. This value is used during release processing to automatically generate a report of the list of Jira issues that are included in this release. Change `2.10.2SDK` to be the actual jira version name, which you can get from the Jira URL by going to https://issues.apache.org/jira/browse/UIMA and selecting **Releases** and then going to the particular version and copying its name.
-
-You can also generate this report manually (for instance, if you want to have a look at what it will produce) by going to top level project being released (e.g., `uima-uimaj`) and issuing the maven command:
-
-----
-mvn changes:jira-report -N
-----
-
-Each time this plugin is run, it creates an updated report in the top level of this project. This report doesn't need to be checked into source control. It will be regenerated and copied into the distribution archives (source and binary) during a release. The `RELEASE_NOTES.html` files have been updated to refer to this generated report.
-
-Running the mvn release... command will cause this report to be generated or updated, every time the command is run. So it is important that the POM is updated to include the internal Jira version number, so the right report is generated.
-====
-* {empty}
-+
 .Update API reference version in POM
 [%collapsible]
 ====
@@ -133,9 +99,11 @@ NOTE: There may be a generation process involved. E.g. in the UIMA Java SDK, the
 .Clean local m2 repository
 [%collapsible]
 ====
-Purge your local maven repository of artifacts being built by running in the top level directory you'll be building from:
+Purge your local maven repository of artifacts being built by running in the top level directory you will be building from:
 
+----
 mvn dependency:purge-local-repository
+----
 
 Note that this will immediately re-resolve the dependencies from the maven repositories you have configured.
 
@@ -158,18 +126,18 @@ If you instead choose to build from your *working* source control checkout, insu
 Do a trial build of the release candidate:
 
     $ cd YOUR-BUILD-DIRECTORY 
-    $ mvn clean install -Papache-release
+    $ mvn clean install -Papache-release -Ddisable-rc-auto-staging
 
-The `-Papache-release` is used to have the build mimic the build actions that would be taken when the release plugin is running the release build.
+The `-Papache-release` is used to have the build mimic the build actions that would be taken when the release plugin is running the release build. The `-Ddisable-rc-auto-staging` ensures that you do not
+need Subversion and also that you do not (accidentally) stage the release candidate artifacts to the
+Apache staging area.
 ====
 * {empty}
 +
 .Check the issues report in `issuesFixed` if it looks ok
 [%collapsible]
 ====
-The build includes a generated set of Jira issues fixed (closed or resolved) in this release. To make this accurate, go through the Jiras and ensure the ones you are including in the release are closed/resolved, and that the "Fixed in release xxx" is set for each Jira issue that is part of the release.
-
-There is a saved "filter" you can adjust for this that will display all fixed Jira issues with no Fixed in release xxx assigned. You can go through subsets of this (use the filter to pick the subset you want) and do "bulk Jira changes" to update multiples of these in parallel, if that makes sense.
+The build includes a generated set of issues fixedin this release. To make this accurate, go through the issues and ensure the ones you are including in the release are closed, and that the milestone is set for each issue that is part of the release.
 ====
 * {empty}
 +
@@ -218,76 +186,7 @@ If you have several artifacts to release, and you want subsequent artifacts to d
 
 If you forget something and close the staging repository too soon, just continue as if you hadn't. Subsequent release artifacts will go into another newly created staging spot on Nexus. The downside of this is that you'll have to tell the *voters* about multiple staging repos.
 ====
-* {empty}
-+
-.Check that files have been auto-staged (or stage manually)
-[%collapsible]
-====
-We have a link:https://dist.apache.org/repos/dist/dev/uima/[staging spot] for all the release candidate artifacts to be later fully released via the Apache mirror system.
-
-The UIMA Parent POM offsets an auto-staging mechanism for release candidate artifacts that you should use. If it is not usable for you, then you have to stage the artifacts manually.
 
-Be sure to copy artifacts from the build-from tag spot, which should have a path like: `...[top level project]/target/checkout/target`. Note this is **NOT** from `[top level project]/target`. Doing this will guarantee that you're posting the artifacts built from the tag (which could be different from the `release:prepare` build in /target if someone snuck in a svn commit at the right moment.)
-
-Copy any artifacts (together with their signings) to the staging spot. A suggested approach: Make a new dir in the build project, called svnUpload (or whatever), and copy the artifacts (from the `...[top level project]/target/checkout/target` directory!) (typically the bin/zip/tar and the source release and all the signature/checksums) into this dir. Then do the svn command:
-
-```
-$ cd the-svnUpload-directory 
-$ svn import -m "commit msg, e.g. uimaj-2.8.0 rc5" . https://dist.apache.org/repos/dist/dev/uima/uimaj/n.n.n-rc1/artifacts
-```
-
-Do not add files like POMs which have line-endings, if they have signatures; the files added should be "binary" style files. (The line endings (if you build on windows) will be changed upon upload to svn, which will result in bad signatures).
-====
-* {empty}
-+
-.Update the version in the `uimaj-eclipse-update-site` **(deprecated)**
-[%collapsible]
-====
-**Deprecated:** Use Tycho instead to build update sites along with every regular build.
-
-For a general background on how we build P2 sites, including Composite update sites, see link:https://uima.apache.org/eclipse-update-site.html[eclipse-update-site] page.
-====
-* {empty}
-+
-.Set `dropPrevVersions` to `true` in the `uimaj-eclipse-update-site` POM **(deprecated)**
-[%collapsible]
-====
-**Deprecated:** Use Tycho instead to build update sites along with every regular build.
-
-For a general background on how we build P2 sites, including Composite update sites, see link:https://uima.apache.org/eclipse-update-site.html[eclipse-update-site] page.
-====
-* {empty}
-+
-.Build the `uimaj-eclipse-update-site` module with {{-Papache-release}} **(deprecated)**
-[%collapsible]
-====
-**Deprecated:** Use Tycho instead to build update sites along with every regular build.
-
-For a general background on how we build P2 sites, including Composite update sites, see link:https://uima.apache.org/eclipse-update-site.html[eclipse-update-site] page.
-
-The component being released, if it has Eclipse features, will have its own Eclipse update (sub) site, which should be built along with the normal build of the entire component, as part of that component's release.
-
-In building that component's update site, you may need to edit/update the affected component's feature project(s), and the category.xml file in the update-site, before building it. For releases, run the signEclipseUpdateSite.sh (on Windows - inside Cygwin) to sign the Jars. (Optional:) There's also a verifySignsEclipseUpdateSite.sh you can run to verify the signing was successful.
-
-If a new Eclipse update site is being added to the composite, edit in the composite project (.../build/uima-eclipse-composite-update-site) the buildCompositeRepository.xml file to add the new update site. If doing a release, run the signing script for the composite site too.
-
-The actual creation of the update site is done in several steps, following the conventions to link:https://uima.apache.org/saving-svn-resources.html[save SVN resources]. The Maven build for Eclipse update sites will end up with files in .../target/eclipse-update-site/[subsite] which should be copied to some accessible spot for Voting/ testing. (After the vot passes, the files in the target site can be svn switched to the release directory and committed.)
-
-Test the result: using the extended composite repository in various versions of Eclipse, and verify it installs OK.
-
-If you changed the composite site, bump up the version of .../build/uima-eclipse-composite-site/pom.xml and commit project changes to the trunk, and tag it. The component's individual update sites should be built and tagged as part of that project's release.
-====
-* {empty}
-+
-.Upload the update site to a subdirectory of the release staging spot and *commit* (*Caution:* the update site contains a `.svn` folder that needs to be removed!)  **(deprecated)**
-[%collapsible]
-====
-**Deprecated:** Use auto-staging instead.
-
-FIXME: Eclipse update site process needs updating...
-
-For a general background on how we build P2 sites, including Composite update sites, see link:https://uima.apache.org/eclipse-update-site.html[eclipse-update-site] page.
-====
 
 === Voting
 
@@ -343,6 +242,8 @@ Thanks.
 ====
 **Before casting +1 binding votes, individuals are REQUIRED to download all signed source code packages onto their own hardware, verify that they meet all requirements of ASF policy on releases as described below, validate all cryptographic signatures, compile as provided, and test the result on their own platform.**
 
+_Source_: https://www.apache.org/legal/release-policy.html#release-approval
+
 .Create a release candidate validation folder
 ----
 % mkdir rc-validation
@@ -395,6 +296,19 @@ rm "$tmp"
 % rm checkHashes.sh
 ----
 
+.Check that the contents of the sources ZIP match the repository tag
+----
+% wget https://github.com/apache/[project]/archive/[release-commit-hash].zip
+% unzip [release-commit-hash].zip
+% diff -r ...
+----
+
+.Run a local build from the sources ZIP
+Typically, we have Maven projects, so this would running a Maven Build
+----
+% mvn clean install
+----
+
 For more information on the ASF release policy, please see the link:https://www.apache.org/legal/release-policy.html[Apache Release Policy] document.
 ====
 * {empty}
@@ -404,7 +318,6 @@ For more information on the ASF release policy, please see the link:https://www.
 ====
 * Check the issues-fixed report
 * Check the release notes
-* Run a local build from the sources zip
 * Install plugins into Eclipse
 * Try out an example
 * ...
@@ -511,12 +424,20 @@ Merge the release preparation pull request just like any other PR via the GitHub
 .Update website
 [%collapsible]
 ====
+.Update downloads
 Update the download page of the UIMA website to make the new release artifacts available. This is done indirectly, by editing both the `downloads.xml` page and also by adding entries to the `xdocs/stylesheets/project.xml` page - follow the previous examples.
 
+.Update documentation
 Also, things not needed to be mirrored go into our website: in the `docs/d` directory. Currently, this includes `the RELEASE_NOTES` (plus `issuesFixed`) for the release, the new documentation, and the Javadocs.
 
-Copy `RELEASE_NOTES` and `issuesFixed` from the top level project (where the mvn `release:perform` was done from) in the directory `target/checkout/` ... to the the website in `docs/d/[project-version]`.
+Copy `RELEASE_NOTES` and `issuesFixed` from the top level project (where the mvn `release:perform` was done from) in the directory `target/checkout/` ... to the the website in `docs/d/[project]-current`. The documentation for the latest release should always be in the `[project]-current` folder. A copy of that should be created under `https://svn.apache.org/repos/asf/uima/site/archive/docs/d/[project]-[version]`.
+
+.Example
+----
+svn copy -m "Creating versioned copy of current release documentation in archive" https://svn.apache.org/repos/asf/uima/site/trunk/uima-website/docs/d/ruta-current https://svn.apache.org/repos/asf/uima/site/trunk/uima-website/docs/d/ruta-3.2.0
+----
 
+.Update news
 Our main UIMA website has a **News** section that should be updated with news of the release. There are 2 place to update: One is the `index.xml` file, which has a one-line summary (at the bottom) that references a link within the `new.xml` page; and a new entry in the `news.xml` page itself. Follow previous examples.
 ====
 * {empty}