Update contributing + some minor fixes

.github/PULL_REQUEST_TEMPLATE.md

@@ -3,8 +3,9 @@ Thank you for your pull request. Please provide a description above and review
 the requirements below.
 -->
 
-##### Checklist
+# Checklist
 <!-- Remove items that do not apply. For completed items, change [ ] to [x]. -->
 
-- [ ] `mvn clean package` build and test completes
-- [ ] documentation is changed or added
+- [ ] You added tests to cover the change
+- [ ] `mvn clean install` build and test completes
+- [ ] You changed or added to the documentation

.github/workflows/build.yml

@@ -17,7 +17,7 @@ jobs:
     - uses: actions/checkout@v1
 
     - name: ktlint
-      run: curl -sSLO https://github.com/pinterest/ktlint/releases/download/0.35.0/ktlint && chmod a+x ktlint && ./ktlint
+      run: curl -sSLO https://github.com/pinterest/ktlint/releases/download/0.36.0/ktlint && chmod a+x ktlint && ./ktlint
 
     - name: Build app
       run: ./mvnw --batch-mode clean install jacoco:report jacoco:report-aggregate
@@ -30,7 +30,7 @@ jobs:
       run: |
         cd adoptopenjdk-api-v3-frontend
         unzip target/adoptopenjdk-api-v3-frontend-*-runner.jar META-INF/quarkus-generated-openapi-doc.YAML
-        ../mvnw --batch-mode org.openapitools:openapi-generator-maven-plugin:4.2.2:generate \
+        ../mvnw --batch-mode org.openapitools:openapi-generator-maven-plugin:4.3.0:generate \
                 -Dopenapi.generator.maven.plugin.inputSpec=META-INF/quarkus-generated-openapi-doc.YAML
 
     - name: Zip Javascript client

CONTRIBUTING.md

@@ -3,31 +3,99 @@
 ## Overview
 
 The AdoptOpenJDK API V3 is a Kotlin application (fronted by Swagger and OpenAPI) which makes 
-calls via the GitHub API inb order to retrieve AdoptOpenJDK binaries and metadata.
+calls via the GitHub API in order to retrieve AdoptOpenJDK binaries and metadata.
 
 Since the GitHub API is rate limited we use MongoDB as a caching mechanism.
 
+## Source code management and branching
+
+We treat the AdoptOpenJDK org repository as the canonical repository for deploying the API from. 
+We use the `staging` branch to trial any changes in a Production like environment and then 
+eventually merge into `master` for a real Production deployment.
+
+**NOTE** Please ensure for any significant change that you Pull Request to the `staging` branch 
+
 ## Build
 
 ### Pre-Requisites
 
-Java 11 is required to build.
+Java 11 is a requirement to build the project.
 
 ### Build Tool
 
-We use a Maven Wrapper (mvnw) to ensure that there's a consistent repeatable build.
+We use a Maven Wrapper (mvnw) to ensure that there's a consistent, repeatable build. The 
+[POM File](./pom.xml) is the place to start.
+
+**NOTE:** We use a multi-module project structure. The root level POM contains a majority 
+of the configuration that the children inherit from. 
 
-### Build
+### Build Command
+
+To perform a full build and test you run the following:
 
 `./mvnw clean install`
 
-## Usage
+If you wish to view all of the Maven reporting about the project you run the following:
+
+`./mvnw clean install site`
+
+## Testing
+
+**WARN** This API is critical to the success of AdoptOpenJDK therefore it is 
+essential that tests are provided for all new functionality. 
+
+### Code Coverage
+
+TBD
+
+## Continuous Integration (CI)
+
+### Pull Requests
+
+There is a [GitHub Action](.github\workflows\build.yml) file which the CI system 
+in GitHub uses to build and test a Pull Request.
+
+**NOTE:** Please update the dependencies in this file if you have changed the versions of:
+
+* The JDK
+* ktlint
+* openapi-generator-maven-plugin  
+
+## API Definition and Usage
+
+We use Swagger to document the API. The Swagger documentation can be viewed at: [swagger-ui](https://api.adoptopenjdk.net/swagger-ui). 
+The Open API definition for this can be viewed at [openapi](https://api.adoptopenjdk.net/openapi).
+
+## Deployment / Continuous Deployment (CD)
+
+You can choose to deploy this API where you wish, for AdoptOpenJDK we use Continuous Deployment.
+
+### AdoptOpenJDK
+
+For AdoptOpenJDK, this API deploys to Red Hat OpenShift and is front ended by Cloud Flare as a CDN
+
+The Jenkins [AdoptOpenJDK CI Server](https://ci.adoptopenjdk.net) will automatically 
+deploy Pull Requests to OpenShift to Staging (the `staging` branch) or Production (the `master` branch.)
+
+## Code Architecture and Code
+
+The AdoptOpenJDK API V3 is a Kotlin application (fronted by Swagger and OpenAPI) which makes 
+calls via the GitHub API in order to retrieve AdoptOpenJDK binaries and metadata.
+
+Since the GitHub API is rate limited we use MongoDB as a caching mechanism.
+
+See [./docs/STRUCTURE.md](Code Structure) doc for more details.
+
+## Common Tasks
+
+In this section we list some common tasks and where to start.
 
-The api is documented via swagger.  The swagger documentation can be viewed at: [swagger-ui](https://api.adoptopenjdk.net/swagger-ui). 
-The open api definition for this can be viewed at [openapi](https://api.adoptopenjdk.net/openapi).
+### I want support a new version string
 
-## Deployment
+If you need to add/edit/remove a supported version string then you need to update the [VersionParser](adoptopenjdk-api-v3-models/src/main/kotlin/net/adoptopenjdk/api/v3/parser/VersionParser.kt) and 
+its corresponding [VersionParserTest](adoptopenjdk-api-v3-models/src/test/kotlin/net/adoptopenjdk/api/VersionParserTest.kt).
 
-The API is deployed to Red Hat OpenShift.
+### I want to add a new variant such as OpenJDK's project amber or 
 
-The API is CDN fronted by Cloud Flare
+You'll need to start at the [Platforms JSON](adoptopenjdk-api-v3-frontend/src/main/resources/JSON/platforms.json) and 
+[Variants JSON](adoptopenjdk-api-v3-frontend/src/main/resources/JSON/variants.json).

adoptopenjdk-api-v3-models/pom.xml

@@ -29,8 +29,6 @@
             <groupId>org.apache.maven</groupId>
             <artifactId>maven-artifact</artifactId>
         </dependency>
-
-
         <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter-api</artifactId>
@@ -46,12 +44,10 @@
     <build>
         <sourceDirectory>src/main/kotlin</sourceDirectory>
         <testSourceDirectory>src/test/kotlin</testSourceDirectory>
-
         <plugins>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-surefire-plugin</artifactId>
-                <version>2.22.2</version>
             </plugin>
         </plugins>
     </build>

adoptopenjdk-api-v3-updater/pom.xml

@@ -21,10 +21,6 @@
             <groupId>org.apache.httpcomponents</groupId>
             <artifactId>httpasyncclient</artifactId>
         </dependency>
-        <!--
-            Should be set by httpasyncclient however bumping past 4.4.12 due to issues caused by:
-            https://issues.apache.org/jira/browse/HTTPCORE-583
-        -->
         <dependency>
             <groupId>org.apache.httpcomponents</groupId>
             <artifactId>httpcore</artifactId>

gradle/wrapper/gradle-wrapper.properties

@@ -2,5 +2,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-#distributionUrl=https\://services.gradle.org/distributions/gradle-5.5.1-bin.zip
 distributionUrl=https\://services.gradle.org/distributions/gradle-5.6.4-bin.zip

pom.xml

@@ -340,6 +340,7 @@
                     <artifactId>maven-filtering</artifactId>
                     <version>3.1.1</version>
                 </plugin>
+                <!-- Moving to 3.0.0-M1 created a multi-module packaging issue -->
                 <plugin>
                     <groupId>org.apache.maven.plugins</groupId>
                     <artifactId>maven-install-plugin</artifactId>
@@ -690,7 +691,6 @@
                 <reportSets>
                     <reportSet>
                         <reports>
-                            <!-- select non-aggregate reports -->
                             <report>report</report>
                             <report>report-aggregate</report>
                         </reports>