sap-jenkins-library/DEVELOPMENT.md

Development

Table of contents:

1. Getting started
2. Build the project
3. Logging
4. 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.