mirror of
https://github.com/SAP/jenkins-library.git
synced 2024-12-14 11:03:09 +02:00
132 lines
4.1 KiB
Markdown
132 lines
4.1 KiB
Markdown
# Development
|
|
|
|
**Table of contents:**
|
|
|
|
1. [Getting started](#getting-started)
|
|
1. [Build the project](#build-the-project_)
|
|
1. [Logging](#logging)
|
|
1. [Error handling](#error-handling)
|
|
|
|
## Getting started
|
|
|
|
1. [Ramp up your development environment](#ramp-up)
|
|
1. [Get familiar with Go language](#go-basics)
|
|
1. Create [a GitHub account](https://github.com/join)
|
|
1. Setup [GitHub access via SSH](https://help.github.com/articles/connecting-to-github-with-ssh/)
|
|
1. [Create and checkout a repo fork](#checkout-your-fork)
|
|
1. Optional: [Get Jenkins related environment](#jenkins-environment)
|
|
1. Optional: [Get familiar with Jenkins Pipelines as Code](#jenkins-pipelines)
|
|
|
|
### Ramp up
|
|
|
|
First you need to set up an appropriate development environment:
|
|
|
|
Install Go, see [GO Getting Started](https://golang.org/doc/install)
|
|
|
|
Install an IDE with Go plugins, see for example [Go in Visual Studio Code](https://code.visualstudio.com/docs/languages/go)
|
|
|
|
### 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](https://golang.org/doc/) especially, [A Tour of Go](https://tour.golang.org/welcome/1)
|
|
|
|
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](https://github.com/quii/learn-go-with-tests)
|
|
|
|
### Checkout your fork
|
|
|
|
The project uses [Go modules](https://blog.golang.org/using-go-modules). Thus please make sure to **NOT** checkout the project into your [`GOPATH`](https://github.com/golang/go/wiki/SettingGOPATH).
|
|
|
|
To check out this repository:
|
|
|
|
1. Create your own
|
|
[fork of this repo](https://help.github.com/articles/fork-a-repo/)
|
|
1. Clone it to your machine, for example like:
|
|
|
|
```shell
|
|
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](https://groovy-lang.org/install.html)
|
|
* [Install Maven](https://maven.apache.org/install.html)
|
|
* 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](https://jenkins.io/doc/book/pipeline-as-code/)
|
|
* [Jenkins Shared Libraries](https://jenkins.io/doc/book/pipeline/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](https://github.com/tektoncd/pipeline/blob/master/docs/tasks.md).
|
|
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
|
|
|
|
```golang
|
|
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](https://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](https://github.com/stretchr/testify/assert) in order to have slimmer assertions if you like.
|