From e8d60f89ac88690c023cb04918544633b1709fee Mon Sep 17 00:00:00 2001 From: Stewart X Addison <6487691+sxa@users.noreply.github.com> Date: Sun, 5 Nov 2023 21:02:36 +0000 Subject: [PATCH] docs: Update CONTRIBUTING.md which is a bit stale (#3219) * docs: Update CONTRIBUTING.md which is a bit stale Signed-off-by: Stewart X Addison * Update CONTRIBUTING.md Co-authored-by: Adam Farley --------- Signed-off-by: Stewart X Addison Co-authored-by: Adam Farley --- CONTRIBUTING.md | 41 ++++++++++++++++++++++++++++------------- 1 file changed, 28 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 199faecf9b..edd2bab540 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,21 +37,23 @@ Contact the Eclipse Foundation Webdev team via webdev@eclipse-foundation.org. ## Mission Statement To provide **secure**, **consistent**, **repeatable**, and **auditable** -infrastructure for the AdoptOpenJDK farm. +infrastructure for the Adoptium farm. ## Infrastructure As Code The infrastructure project contains: -1. The [Ansible Playbooks](ansible/playbooks) for bootstrapping the build and test hosts (including a way to test Ansible). -1. The [Vagrant and QEMU test scripts](ansible/pbTestScripts) for running our full suite of playbook tests. -1. The [Dockerfiles](ansible/) are used for: +1. The [Ansible Playbooks](ansible/playbooks) for bootstrapping the build and test hosts (including a way to test Ansible). There are separate playbooks for Windows, UNIX (Including Linux), and AIX plus some others for individual machines. +1. The [Vagrant and QEMU test scripts](ansible/pbTestScripts) for running our full suite of playbook tests across different OS/distribution combinations. For any non-trivial plasybook change it is expected that they should be run against the vagrant tests at a minimum and not cause problems. +1. The [Dockerfiles](ansible/docker) are used to produce images to run builds on. They run the playbooks to create a docker image that is suitable for running the adoptium build and test suites: 1. Running a subset of tests as GitHub actions (on a PR). 1. Providing the base images for running builds on Docker containers in our build farm. -1. The overriding [Documentation](docs) for the build farm. +1. The top level [Jenkinsfile] is triggered by the [jenkins job](https://ci.adoptium.net/job/centos7_docker_image_updater) that rebuilds the Linux build containers when playbook changes are made and pushes them to dockerhub. +1. In addition the [Dockerfiles in the DockerStatic role](ansible/playbooks/AdoptOpenJDK_Unix_Playbook/roles/DockerStatic/Dockerfiles) are standalone source files for containers that have a minimal set of requirements to run our test jobs in. They do not use the playbooks. +1. The overriding [Documentation](docs) for the build farm. The [FAQ](FAQ.md) also contains specific things that it is useful to know about the project and its operations, so if you have any questions it is a good place to check. 1. Configuration files for linters etc in the root folder. -## Submitting a contribution to AdoptOpenJDK/infrastructure +## Submitting a contribution to Adoptium/infrastructure You can propose contributions by sending pull requests (PRs) through GitHub. Following these guidelines will help us merge your pull requests smoothly: @@ -100,7 +102,7 @@ ensure the 32bit and 64bit versions are both installed into C:\openjdk Fixes: #1234 ``` -All changes should be made to a personal fork of AdoptOpenJDK/infrastructure for making changes. +All changes should be made to a personal fork of adoptium/infrastructure for making changes so the following standard GitHub workflow should be used. 1. Fork this repository 1. Create a branch off your fork @@ -108,12 +110,25 @@ All changes should be made to a personal fork of AdoptOpenJDK/infrastructure for 1. Test it (see below) 1. Submit a Pull Request -Only reviewers in the -[infrastructure](https://github.com/orgs/AdoptOpenJDK/teams/infrastructure) -team have permission to merge requests for this repo, so if you feel your PR +If you are new to git and GitHub and the above makes no sense to you then [this primer may be useful](http://sxatech.blogspot.com/2021/12/git.html). + +Only [committers to the adoptium.temurin project](https://projects.eclipse.org/projects/adoptium.temurin/who) +have permission to merge requests for this repo, so if you feel your PR is not getting enough attention, let one the team know via the `#infrastructure` slack channel +If you are adding any downloads into the playbooks, please ensure this is +done over https or another secure channel, and that a GPG checksum of the +file is verified if possible, and if not a SHA checksum is performed after +the download has been performed. There are various examples of this in the +playbooks: + +- [gmake role](https://github.com/adoptium/infrastructure/blob/master/ansible/playbooks/AdoptOpenJDK_Unix_Playbook/roles/gmake/tasks/main.yml) (GPG verification using [package_signature_verification.sh](https://github.com/adoptium/infrastructure/blob/master/ansible/playbooks/Supporting_Scripts/package_signature_verification.sh) +- [NVidia_Cuda_Toolkit role](https://github.com/adoptium/infrastructure/blob/master/ansible/playbooks/AdoptOpenJDK_Unix_Playbook/roles/NVidia_Cuda_Toolkit/tasks/main.yml) which performs a SHA256 check of the download +- The [gcc_11 role](https://github.com/adoptium/infrastructure/blob/master/ansible/playbooks/AdoptOpenJDK_Unix_Playbook/roles/gcc_11/tasks/main.yml) is an example of SHA checks when there are multiple downloads for each architecture. It uses checksums stored in a [separate variables file](https://github.com/adoptium/infrastructure/blob/master/ansible/playbooks/AdoptOpenJDK_Unix_Playbook/roles/gcc_11/vars/main.yml) + +Where possible, if you are modifying a playbook to add something new, please also add information saying what it is needed for (it may be useful to link back to a related PR or issue) + ## Using Vagrant to test your Ansible scripts To test changes made to our ansible playbooks, we have the following test jobs which you can use to validate your pull request: @@ -138,10 +153,10 @@ in the [ansible directory README](ansible/README.md#running-via-vagrant-and-virtualbox) We expect developers to test their Ansible changes in a test environment -whether through vagrant or elsewhere in order to ensure there are as few -problems as possible. +whether through vagrant, docker or elsewhere in order to ensure there are as +few problems as possible when the PR is ready for review. -[Ansible Scripts Guide](ansible/README.md) +[Ansible Scripts Usage Guide](ansible/README.md) ## Commit messages