Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fixes from VS Code MD Linter #416

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,9 +68,9 @@ members of the project's leadership.
## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
available at [https://www.contributor-covenant.org/version/1/4/code-of-conduct.html](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html)

[homepage]: https://www.contributor-covenant.org

For answers to common questions about this code of conduct, see
https://www.contributor-covenant.org/faq
[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq)
55 changes: 34 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
[![Main workflow](https://github.com/actions/setup-java/actions/workflows/workflow.yml/badge.svg)](https://github.com/actions/setup-java/actions/workflows/workflow.yml)

The `setup-java` action provides the following functionality for GitHub Actions runners:

- Downloading and setting up a requested version of Java. See [Usage](#Usage) for a list of supported distributions
- Extracting and caching custom version of Java from a local file
- Configuring runner for publishing using Apache Maven
Expand All @@ -18,49 +19,51 @@ This action allows you to work with Java and Scala projects.

## V2 vs V1

- V2 supports custom distributions and provides support for Azul Zulu OpenJDK, Eclipse Temurin and AdoptOpenJDK out of the box. V1 supports only Azul Zulu OpenJDK
- V2 supports custom distributions and provides support for Azul Zulu OpenJDK, Eclipse Temurin and AdoptOpenJDK out of the box. V1 supports only Azul Zulu OpenJDK
- V2 requires you to specify distribution along with the version. V1 defaults to Azul Zulu OpenJDK, only version input is required. Follow [the migration guide](docs/switching-to-v2.md) to switch from V1 to V2

## Usage

- `java-version`: _(required)_ The Java version to set up. Takes a whole or [semver](#supported-version-syntax) Java version.
- `distribution`: _(required)_ Java [distribution](#supported-distributions).
- `java-version`: _(required)_ The Java version to set up. Takes a whole or [semver](#supported-version-syntax) Java version.

- `distribution`: _(required)_ Java [distribution](#supported-distributions).

- `java-package`: The packaging variant of the choosen distribution. Possible values: `jdk`, `jre`, `jdk+fx`, `jre+fx`. Default value: `jdk`.
- `java-package`: The packaging variant of the chosen distribution. Possible values: `jdk`, `jre`, `jdk+fx`, `jre+fx`. Default value: `jdk`.

- `architecture`: The target architecture of the package. Possible values: `x86`, `x64`, `armv7`, `aarch64`, `ppc64le`. Default value: `x64`.
- `architecture`: The target architecture of the package. Possible values: `x86`, `x64`, `armv7`, `aarch64`, `ppc64le`. Default value: `x64`.

- `jdkFile`: If a use-case requires a custom distribution setup-java uses the compressed JDK from the location pointed by this input and will take care of the installation and caching on the VM.
- `jdkFile`: If a use-case requires a custom distribution setup-java uses the compressed JDK from the location pointed by this input and will take care of the installation and caching on the VM.

- `check-latest`: Setting this option makes the action to check for the latest available version for the version spec.
- `check-latest`: Setting this option makes the action to check for the latest available version for the version spec.

- `cache`: Quick [setup caching](#caching-packages-dependencies) for the dependencies managed through one of the predifined package managers. It can be one of "maven", "gradle" or "sbt".
- `cache`: Quick [setup caching](#caching-packages-dependencies) for the dependencies managed through one of the predefined package managers. It can be one of "maven", "gradle" or "sbt".

#### Maven options
The action has a bunch of inputs to generate maven's [settings.xml](https://maven.apache.org/settings.html) on the fly and pass the values to Apache Maven GPG Plugin as well as Apache Maven Toolchains. See [advanced usage](docs/advanced-usage.md) for more.
### Maven options

- `overwrite-settings`: By default action overwrites the settings.xml. In order to skip generation of file if it exists set this to `false`.
The action has a bunch of inputs to generate maven's [settings.xml](https://maven.apache.org/settings.html) on the fly and pass the values to Apache Maven GPG Plugin as well as Apache Maven Toolchains. See [advanced usage](docs/advanced-usage.md) for more.

- `server-id`: ID of the distributionManagement repository in the pom.xml file. Default is `github`.
- `overwrite-settings`: By default action overwrites the settings.xml. In order to skip generation of file if it exists set this to `false`.

- `server-username`: Environment variable name for the username for authentication to the Apache Maven repository. Default is GITHUB_ACTOR.
- `server-id`: ID of the distributionManagement repository in the pom.xml file. Default is `github`.

- `server-password`: Environment variable name for password or token for authentication to the Apache Maven repository. Default is GITHUB_TOKEN.
- `server-username`: Environment variable name for the username for authentication to the Apache Maven repository. Default is GITHUB_ACTOR.

- `settings-path`: Maven related setting to point to the diractory where the settings.xml file will be written. Default is ~/.m2.
- `server-password`: Environment variable name for password or token for authentication to the Apache Maven repository. Default is GITHUB_TOKEN.

- `gpg-private-key`: GPG private key to import. Default is empty string.'
- `settings-path`: Maven related setting to point to the directory where the settings.xml file will be written. Default is ~/.m2.

- `gpg-passphrase`: description: 'Environment variable name for the GPG private key passphrase. Default is GPG_PASSPHRASE.
- `gpg-private-key`: GPG private key to import. Default is empty string.'

- `mvn-toolchain-id`: Name of Maven Toolchain ID if the default name of `${distribution}_${java-version}` is not wanted.
- `gpg-passphrase`: description: 'Environment variable name for the GPG private key passphrase. Default is GPG_PASSPHRASE.

- `mvn-toolchain-vendor`: Name of Maven Toolchain Vendor if the default name of `${distribution}` is not wanted.
- `mvn-toolchain-id`: Name of Maven Toolchain ID if the default name of `${distribution}_${java-version}` is not wanted.

- `mvn-toolchain-vendor`: Name of Maven Toolchain Vendor if the default name of `${distribution}` is not wanted.

### Basic Configuration

#### Eclipse Temurin

```yaml
steps:
- uses: actions/checkout@v3
Expand All @@ -72,6 +75,7 @@ steps:
```

#### Azul Zulu OpenJDK

```yaml
steps:
- uses: actions/checkout@v3
Expand All @@ -83,12 +87,15 @@ steps:
```

#### Supported version syntax

The `java-version` input supports an exact version or a version range using [SemVer](https://semver.org/) notation:

- major versions: `8`, `11`, `16`, `17`
- more specific versions: `17.0`, `11.0`, `11.0.4`, `8.0.232`, `8.0.282+8`
- early access (EA) versions: `15-ea`, `15.0.0-ea`, `15.0.0-ea.2`, `15.0.0+2-ea`

#### Supported distributions

Currently, the following distributions are supported:
| Keyword | Distribution | Official site | License
|-|-|-|-|
Expand All @@ -108,7 +115,9 @@ Currently, the following distributions are supported:
**NOTE:** For Azul Zulu OpenJDK architectures x64 and arm64 are mapped to x86 / arm with proper hw_bitness.

### Caching packages dependencies

The action has a built-in functionality for caching and restoring dependencies. It uses [actions/cache](https://github.com/actions/cache) under hood for caching dependencies but requires less configuration settings. Supported package managers are gradle, maven and sbt. The format of the used cache key is `setup-java-${{ platform }}-${{ packageManager }}-${{ fileHash }}`, where the hash is based on the following files:

- gradle: `**/*.gradle*`, `**/gradle-wrapper.properties`, `buildSrc/**/Versions.kt`, `buildSrc/**/Dependencies.kt`, and `gradle/*.versions.toml`
- maven: `**/pom.xml`
- sbt: all sbt build definition files `**/*.sbt`, `**/project/build.properties`, `**/project/**.{scala,sbt}`
Expand All @@ -118,6 +127,7 @@ The workflow output `cache-hit` is set to indicate if an exact match was found f
The cache input is optional, and caching is turned off by default.

#### Caching gradle dependencies

```yaml
steps:
- uses: actions/checkout@v3
Expand All @@ -130,6 +140,7 @@ steps:
```

#### Caching maven dependencies

```yaml
steps:
- uses: actions/checkout@v3
Expand All @@ -143,6 +154,7 @@ steps:
```

#### Caching sbt dependencies

```yaml
steps:
- uses: actions/checkout@v3
Expand All @@ -163,7 +175,6 @@ If `check-latest` is set to `true`, the action first checks if the cached versio

For Java distributions that are not cached on Hosted images, `check-latest` always behaves as `true` and downloads Java on-flight. Check out [Hosted Tool Cache](docs/advanced-usage.md#Hosted-Tool-Cache) for more details about pre-cached Java versions.


```yaml
steps:
- uses: actions/checkout@v3
Expand All @@ -176,6 +187,7 @@ steps:
```

### Testing against different Java versions

```yaml
jobs:
build:
Expand Down Expand Up @@ -210,6 +222,7 @@ All versions are added to the PATH. The last version will be used and available
```

### Using Maven Toolchains

In the example above multiple JDKs are installed for the same job. The result after the last JDK is installed is a Maven Toolchains declaration containing references to all three JDKs. The values for `id`, `version`, and `vendor` of the individual Toolchain entries are the given input values for `distribution` and `java-version` (`vendor` being the combination of `${distribution}_${java-version}`) by default.

### Advanced Configuration
Expand Down
24 changes: 12 additions & 12 deletions docs/adrs/0000-v2-setup-java.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,17 @@ Date: 2020-08-24

Status: Proposed

# Context
## Context

- The `v1` version of `setup-java` downloads and installs Zulu builds of OpenJDK. There is a huge ask from customers to offer AdoptOpenJDK/Adoptium builds of OpenJDK: https://github.com/actions/setup-java/issues/13
- The `v1` version of `setup-java` downloads and installs Zulu builds of OpenJDK. There is a huge ask from customers to offer AdoptOpenJDK/Adoptium builds of OpenJDK: [https://github.com/actions/setup-java/issues/13](https://github.com/actions/setup-java/issues/13)

- Zulu and AdoptOpenJDK aren't the only distributions of Java though. Other providers include Oracle OpenJDK or Amazon Corretto and ideally it would be nice to support downloading Java from all providers.

- GitHub Actions virtual environments install and default to AdoptOpenJDK builds of OpenJDK. `setup-java` should give users an option to download and use other distributions that may not be be installed

# Decision
## Decision

## New input
### New input

A new required input parameter (titled `distribution`) will be added to `setup-java` that will allow users to specify the distribution that they would like to download

Expand All @@ -24,17 +24,17 @@ A new required input parameter (titled `distribution`) will be added to `setup-j
distribution: adoptium
```

## Default Behavior
### Default Behavior

There will be no default distribution that we pick for the user. Users will have to specify a distribution in their YAML or else the action will fail.

Requiring a default version will break users that are pinned to `@main` as they will have no `distribution` specified in their YAML. Telemetry indicates that only a small percentage of users would be effected though. Users pinned to `v1` will be uneffected. This change is meant to not be backward compatible and it is acceptable to change the default behavior because a new major version will be released alongside these changes.
Requiring a default version will break users that are pinned to `@main` as they will have no `distribution` specified in their YAML. Telemetry indicates that only a small percentage of users would be effected though. Users pinned to `v1` will be unaffected. This change is meant to not be backward compatible and it is acceptable to change the default behavior because a new major version will be released alongside these changes.

## Extensibility & Documentation
### Extensibility & Documentation

`setup-java` should be structured in such a way that will allow the open source community to easily add support for extra distributions.

Existing code will be restructured so that distribution specific code will be easily separated. Currently the core download logic is in a single file, `installer.ts`. This file will be split up and abstracted out so that there will be no vendor specified logic. Each distribution will have it's own files under `src/distributions` that will contain the core setup logic for a specific distribution.
Existing code will be restructured so that distribution specific code will be easily separated. Currently the core download logic is in a single file, `installer.ts`. This file will be split up and abstracted out so that there will be no vendor specified logic. Each distribution will have it's own files under `src/distributions` that will contain the core setup logic for a specific distribution.

```yaml
∟ src/
Expand All @@ -47,19 +47,19 @@ Existing code will be restructured so that distribution specific code will be ea

The contribution doc (`CONTRIBUTING.md`) will describe how a new distribution should be added and how everything should be structured.

## v2-preview
### v2-preview

There will be a `v2-preview` branch that will be created for development and testing. Any changes will first be merged into `v2-preview` branch. After a period of testing & verification, the `v2-preview` branch will be merged into the `main` branch and a `v2` tag will be created. Any [GitHub public documentation](https://docs.github.com/en/actions/language-and-framework-guides/github-actions-for-java) and [starter workflows](https://github.com/actions/starter-workflows) that mention `setup-java` will then be updated to use `v2` instead of `v1`.

## Goals & Anti-Goals
### Goals & Anti-Goals

The main focus of the `v2` version of `setup-java` will be to add support for adoptium builds of openJDK in addition to Zulu builds of openJDK. In addition, extensibility will be a priority so that other distributions can be added in the future.

The `setup-java` action has some logic that creates a `settings.xml` file so that it is easier to publish packages. Any improvements or modifications to this logic or anything Gradle/Maven specific will be avoided during the development of the `v2-preview`.

# Consequences
## Consequences

- Users will have more flexibility and the freedom to choose a specific distribution that they would like (AdoptOpenJDK builds of OpenJDK in addition or Zulu builds of OpenJDK)
- `setup-java` will be structured in such a way that will allow for more distributions to be easily added in the future
- A large subset of users pin to `@main` or `@master` instead of to a specific version (`v1`). By introducing a breaking change that now requires a distribution to be specified, many users will have their workflows fail until they go and update their yaml
- Higher maintenance and support burden moving forward
- Higher maintenance and support burden moving forward
2 changes: 1 addition & 1 deletion docs/adrs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,4 +16,4 @@ This folder includes ADRs for the setup-java action. ADRs are proposed in the fo

---

- More information about ADRs can be found [here](https://github.com/joelparkerhenderson/architecture_decision_record).
* More information about ADRs can be found [here](https://github.com/joelparkerhenderson/architecture_decision_record).
Loading