Skip to content

Latest commit

 

History

History
182 lines (130 loc) · 9.39 KB

CONTRIBUTING.md

File metadata and controls

182 lines (130 loc) · 9.39 KB
Raw

Contributing to infrastructure

Thanks for your interest in this project.

Project description

This repo contains all information about machine maintenance and configurations

Developer resources

The project maintains the following source code repositories

Eclipse Contributor Agreement

Before your contribution can be accepted by the project team contributors must electronically sign the Eclipse Contributor Agreement (ECA).

Commits that are provided by non-committers must have a Signed-off-by field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. The non-committer must additionally have an Eclipse Foundation account and must have a signed Eclipse Contributor Agreement (ECA) on file.

For more information, please see the Eclipse Committer Handbook: https://www.eclipse.org/projects/handbook/#resources-commit

Contact

Contact the Eclipse Foundation Webdev team via webdev@eclipse-foundation.org.

Mission Statement

To provide secure, consistent, repeatable, and auditable infrastructure for the Adoptium farm.

Infrastructure As Code

The infrastructure project contains:

  1. The 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.
  2. The Vagrant and QEMU test scripts 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.
  3. The Dockerfiles 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).
    2. Providing the base images for running builds on Docker containers in our build farm.
  4. The top level [Jenkinsfile] is triggered by the jenkins job that rebuilds the Linux build containers when playbook changes are made and pushes them to dockerhub.
  5. In addition the Dockerfiles in the DockerStatic role 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.
  6. The overriding Documentation for the build farm. The FAQ 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.
  7. Configuration files for linters etc in the root folder.

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:

  1. Your pull request is an opportunity to explain both what changes you'd like pulled in, but also why you'd like them added. Providing clarity on why you want changes makes it easier to accept, and provides valuable context to review. If there is a link to an issue in the PR that contains these details that is sufficient.

  2. Follow the commit guidelines found below.

  3. We encourage you to open a pull request early, and mark it as "Work In Progress", by prefixing the PR title with "WIP". This allows feedback to start early, and helps create a better end product. Committers will wait until after you've removed the WIP prefix to merge your changes.

Commit Guidelines

The first line describes the change made. It is written in the imperative mood, and should say what happens when the patch is applied. Keep it short and simple. The first line should be less than 70 characters, where reasonable, and should be written in sentence case preferably not ending in a period. Leave a blank line between the first line and the message body.

The body should be wrapped at 72 characters, where reasonable.

Include as much information in your commit as possible. You may want to include designs and rationale, examples and code, or issues and next steps. Prefer copying resources into the body of the commit over providing external links. Structure large commit messages with headers, references etc. Remember, however, that the commit message is always going to be rendered in plain text.

When a commit has related issues or commits, explain the relation in the message body. When appropriate, use the keywords described in the following help article to automatically close issues. Closing Issues Using Keywords For example:

Install OpenSSL in windows playbook

OpenSSL is required to compile java on windows, so the OpenSSL role will
ensure the 32bit and 64bit versions are both installed into C:\openjdk

Fixes: #1234

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
  2. Create a branch off your fork
  3. Make the change
  4. Test it (see below)
  5. Submit a Pull Request

If you are new to git and GitHub and the above makes no sense to you then this primer may be useful.

Only committers to the adoptium.temurin project 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:

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:

VagrantPlaybookCheck

  • Tests changes made to the Unix or Windows playbook.
  • Suitable to test changes made which concern the x86_64 tasks of the ansible playbooks
  • Requires authorised access to kick off (ping a member of the infrastructure team if necessary)

QemuPlaybookCheck

  • Tests changes made to the Unix playbook
  • Suitable to test changes made which concern non x86_64 tasks of the ansible playbooks, such as s390x, arm32, aarch64, riscv and ppc64le
  • Requires authorised access to kick off (ping a member of the infrastructure team if necessary)

QEMU-playbook-check pull request Label

We have some information on running virtual machines to test the playbooks in the ansible directory README

We expect developers to test their Ansible changes in a test environment 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 Usage Guide

Commit messages

Wherever possible, prefix the commit message with the area which you are changing e.g.

  • unixPB:
  • winPB:
  • aixPB:
  • ansible:
  • vagrant:
  • pbTests:
  • docs:
  • plugins:
  • inventory:
  • github:
  • tools:
  • nagios:
  • wazuh:

Further Docs

Project documentation in permanent form (e.g. Build Farm architecture) is stored in the docs folder.