CONTRIBUTING.adoc

Contributing to Jenkinsfile Runner

This page provides information about contributing code to the Jenkinsfile Runner codebase.

Table of Contents

• Getting started
• Documentation
• Contacts
• Building
  • Building Docker images
• Debugging
• Testing changes
• Proposing Changes
• Continuous Integration

Getting started

1. Fork the repository on GitHub

2. Clone the forked repository to your machine

3. Install the development tools. To develop Jenkinsfile Runner, you need the following tools:

   • Java Development Kit (JDK) 8.

     • We usually use [OpenJDK](http://openjdk.java.net/) but you can use other JDKs as well.

   • Maven 3.5.4 or above.

   • Any IDE which supports importing Maven projects.

   • Docker.

   • Make.

Documentation

This page provides basic information about building and testing Jenkinsfile Runner. In case you are more interested in details and in the architecture, see the Developer Documentation.

Contacts

If you have any questions or need help, please use the following channels:

• Forum on Discourse - for JFR usage and developer discussions

• Gitter Chat - for JFR usage and development questions

• Jenkins Cloud Native SIG channels: mailing lists, chats, meetings

• Jenkins Developer Mailing list - for JFR development questions

Building

The build flow for Jenkinsfile Runner is built around Maven and Docker.

Run mvn clean package for the project to be just built and mvn clean package -Denvironment=test for the project to be built and the integration tests to be launched, which are based on the Jenkinsfile Runner Test Framework.

This will generate an assembly artifact through the appassembler-maven-plugin that can be configured and used to run Jenkinsfiles.

Building Docker images

This repository includes the base image which can be built simply as…​

docker build -t jenkins4eval/jenkinsfile-runner -f packaging/docker/unix/eclipse-temurin-11-jre/Dockerfile .

During development you can reuse the local machine build instead of doing a full build from scratch

docker build -t jenkins4eval/jenkinsfile-runner:dev -f packaging/docker/unix/eclipse-temurin-11-jre/Dockerfile-dev-vanilla .

Debugging

See the Debugging Guidelines.

Testing changes

Jenkinsfile Runner includes integration tests as a part of the repository.

These tests (tests module) take a while even on server-grade machines. All of them will be launched by the continuous integration instance, so there is no strict need to run them before proposing a pull request.

In case you want to run them, see the previous section. You could also enter the tests directory and execute the make command.

Proposing Changes

All proposed changes are submitted and code reviewed using the GitHub Pull Request process.

To submit a pull request:

1. Commit changes and push them to your fork on GitHub. It is a good practice to create branches instead of pushing to master.

2. In GitHub Web UI click the New Pull Request button

3. Select jenkinsci/jenkinsfile-runner as base fork and master as base, then click Create Pull Request

4. Fill in the Pull Request description according to the changes.

5. Click Create Pull Request

6. Wait for CI results/reviews, process the feedback.

It is recommended that new features/changes include testing proving the changes are working correctly.

Continuous Integration

Jenkinsfile Runner uses ci.jenkins.io as Continuous Integration server and uses Jenkins Pipeline to run builds. See the job here. The code for the build flow is stored in the Jenkinsfile in the repository root.

If you want to update that build flow (e.g. "add more checks"), just submit a pull request.