Skip to content

Commit c873d68

Browse files
konradpabjankonradpabjan
committed
Update ADR
1 parent 5b8e700 commit c873d68

2 files changed

Lines changed: 93 additions & 0 deletions

File tree

‎docs/adrs/0000-v2-setup-java.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# 0. V2 setup-java
2+
3+
Date: 2020-08-24
4+
5+
Status: Proposed
6+
7+
# Context
8+
9+
- 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
10+
11+
- 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.
12+
13+
- GitHub Actions virtual environments install and default to AdoptOpenJDK builds of OpenJDK. `setup-java` should align to to the same behavior.
14+
15+
# Decision
16+
17+
## New input
18+
19+
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
20+
21+
```yaml
22+
with:
23+
java-version: '11'
24+
distribution: adoptopenjdk
25+
```
26+
27+
## Default Behavior
28+
29+
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.
30+
31+
## Extensibility & Documentation
32+
33+
`setup-java` should be structured in such a way that will allow the open source community to easily add support for extra distributions.
34+
35+
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.
36+
37+
```yaml
38+
∟ src/
39+
installer.ts # core installer logic
40+
distributions/
41+
∟ adoptOpenJDK.ts # adoptOpenJDK specific logic
42+
∟ zulu.ts # zulu specific logic
43+
∟ # future distributions will be added here
44+
```
45+
46+
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.
47+
48+
```yaml
49+
∟ docs/
50+
distributions/
51+
∟ adoptOpenJDK.md # adoptOpenJDK specific info
52+
∟ zulu.md # zulu specific info
53+
∟ # future distributions will be added here
54+
55+
```
56+
57+
The contribution doc (`CONTRIBUTING.md`) will describe how a new distribution should be added and how everything should be structured.
58+
59+
## v2-preview
60+
61+
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`.
62+
63+
## Goals & Anti-Goals
64+
65+
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.
66+
67+
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`.
68+
69+
# Consequences
70+
71+
- 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)
72+
- `setup-java` will be structured in such a way that will allow for more distributions to be easily added in the future
73+
- 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
74+
- Higher maintenance and support burden moving forward

‎docs/adrs/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# ADRs
2+
3+
ADR, short for "Architecture Decision Record" is a way of capturing important architectural decisions, along with their context and consequences.
4+
5+
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:
6+
7+
* **Title**: short present tense imperative phrase, less than 50 characters, like a git commit message.
8+
9+
* **Status**: proposed, accepted, rejected, deprecated, superseded, etc.
10+
11+
* **Context**: what is the issue that we're seeing that is motivating this decision or change.
12+
13+
* **Decision**: what is the change that we're actually proposing or doing.
14+
15+
* **Consequences**: what becomes easier or more difficult to do because of this change.
16+
17+
---
18+
19+
- More information about ADRs can be found [here](https://github.com/joelparkerhenderson/architecture_decision_record).

0 commit comments

Comments
 (0)