Skip to content

Commit

Permalink
Merge pull request #130 from rvesse/2.10
Browse files Browse the repository at this point in the history
Prepare for 3.0.0 release
  • Loading branch information
rvesse authored Nov 27, 2023
2 parents 283c4d7 + 8146ce4 commit 08c30fa
Show file tree
Hide file tree
Showing 308 changed files with 1,160 additions and 936 deletions.
5 changes: 4 additions & 1 deletion .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,18 +28,21 @@ jobs:
strategy:
fail-fast: false
matrix:
java: [ "8", "11", "17" ]
java: [ "11", "17" ]

steps:
- uses: actions/checkout@v3

- name: Set up JDK ${{ matrix.java }}
uses: actions/setup-java@v3
with:
java-version: ${{ matrix.java }}
distribution: 'temurin'
cache: maven

- name: Build with Maven
run: mvn -B -e -Prelease -Dgpg.skip=true clean install

- name: Run ITs and coverage
if: matrix.java == '11'
run: mvn -B -e verify -Dcoveralls.token=${{ secrets.COVERALLS_TOKEN }} -Pcoveralls
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,6 @@ _site/
docs/dist-version.txt
docs/find.xslt
docs/maven-metadata.xml
docs/.bundle/
docs/vendor/
docs/.jekyll-metadata
29 changes: 17 additions & 12 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
# Airline - Change Log

### Forthcoming 2.x Deprecation
### 3.x Deprecation

2.10.0, and any subsequent patch releases, are intended to be the last supported releases of Airline 2.x
Future releases will start to focus on the 4.x builds which include some important new features e.g. first class
positional argument support, better DI framework integration, that are not possible under 2.x/3.x without making
breaking changes. You can see progress on 4.x by following the `4x` branch and its `CHANGELOG.md` and `Migrating.md`
files.

Future releases will start to focus on the 3.x builds which include some important new features e.g. first class
positional argument support, better DI framework integration, that are not possible under 2.x without making breaking
changes. You can see progress on 3.x by following the `3x` branch and its `CHANGELOG.md` and `MIGRATING.md`

## 2.10.0
## 3.0.0

- Core Improvements
- First class support for `BigInteger` and `BigDecimal` as numeric types
Expand All @@ -17,6 +16,8 @@ changes. You can see progress on 3.x by following the `3x` branch and its `CHAN
deprecated
- Added a `JpmsResourceLocator` as an additional `ResourceLocator` to allow finding resources when running in a JPMS
context (requires additional module `airline-jpms-resources`)
- **BREAKING** - Only `@AirlineModule` is used as a composition annotation by default, use of the older
`@javax.inject.Inject` or `@jakarta.inject.Inject` annotations **MUST** now be explicitly configured.
- Help Improvements
- Added an `@SeeAlso` annotation to Airline Core (#51)
- **BREAKING** - `airline-help-bash` has moved `@BashCompletion` annotation into
Expand All @@ -26,15 +27,14 @@ changes. You can see progress on 3.x by following the `3x` branch and its `CHAN
- A `ParserBuilder` created by calling `withParser()` on a `CliBuilder` can now return control back to its parent via
the `parent()` method for cleaner Fluid CLI definitions
- Dependency Updates
- **BREAKING** - Minimum JDK Version is now 11
- Apache Commons Collections upgraded to 4.4
- Apache Commons Lang upgraded to 3.12.0
- Apache Commons Lang upgraded to 3.14.0
- `jakarta.inject` and `airline-backcompat-javaxinject` were made `optional` so will no longer be pulled in
automatically
- Various build plugins updated to the latest available versions (this only impacts developers building the library
from source)
- Added new `airline-help-external` module with a dependency on Apache Commons CSV 1.10.0-20220310.222602-6
- Due to an upstream bug in Commons CSV they don't yet have an official release build with JPMS support so we are
currently locking to a timestamped SNAPSHOT
- Added new `airline-help-external` module with a dependency on Apache Commons CSV 1.10.0
- Added new `airline-jpms-resources` module with a dependency on
[ClassGraph](https://github.com/classgraph/classgraph) to enable resource location when Airline is used on Module
Path i.e. JPMS runtime context
Expand All @@ -49,13 +49,18 @@ changes. You can see progress on 3.x by following the `3x` branch and its `CHAN
- New `airline-help-external` modules provides new help annotations that allow more complex help to be provided via
classpath/file resources rather than directly in the annotations. This is a generalisation of the mechanism already
used by `@Version` annotation. (#52)
- Adds `@ExternalProse`, `@ExternalExitCodes`, `@ExternalExamples` and `@ExternalExamplesTabular` annotations
- Adds `@ExternalDiscussion` `@ExternalProse`, `@ExternalExitCodes`, `@ExternalExamples` and
`@ExternalExamplesTabular` annotations
- Build and Release Improvements
- All Airline modules are now fully fledged JPMS modules meaning they can be used on the JVM Module Path instead of
the Classpath where preferred
- See `airline-examples` module for examples of constructing a `module-info.java` that pulls in other Airline
modules and see `modularExample` script for examples of invoking an Airline based app using the Module Path

### 2.x Deprecation

3.0.0 is now released, so Airline 2.x will no longer be supported.

## 2.9.0

- Build Improvements
Expand Down
20 changes: 14 additions & 6 deletions Migrating.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
# Migration to Airline 2.10 from Airline 2.x
# Migration to Airline 3.0.0 from Airline 2.x

Airline 2.10 has a single minor breaking change that only affects users of the `airline-help-bash` module.
Airline 3.0.0 has several breaking changes

## Minimum Java Version is now 11

Java 11 is now required as the minimum Java version. This was necessary in order to be able to continue to use
up-to-date releases of our dependencies, and since Java 8 is now EOL.

## `@BashCompletion` package relocation

Expand All @@ -9,11 +14,14 @@ this annotation was moved into a new sub-package `com.github.rvesse.airline.anno

## Inject Dependencies are now optional

As noted in [Migrating to Airline 2.9](#migration-to-airline-29) Airline is moving away from usage of the `@Inject`
As noted in [Migrating to Airline 2.9](#migration-to-airline-29) Airline is moving away from usage of the `@Inject`
annotation for composition in favour of its own `@AirlineModule` annotation. As part of this move the `jakarta.
inject-api` and `airline-backcompat-javaxinject` dependencies became `optional` in 2.10. This means that if you have an
existing Airline based application that is using `@Inject` annotations you must now provide the relevant dependency
yourself as you will not automatically pick it up as a transitive dependency of Airline.
inject-api` and `airline-backcompat-javaxinject` dependencies became `optional` in `3.0.0`. This means that if you have
an existing Airline based application that is using `@Inject` annotations you **MUST** now provide the relevant
dependency yourself as you will not automatically pick it up as a transitive dependency of Airline.

You **MUST** also explicitly configure the `@Parser` configuration to use the old composition annotations if you still
need to use these.

# Migration to Airline 2.9

Expand Down
40 changes: 7 additions & 33 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,52 +93,23 @@ See provided **NOTICE** for Copyright Holders

## JDK Compatibility

### Source

Our source code is Java 7 compliant.

### Build

Airline can be built with Java 7 through 11 and our `pom.xml` contains appropriate profile customisations to enable this.
Regardless of the version built the `pom.xml` will target Java 7 byte code. Our official releases are built with
Java 11 but targeting Java 7 bytecode to maximise version compatibility.

It may be possible to build with newer Java versions than those stated here but those have not been tested by the
developers.

**NB** - If you are trying to build older versions from source the relevant `pom.xml` customisations may not have
existed at that time. Also. you may encounter SSL errors trying to download Maven plugins using older versions of
Java, you may need to first build with a newer version of Java to successfully download relevant Maven plugins before
then building with the desired version of Java.

### Runtime

Airline releases are configured to build Java 7 compatible bytecode so can be used with Java 7 or above.

#### JPMS

Airline does make heavy use of reflection and therefore will likely not work on the Module Path without exporting
packages that contain your CLI and Command classes as part of your `module-info.java`

From 2.7.0 onwards builds include contributions from our user community to enable use of Airline on the Module Path
including relevant `module-info.java` files. If you encounter a problem with this please report it at
https://github.com/rvesse/airline/issues
As of `3.0.0` Airline requires Java 11, see [guide/practise/jdk.md] for more details.

## Maven Artifacts

This library is available from [Maven Central](http://search.maven.org) with the latest stable release being `2.9.0`
This library is available from [Maven Central](http://search.maven.org) with the latest stable release being `3.0.0`

Use the following maven dependency declaration:

```xml
<dependency>
<groupId>com.github.rvesse</groupId>
<artifactId>airline</artifactId>
<version>2.9.0</version>
<version>3.0.0</version>
</dependency>
```

Snapshot artifacts of the latest source are also available using the version `2.10.0-SNAPSHOT` from the
Snapshot artifacts of the latest source are also available using the version `3.0.1-SNAPSHOT` from the
[OSSRH repositories](http://central.sonatype.org/pages/ossrh-guide.html#ossrh-usage-notes).

## Build Status
Expand Down Expand Up @@ -168,3 +139,6 @@ Airline 2.2 has some minor breaking changes that may affect users of the `@Argum
Airline 2.9 has some changes to composition in preparation for future breaking changes, most notably introducing the
`@AirlineModule` annotation as a replacement for `@Inject`. It remains backwards compatible with prior 2.x releases
but users may wish to start making changes to ease future transitions.

Airline 3.0.0 has several major breaking changes, this includes updating the minimum JDK version to 11, making some
dependencies optional and much improved JPMS compatibility.
2 changes: 1 addition & 1 deletion airline-backcompat-javaxinject/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
<parent>
<artifactId>airline-parent</artifactId>
<groupId>com.github.rvesse</groupId>
<version>2.10.0-SNAPSHOT</version>
<version>3.0.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>airline-backcompat-javaxinject</artifactId>
Expand Down
3 changes: 1 addition & 2 deletions airline-core/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>com.github.rvesse</groupId>
<artifactId>airline-parent</artifactId>
<version>2.10.0-SNAPSHOT</version>
<version>3.0.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>

Expand All @@ -17,7 +17,6 @@
<properties>
<license.header.path>${project.parent.basedir}</license.header.path>
<coveralls.skip>true</coveralls.skip>
<moditect.moduleName>com.github.rvesse.airline</moditect.moduleName>
</properties>

<dependencies>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@

import com.github.rvesse.airline.parser.resources.ClasspathLocator;
import com.github.rvesse.airline.parser.resources.FileLocator;
import com.github.rvesse.airline.parser.resources.ModulePathLocator;
import com.github.rvesse.airline.parser.resources.ResourceLocator;

@Retention(java.lang.annotation.RetentionPolicy.RUNTIME)
Expand Down Expand Up @@ -127,6 +128,7 @@
*/
Class<? extends ResourceLocator>[] sourceLocators() default {
ClasspathLocator.class,
ModulePathLocator.class,
FileLocator.class
};
}
Original file line number Diff line number Diff line change
Expand Up @@ -135,12 +135,9 @@ public ParserBuilder<C> withCompositionAnnotations(String... annotationClassName
* </p>
* <ul>
* <li>{@code com.github.rvesse.airline.annotations.AirlineModule}</li>
* <li>{@code javax.inject.Inject}</li>
* <li>{@code jakarta.inject.Inject}</li>
* <li>{@code com.google.inject.Inject}</li>
* </ul>
* <p>
* <strong>NB:</strong> Future releases will reduce the default set to just
* <strong>NB:</strong> As of {@code 3.0.0) the default set was reduced to just
* {@code com.github.rvesse.airline.annotations.AirlineModule} and require that users explicitly configure
* additional annotation classes as they see fit. If you are not currently using a dependency injection framework
* that requires some form of {@code Inject} annotation we would recommend that you transition to using
Expand All @@ -151,9 +148,7 @@ public ParserBuilder<C> withCompositionAnnotations(String... annotationClassName
* @since 2.9.0
*/
public ParserBuilder<C> withDefaultCompositionAnnotations() {
return withCompositionAnnotations(AirlineModule.class.getCanonicalName(), MetadataLoader.JAVAX_INJECT_INJECT,
MetadataLoader.JAKARTA_INJECT_INJECT,
MetadataLoader.COM_GOOGLE_INJECT_INJECT);
return withCompositionAnnotations(AirlineModule.class.getCanonicalName());
}

/**
Expand Down Expand Up @@ -574,15 +569,15 @@ public ParserBuilder<C> withFlagNegationPrefix(String prefix) {

/**
* Gets the parent CLI builder (if any)
*
*
* @return Parent CLI builder
* @throws IllegalStateException
* Thrown if there is no parent CLI builder
* @throws IllegalStateException Thrown if there is no parent CLI builder
*/
public CliBuilder<C> parent() {
if (this.cliBuilder == null)
if (this.cliBuilder == null) {
throw new IllegalStateException(
"This Parser Builder was not created via a CLI builder and so cannot call parent() to obtain a parent CLI builder");
}
return this.cliBuilder;
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,11 @@
*/
public class MetadataLoader {

/**
* Constant for the {@link AirlineModule} annotation class
*/
public static final String AIRLINE_MODULE = "com.github.rvesse.airline.annotations.AirlineModule";

/**
* Constant for the {@code javax.inject.Inject} annotation class
*/
Expand Down Expand Up @@ -574,14 +579,9 @@ public static SuggesterMetadata loadSuggester(Class<? extends Suggester> suggest
* migrated into the {@code jakarta} namespace. As of <strong>2.9.0</strong> Airline makes the choice of annotation
* fully configurable via the parser configuration. To avoid potential class loading issues these are specified as
* string class names with the metadata loader dynamically loading the relevant annotation classes if they are
* present on the runtime classpath. For backwards compatibility if this piece of configuration is not customised
* then we support the following annotations by default:
* </p>
* <ul>
* <li>{@value JAVAX_INJECT_INJECT}</li>
* <li>{@value JAKARTA_INJECT_INJECT}</li>
* <li>{@value COM_GOOGLE_INJECT_INJECT}</li>
* </ul>
* present on the runtime classpath. As of <strong>3.10.0</strong> we only look for our own {@link AirlineModule}
* annotation and any other composition annotation e.g. {@code jakarta.inject.Inject} <strong>MUST</strong> be
* explicitly configured.
*
* @param type Class
* @param parserConfig Parser Configuration
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
/**
* Copyright (C) 2010-16 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.github.rvesse.airline.parser.resources;

import java.io.IOException;
import java.io.InputStream;

public class ModulePathLocator implements ResourceLocator {
@Override
public InputStream open(String searchLocation, String filename) throws IOException {
if (searchLocation == null) {
return null;
}

// Strip off Classpath URI prefix if present
if (searchLocation.startsWith(ClasspathLocator.CLASSPATH_URI_PREFIX)) {
searchLocation = searchLocation.substring(ClasspathLocator.CLASSPATH_URI_PREFIX.length());
}

// Strip off leading / if present
// This is because when running on the Module Path the JVM translates the package name of the resource
// to its associated module by simply replacing / characters with . characters. Thus, if we have a leading
// slash we end up with an invalid module name like .foo.bar instead of foo.bar as was intended. And as a
// result we never correctly locate resources when running on the Module Path if we didn't do this.
if (searchLocation.startsWith("/")) {
searchLocation = searchLocation.length() > 1 ? searchLocation.substring(1) : "";
}

// Build the expected resource name
StringBuilder resourceName = new StringBuilder();
resourceName.append(searchLocation);
if (!searchLocation.endsWith("/") && searchLocation.length() > 0) {
resourceName.append("/");
}
resourceName.append(filename);

// Try to open the classpath resource
InputStream resourceStream = ClassLoader.getSystemResourceAsStream(resourceName.toString());
if (resourceStream != null) {
return resourceStream;
}

// If the search location is not a package then return that directly if
// it is a valid location
if (!searchLocation.endsWith("/")) {
InputStream locStream = ClassLoader.getSystemResourceAsStream(searchLocation);
if (locStream != null) {
return locStream;
}
}

return null;
}
}
Loading

0 comments on commit 08c30fa

Please sign in to comment.