From 5b8e700d90a34a255174bb9568566545397c4e00 Mon Sep 17 00:00:00 2001 From: Konrad Pabjan Date: Mon, 24 Aug 2020 17:15:33 +0200 Subject: [PATCH 1/5] V2 setup-java initial ADR --- docs/adrs/0000-v2-setup-java.md | 0 docs/adrs/README.md | 0 2 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/adrs/0000-v2-setup-java.md create mode 100644 docs/adrs/README.md diff --git a/docs/adrs/0000-v2-setup-java.md b/docs/adrs/0000-v2-setup-java.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/adrs/README.md b/docs/adrs/README.md new file mode 100644 index 000000000..e69de29bb From c873d688665e21a5723c227680121410be1481f8 Mon Sep 17 00:00:00 2001 From: Konrad Pabjan Date: Mon, 24 Aug 2020 17:18:42 +0200 Subject: [PATCH 2/5] Update ADR --- docs/adrs/0000-v2-setup-java.md | 74 +++++++++++++++++++++++++++++++++ docs/adrs/README.md | 19 +++++++++ 2 files changed, 93 insertions(+) diff --git a/docs/adrs/0000-v2-setup-java.md b/docs/adrs/0000-v2-setup-java.md index e69de29bb..7d2e58ab8 100644 --- a/docs/adrs/0000-v2-setup-java.md +++ b/docs/adrs/0000-v2-setup-java.md @@ -0,0 +1,74 @@ +# 0. V2 setup-java + +Date: 2020-08-24 + +Status: Proposed + +# Context + +- The `v1` version of `setup-java` downloads and installs Zulu builds of OpenJDK. There is a huge ask from customers to offer AdoptOpenJDK builds of OpenJDK: 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 align to to the same behavior. + +# Decision + +## New input + +A new input parameter (titled `distribution`) will be added to `setup-java` that will allow users to specify the distribution that they would like to download + +```yaml + with: + java-version: '11' + distribution: adoptopenjdk +``` + +## Default Behavior + +If no `distribution` parameter is provided, the default value will be `adoptopenjdk`. The action will first attempt to use pre-installed versions of AdoptOpenJDK builds of OpenJDK on GitHub hosted runners. If a specific version is not found, the action will then download and install the correct version. + +## 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 file under `src/distributions` that will contain the core setup logic for a specific distribution. + +```yaml + ∟ src/ + installer.ts # core installer logic + distributions/ + ∟ adoptOpenJDK.ts # adoptOpenJDK specific logic + ∟ zulu.ts # zulu specific logic + ∟ # future distributions will be added here +``` + +Each specific distribution can have minute differences or other information that should be documented. There will be a directory for distribution specific information under `docs/`. The main `README.md` will document all available distributions and link to specific documentation. The main `README.md` should not contain distribution specific information. + +```yaml + ∟ docs/ + distributions/ + ∟ adoptOpenJDK.md # adoptOpenJDK specific info + ∟ zulu.md # zulu specific info + ∟ # future distributions will be added here + +``` + +The contribution doc (`CONTRIBUTING.md`) will describe how a new distribution should be added and how everything should be structured. + +## 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 + +The main focus of the `v2` version of `setup-java` will be to add support for adoptOpenJDK 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 + +- 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 by switching from `Zulu` to `AdoptOpenJDK` as the default, certain existing workflows for users might break +- Higher maintenance and support burden moving forward \ No newline at end of file diff --git a/docs/adrs/README.md b/docs/adrs/README.md index e69de29bb..8c5234dec 100644 --- a/docs/adrs/README.md +++ b/docs/adrs/README.md @@ -0,0 +1,19 @@ +# ADRs + +ADR, short for "Architecture Decision Record" is a way of capturing important architectural decisions, along with their context and consequences. + +This folder includes ADRs for the Ecosystem Events team. ADRs are proposed in the form of a pull request, and they commonly follow this format: + +* **Title**: short present tense imperative phrase, less than 50 characters, like a git commit message. + +* **Status**: proposed, accepted, rejected, deprecated, superseded, etc. + +* **Context**: what is the issue that we're seeing that is motivating this decision or change. + +* **Decision**: what is the change that we're actually proposing or doing. + +* **Consequences**: what becomes easier or more difficult to do because of this change. + +--- + +- More information about ADRs can be found [here](https://github.com/joelparkerhenderson/architecture_decision_record). \ No newline at end of file From 5a4a419cc26a8f9f7829da635bf1799edcb66e56 Mon Sep 17 00:00:00 2001 From: Konrad Pabjan Date: Mon, 24 Aug 2020 17:44:17 +0200 Subject: [PATCH 3/5] Misc fixes --- docs/adrs/0000-v2-setup-java.md | 2 +- docs/adrs/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/adrs/0000-v2-setup-java.md b/docs/adrs/0000-v2-setup-java.md index 7d2e58ab8..461994dc9 100644 --- a/docs/adrs/0000-v2-setup-java.md +++ b/docs/adrs/0000-v2-setup-java.md @@ -10,7 +10,7 @@ Status: Proposed - 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 align to to the same behavior. +- GitHub Actions virtual environments install and default to AdoptOpenJDK builds of OpenJDK. `setup-java` should align to the same behavior. # Decision diff --git a/docs/adrs/README.md b/docs/adrs/README.md index 8c5234dec..f23a8f723 100644 --- a/docs/adrs/README.md +++ b/docs/adrs/README.md @@ -2,7 +2,7 @@ ADR, short for "Architecture Decision Record" is a way of capturing important architectural decisions, along with their context and consequences. -This folder includes ADRs for the Ecosystem Events team. ADRs are proposed in the form of a pull request, and they commonly follow this format: +This folder includes ADRs for the setup-java action. ADRs are proposed in the form of a pull request, and they commonly follow this format: * **Title**: short present tense imperative phrase, less than 50 characters, like a git commit message. From bfa3ae1e2b54ff133b0b5785f508cfa6bcdef823 Mon Sep 17 00:00:00 2001 From: konradpabjan Date: Tue, 1 Dec 2020 21:37:22 -0500 Subject: [PATCH 4/5] Clarifications around default behavior and new input --- docs/adrs/0000-v2-setup-java.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/adrs/0000-v2-setup-java.md b/docs/adrs/0000-v2-setup-java.md index 461994dc9..5c161dfed 100644 --- a/docs/adrs/0000-v2-setup-java.md +++ b/docs/adrs/0000-v2-setup-java.md @@ -10,13 +10,13 @@ Status: Proposed - 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 align to the same behavior. +- GitHub Actions virtual environments install and default to AdoptOpenJDK builds of OpenJDK. `setup-java` should give users an option to donwload and use other distributions that may not be be installed # Decision ## New input -A new input parameter (titled `distribution`) will be added to `setup-java` that will allow users to specify the distribution that they would like to download +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 ```yaml with: @@ -26,7 +26,9 @@ A new input parameter (titled `distribution`) will be added to `setup-java` that ## Default Behavior -If no `distribution` parameter is provided, the default value will be `adoptopenjdk`. The action will first attempt to use pre-installed versions of AdoptOpenJDK builds of OpenJDK on GitHub hosted runners. If a specific version is not found, the action will then download and install the correct version. +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 `@master` or `@main` as they will have no `distribution` specified in their YAML. 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. ## Extensibility & Documentation @@ -70,5 +72,5 @@ The `setup-java` action has some logic that creates a `settings.xml` file so tha - 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 by switching from `Zulu` to `AdoptOpenJDK` as the default, certain existing workflows for users might break +- 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 \ No newline at end of file From 4d60e847a97bfbe867d1b6fa17932b40974d78ad Mon Sep 17 00:00:00 2001 From: konradpabjan Date: Mon, 8 Mar 2021 12:34:22 -0500 Subject: [PATCH 5/5] PR feedback --- docs/adrs/0000-v2-setup-java.md | 27 ++++++++------------------- 1 file changed, 8 insertions(+), 19 deletions(-) diff --git a/docs/adrs/0000-v2-setup-java.md b/docs/adrs/0000-v2-setup-java.md index 5c161dfed..2d0c170d3 100644 --- a/docs/adrs/0000-v2-setup-java.md +++ b/docs/adrs/0000-v2-setup-java.md @@ -6,11 +6,11 @@ Status: Proposed # Context -- The `v1` version of `setup-java` downloads and installs Zulu builds of OpenJDK. There is a huge ask from customers to offer AdoptOpenJDK 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 - 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 donwload and use other distributions that may not be be installed +- 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 @@ -21,41 +21,30 @@ A new required input parameter (titled `distribution`) will be added to `setup-j ```yaml with: java-version: '11' - distribution: adoptopenjdk + distribution: adoptium ``` ## 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 `@master` or `@main` as they will have no `distribution` specified in their YAML. 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 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. ## 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 file 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/ installer.ts # core installer logic distributions/ - ∟ adoptOpenJDK.ts # adoptOpenJDK specific logic - ∟ zulu.ts # zulu specific logic + ∟ adoptium/ # adoptium (formerly AdoptOpenJDK) specific logic + ∟ zulu/ # zulu specific logic ∟ # future distributions will be added here ``` -Each specific distribution can have minute differences or other information that should be documented. There will be a directory for distribution specific information under `docs/`. The main `README.md` will document all available distributions and link to specific documentation. The main `README.md` should not contain distribution specific information. - -```yaml - ∟ docs/ - distributions/ - ∟ adoptOpenJDK.md # adoptOpenJDK specific info - ∟ zulu.md # zulu specific info - ∟ # future distributions will be added here - -``` - The contribution doc (`CONTRIBUTING.md`) will describe how a new distribution should be added and how everything should be structured. ## v2-preview @@ -64,7 +53,7 @@ There will be a `v2-preview` branch that will be created for development and tes ## Goals & Anti-Goals -The main focus of the `v2` version of `setup-java` will be to add support for adoptOpenJDK 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 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`.