feat: integrate no-npe EEA generator

.github/dependabot.yml

@@ -0,0 +1,32 @@
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "10:00"
+    commit-message:
+      prefix: ci
+      prefix-development: ci
+      include: scope
+    labels:
+      - pinned
+      - dependencies
+      - gha
+
+  - package-ecosystem: maven
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "10:00"
+    commit-message:
+      prefix: fix
+      prefix-development: build
+      include: scope
+    labels:
+      - pinned
+      - dependencies
+      - mvn

.github/workflows/build.yml

@@ -0,0 +1,176 @@
+# SPDX-FileCopyrightText: © Vegard IT GmbH (https://vegardit.com) and others.
+# SPDX-FileContributor: Sebastian Thomschke (Vegard IT GmbH)
+# SPDX-License-Identifier: EPL-2.0
+
+# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
+name: Build
+
+on:
+  push:
+    branches-ignore:  # build all branches except:
+    - 'dependabot/**'  # prevent GHA triggered twice (once for commit to the branch and once for opening/syncing the PR)
+    tags-ignore:  # don't build tags
+    - '**'
+    paths-ignore:
+    - '**/*.adoc'
+    - '**/*.md'
+    - '.editorconfig'
+    - '.git*'
+    - '.github/*.yml'
+    - '.github/workflows/stale.yml'
+    - '.github/workflows/update-eea-files.yml'
+  pull_request:
+    paths-ignore:
+    - '**/*.adoc'
+    - '**/*.md'
+    - '.editorconfig'
+    - '.git*'
+    - '.github/*.yml'
+  workflow_dispatch:
+    # https://github.blog/changelog/2020-07-06-github-actions-manual-triggers-with-workflow_dispatch/
+    inputs:
+      additional_maven_args:
+        description: 'Additional Maven Args'
+        required: false
+        default: ''
+
+
+defaults:
+  run:
+    shell: bash
+
+
+jobs:
+
+  ###########################################################
+  build:
+  ###########################################################
+    runs-on: ubuntu-latest
+
+
+    # https://docs.github.com/en/actions/using-jobs/using-concurrency
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: false
+
+
+    steps:
+    - name: "Show: GitHub context"
+      env:
+        GITHUB_CONTEXT: ${{ toJSON(github) }}
+      run: echo $GITHUB_CONTEXT
+
+
+    - name: "Show: environment variables"
+      run: env | sort
+
+
+    - name: Git Checkout
+      uses: actions/checkout@v4  # https://github.com/actions/checkout
+
+
+    - name: "Install: JDK 17 ☕"
+      uses: actions/setup-java@v4  # https://github.com/actions/setup-java
+      with:
+        distribution: temurin
+        java-version: 17
+    - run: echo "JAVA17_HOME=$JAVA_HOME" >> $GITHUB_ENV
+
+
+    - name: "Install: JDK 21 ☕"
+      uses: actions/setup-java@v4  # https://github.com/actions/setup-java
+      with:
+        distribution: temurin
+        java-version: 21
+    - run: echo "JAVA21_HOME=$JAVA_HOME" >> $GITHUB_ENV
+
+
+    - name: "Show: toolchains.xml"
+      run: cat "$HOME/.m2/toolchains.xml"
+
+
+    - name: "Cache: Local Maven Repository"
+      uses: actions/cache@v4
+      if: ${{ !env.ACT }}  # https://github.com/nektos/act#skipping-steps
+      with:
+        # Excluded sub directory not working https://github.com/actions/toolkit/issues/713
+        path: |
+          ~/.m2/repository/*
+          !~/.m2/repository/*SNAPSHOT*
+        key: ${{ runner.os }}-mvn-${{ hashFiles('**/pom.xml') }}
+
+
+    - name: "Install: Maven 📦"
+      uses: stCarolas/setup-maven@v5  # https://github.com/stCarolas/setup-maven
+      with:
+        maven-version: 3.9.9
+
+
+    - name: Prepare Maven Snapshots Repo
+      if: ${{ github.ref_name == 'main' && !env.ACT }}  # https://github.com/nektos/act#skipping-steps
+      run: |
+        set -eux
+
+        cd /tmp
+        github_repo_url="https://${{ github.actor }}:${{ github.token }}@github.com/${{ github.repository }}/"
+        if curl --output /dev/null --silent --head --fail "$github_repo_url/tree/mvn-snapshots-repo"; then
+          git clone https://${{ github.actor }}:${{ github.token }}@github.com/${{ github.repository }}/ --single-branch --branch mvn-snapshots-repo mvn-snapshots-repo
+          cd mvn-snapshots-repo
+          # https://github.community/t/github-actions-bot-email-address/17204
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git reset --hard HEAD^ # revert previous commit
+        else
+          git clone https://${{ github.actor }}:${{ github.token }}@github.com/${{ github.repository }}/ mvn-snapshots-repo
+          cd mvn-snapshots-repo
+          git checkout --orphan mvn-snapshots-repo
+          git rm -rf .
+          cat <<EOF > index.html
+            <!DOCTYPE html>
+            <html>
+            <head>
+              <title>${{ github.repository }} - Maven Snapshots Repo</title>
+            </head>
+            <body>
+            <h1>${{ github.repository }} - Maven Snapshots Repo</h1>
+            </body>
+            </html>
+        EOF
+          git add index.html
+          # https://github.community/t/github-actions-bot-email-address/17204
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -am "Initialize Maven Snapshots Repo"
+        fi
+
+
+    - name: "Build with Maven 🔨"
+      run: |
+        set -euo pipefail
+
+        MAVEN_OPTS="${MAVEN_OPTS:-}"
+        MAVEN_OPTS+=" -Djava.security.egd=file:/dev/./urandom" # https://stackoverflow.com/questions/58991966/what-java-security-egd-option-is-for/59097932#59097932
+        MAVEN_OPTS+=" -Dorg.slf4j.simpleLogger.showDateTime=true -Dorg.slf4j.simpleLogger.dateTimeFormat=HH:mm:ss,SSS" # https://stackoverflow.com/questions/5120470/how-to-time-the-different-stages-of-maven-execution/49494561#49494561
+        MAVEN_OPTS+=" -Xmx1024m -Djava.net.preferIPv4Stack=true -Dhttps.protocols=TLSv1.3,TLSv1.2"
+        export MAVEN_OPTS
+        echo "MAVEN_OPTS: $MAVEN_OPTS"
+
+        mvn \
+          --errors \
+          --update-snapshots \
+          --batch-mode \
+          --show-version \
+          ${{ github.event.inputs.additional_maven_args }} \
+          clean ${{ (github.ref_name == 'main' && !env.ACT) && 'deploy' || 'verify' }} \
+          -DaltSnapshotDeploymentRepository=temp-snapshots-repo::file:///tmp/mvn-snapshots-repo
+
+
+    - name: Update Maven Snapshots Repo
+      if: ${{ github.ref_name == 'main' && !env.ACT }}  # https://github.com/nektos/act#skipping-steps
+      run: |
+        cd /tmp/mvn-snapshots-repo
+        if [[ $(git -C . ls-files -o -m -d --exclude-standard | wc -l) -gt 0 ]]; then
+          git add --all
+          git commit -am "Deploy snapshot version"
+          git push origin mvn-snapshots-repo --force
+        fi

README.md

@@ -1,13 +1,31 @@
-[![Build Status](https://travis-ci.org/lastnpe/eclipse-null-eea-augments.svg)](https://travis-ci.org/lastnpe/eclipse-null-eea-augments)
-
 # Eclipse External null Annotations (EEA)
 
+[![Build Status](https://github.com/lastnpe/eclipse-null-eea-augments/workflows/Build/badge.svg "GitHub Actions")](https://github.com/lastnpe/eclipse-null-eea-augments/actions?query=workflow%3A%22Build%22)
+[![License](https://img.shields.io/github/license/lastnpe/eclipse-null-eea-augments.svg?color=blue)](LICENSE.txt)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.1%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)
+
+1. [What is this?](#what-is-this)
+1. [How to use this](#usage)
+   1. [Binaries](#binaries)
+   1. [Building from Sources](#building)
+   1. [Validating/Updating EEA files](#validate_update)
+1. [How to contribute](#contribute)
+1. [Troubleshooting](#troubleshooting)
+1. [Future](#future)
+1. [License](#license)
+
+
+## <a name="what-is-this"></a>What is this?
+
 This repository contains *.eea files and example projects how to use this.
 
 If you like/use this project, a Star / Watch / Follow on GitHub is appreciated.
 
 
-## How to use this
+## <a name="usage"></a>How to use this
+
+General usage of External Null Annotations in Eclipse is documented at
+https://help.eclipse.org/latest/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/task-using_external_null_annotations.htm
 
 [See theses slides here](http://www.slideshare.net/mikervorburger/the-end-of-the-world-as-we-know-it-aka-your-last-nullpointerexception-1b-bugs) from this
 [EclipseCon Europe 2016 presentation](https://www.eclipsecon.org/europe2016/session/end-world-we-know-it-aka-your-last-nullpointerexception-1b-bugs) for some background about this project.
@@ -17,7 +35,120 @@ recommend you install the [eclipse-external-annotations-m2e-plugin](https://gith
 (On Eclipse m2e versions < 1.8 (shipped with Oxygen), you also had to install [m2e-jdt-compiler](https://github.com/jbosstools/m2e-jdt-compiler), but with M2E 1.8 in Oxygen that is not necessary anymore, even harmful; see below.)
 
 
-## Contribute
+### <a id="binaries"></a>Binaries
+
+Latest **Release** binaries are available on Maven central, see https://search.maven.org/search?q=g%3Aorg.lastnpe.eea
+
+Latest **Snapshot** binaries are available via the [mvn-snapshots-repo](https://github.com/lastnpe/eclipse-null-eea-augments/tree/mvn-snapshots-repo) git branch.
+You need to add this repository configuration to your Maven `settings.xml`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 https://maven.apache.org/xsd/settings-1.2.0.xsd">
+  <profiles>
+    <profile>
+      <repositories>
+        <repository>
+          <id>lastnpe-snapshots</id>
+          <name>lastnpe-snapshots</name>
+          <url>https://raw.githubusercontent.com/lastnpe/eclipse-null-eea-augments/mvn-snapshots-repo</url>
+          <releases><enabled>false</enabled></releases>
+          <snapshots><enabled>true</enabled></snapshots>
+        </repository>
+      </repositories>
+    </profile>
+  </profiles>
+  <activeProfiles>
+    <activeProfile>lastnpe-snapshots</activeProfile>
+  </activeProfiles>
+</settings>
+```
+
+
+### <a id="building"></a>Building from Sources
+
+The project also uses the [maven-toolchains-plugin](http://maven.apache.org/plugins/maven-toolchains-plugin/) which decouples the JDK that is
+used to execute Maven and it's plug-ins from the target JDK that is used for compilation and/or unit testing. This ensures full binary
+compatibility of the compiled artifacts with the runtime library of the required target JDK.
+
+To build the project follow these steps:
+
+1. Download and install Java 17 **AND** Java 21 SDKs, e.g. from:
+   - Java 17: https://adoptium.net/releases.html?variant=openjdk17 or https://www.azul.com/downloads/?version=java-17-lts&package=jdk#download-openjdk
+   - Java 21: https://adoptium.net/releases.html?variant=openjdk21 or https://www.azul.com/downloads/?version=java-21-lts&package=jdk#download-openjdk
+
+1. Download and install the latest [Maven distribution](https://maven.apache.org/download.cgi).
+
+1. In your user home directory create the file `.m2/toolchains.xml` with the following content:
+
+   ```xml
+   <?xml version="1.0" encoding="UTF8"?>
+   <toolchains xmlns="http://maven.apache.org/TOOLCHAINS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:schemaLocation="http://maven.apache.org/TOOLCHAINS/1.1.0 https://maven.apache.org/xsd/toolchains-1.1.0.xsd">
+      <toolchain>
+         <type>jdk</type>
+         <provides>
+            <version>17</version>
+            <vendor>default</vendor>
+         </provides>
+         <configuration>
+            <jdkHome>[PATH_TO_YOUR_JDK_17]</jdkHome>
+         </configuration>
+      </toolchain>
+      <toolchain>
+         <type>jdk</type>
+         <provides>
+            <version>21</version>
+            <vendor>default</vendor>
+         </provides>
+         <configuration>
+            <jdkHome>[PATH_TO_YOUR_JDK_21]</jdkHome>
+         </configuration>
+      </toolchain>
+   </toolchains>
+   ```
+
+   Set the `[PATH_TO_YOUR_JDK_17]`/`[PATH_TO_YOUR_JDK_21]` parameters accordingly
+   to where you installed the JDKs.
+
+1. Checkout the code, e.g. using:
+
+    - `git clone https://github.com/lastnpe/eclipse-null-eea-augments`
+
+1. Run `mvn clean verify` in the project root directory. This will execute compilation, unit-testing, integration-testing and
+   packaging of all artifacts.
+
+
+### <a name="validate_update"></a>Validating/Updating EEA files
+
+The EEA files can be validated/updated using:
+
+```bash
+# validate all EEA files of all eea-* modules
+mvn compile
+
+# validate all EEA files of a specific module
+mvn compile -am -pl <MODULE_NAME>
+mvn compile -am -pl libraries/gson
+
+# update/regenerate all EEA files of all eea-* modules
+mvn compile -Deea-generator.action=generate
+
+# update/regenerate all EEA files of a specific module
+mvn compile -Deea-generator.action=generate -am -pl <MODULE_NAME>
+mvn compile -Deea-generator.action=generate -am -pl libraries/gson
+```
+
+Updating EEA files will:
+- add new types/fields/methods found
+- remove obsolete declarations from the EEA files
+- preserve null/non-null annotations specified for existing fields/methods
+
+
+## <a name="contribute"></a>How to contribute
+
+Please consult the [CONTRIBUTING.md](CONTRIBUTING.md).
 
 This project aims to develop an active community of contributors, and not remain controlled by a single person.
 Anyone making 3 intelligent contributions to this repo may ask to be promoted from a contributor to a committer with full write access by opening an issue requesting it.
@@ -33,13 +164,25 @@ When making contributions with changes, please explain what is wrong in the curr
 We generally do not "self merge", but let other committers merge our own changes.
 
 
-## Troubleshooting
+## <a name="troubleshooting"></a>Troubleshooting
 
 * Uninstall the [jbosstools/m2e-jdt-compiler](https://github.com/jbosstools/m2e-jdt-compiler) to fix this problem: _Conflicting lifecycle mapping (plugin execution "org.apache.maven.plugins:maven-compiler-plugin:3.5.1:compile (execution: default-compile, phase: compile)"). To enable full functionality, remove the conflicting mapping and run Maven->Update Project Configuration._
 
 * Do `mvn install` of the `examples/maven/jdt-ecj-settings` to fix this problem, due to [M2E Bug 522393](https://bugs.eclipse.org/bugs/show_bug.cgi?id=522393): _CoreException: Could not get the value for parameter compilerId for plugin execution default-testCompile: PluginResolutionException: Plugin org.apache.maven.plugins:maven-compiler-plugin:3.5.1 or one of its dependencies could not be resolved: Failure to find ch.vorburger.nulls.examples:jdt-ecj-settings:jar:1.0.0-SNAPSHOT_
 
 
-## Future
+## <a name="future"></a>Future
 
 If this is found to be of general interest, perhaps this could move to eclipse.org. If this happens, it would be imperative to keep it very easy for anyone to contribute via Pull Requests on GitHub (and not, or not you only, eclipse.org Gerrit changes).
+
+
+## <a name="license"></a>License
+
+All files are released under the [Eclipse Public License 2.0](LICENSE.txt).
+
+Individual files contain the following tag instead of the full license text:
+```
+SPDX-License-Identifier: EPL-2.0
+```
+
+This enables machine processing of license information based on the SPDX License Identifiers that are available here: https://spdx.org/licenses/.