sap-jenkins-library/DEVELOPMENT.md

Development

Table of contents:

1. Getting started
2. Build the project
3. Generating step framework
4. Logging
5. Error handling

Getting started

1. Ramp up your development environment
2. Get familiar with Go language
3. Create a GitHub account
4. Setup GitHub access via SSH
5. Create and checkout a repo fork
6. Optional: Get Jenkins related environment
7. Optional: Get familiar with Jenkins Pipelines as Code

Ramp up

First you need to set up an appropriate development environment:

Install Go, see GO Getting Started

Install an IDE with Go plugins, see for example Go in Visual Studio Code

Go basics

In order to get yourself started, there is a lot of useful information out there.

As a first step to take we highly recommend the Golang documentation especially, A Tour of Go

We have a strong focus on high quality software and contributions without adequate tests will not be accepted. There is an excellent resource which teaches Go using a test-driven approach: Learn Go with Tests

Checkout your fork

The project uses Go modules. Thus please make sure to NOT checkout the project into your GOPATH.

To check out this repository:

1. Create your own fork of this repo
2. Clone it to your machine, for example like:

mkdir -p ${HOME}/projects/jenkins-library
cd ${HOME}/projects
git clone git@github.com:${YOUR_GITHUB_USERNAME}/jenkins-library.git
cd jenkins-library
git remote add upstream git@github.com:sap/jenkins-library.git
git remote set-url --push upstream no_push

Jenkins environment

If you want to contribute also to the Jenkins-specific parts like

• Jenkins library step
• Jenkins pipeline integration

you need to do the following in addition:

• Install Groovy
• Install Maven
• Get a local Jenkins installed: Use for example [cx-server](toDo: add link)

Jenkins pipelines

The Jenkins related parts depend on

• Jenkins Pipelines as Code
• Jenkins Shared Libraries

You should get familiar with these concepts for contributing to the Jenkins-specific parts.

Build the project

Build the executable suitable for the CI/CD Linux target environments

Use Docker:

docker build -t piper:latest .

You can extract the binary using Docker means to your local filesystem:

docker create --name piper piper:latest
docker cp piper:/piper .
docker rm piper

Generating step framework

The steps are generated based on the yaml files in resources/metadata/ with the following command go run pkg/generator/step-metadata.go.

The yaml format is kept pretty close to Tekton's task format. Where the Tekton format was not sufficient some extenstions have been made.

Examples are:

• matadata - longDescription
• spec - inputs - secrets
• spec - containers
• spec - sidecars

Logging

to be added

Error handling

In order to better understand the root cause of errors that occur we wrap errors like

    f, err := os.Open(path)
    if err != nil {
        return errors.Wrapf(err, "open failed for %v", path)
    }
    defer f.Close()

We use github.com/pkg/errors for that.

Testing

Unit tests are done using basic golang means.

Additionally we encourage you to use github.com/stretchr/testify/assert in order to have slimmer assertions if you like.