Contributing

Contributing to updatecli

Instead of rewritng the "almost" same script over and over, this project has been created to easily implement update pipeline. The project is open to contribution as long as they remain generic enough or with a shared interest.

Thanks for your interest in this project, feel free to ask any questions you may have.

CONTRIBUTE

They are multiple ways to contribute which don’t necessarily involve coding like providing feedback, improving documentation, processes. Here I’ll just highlight some of them

FEEDBACK

It significantly harder to build a solution that could be used by different people. It involves many different skills that are hard to master and it’s easy to get stuck in the local optimum. So we welcome any feedbacks you may have.

CODE

REQUIREMENTS

To build the project, just ensure to have access to the correct golang version then just run make build which should return something like:

echo v0.0.15-6-g1e24f1d
v0.0.15-6-g1e24f1d
go build \
	-ldflags "-w -s \
        -X \"github.com/olblak/updateCli/pkg/version.BuildTime=`date -R`\" \
        -X \"github.com/olblak/updateCli/pkg/version.GoVersion=go version go1.15.2 linux/amd64\" \
        -X \"github.com/olblak/updateCli/pkg/version.Version=v0.0.15-6-g1e24f1d\""\
        -o bin/updatecli

or using docker

docker run --rm -v "$PWD":/usr/src/updatecli -w /usr/src/updatecli -e GOOS=windows -e GOARCH=386 golang:1.15 go build -v

The code is divided into two categories, core, and plugins. It says what it says. Core is designed to be independent and to provide the skeleton for the updatecli while plugins define specific third party behaviors.. The easiest part is probably plugins as it allows you to contribute independently to the process you are looking to automate.

CORE

This section is still evolving as they are many areas that need attention.

PLUGINS

Plugins can be easily added following this workflow:

1. Define Package name

Creating a new directory using your "packageName" under the directory pkg/plugins that will contain your go package similar to:

pkg
├── plugins
│   └── packageName
│       ├── source_test.go
│       ├── source.go
│       ├── condition_test.go
│       ├── condition.go
│       ├── target_test.go
│       ├── target.go
│       ├── main_test.go
│       └── main.go
└── main_test.go
2. Define configuration

In the main.go, you need to define the struct that you’ll use to configure your workflow where the capitalized fields will be set when unmarshalling from your future configuration.yaml

type Capitalized_package_name struct {
	Field1        string
	Field2        string
	Field3        string
	Field4        string
}
3. Respect the contract

Your 'packageName' must respect at least one of the following interface contract by defining appropriated functions.

Table 1. Rules
StageInterfaceDescription

Source

type Spec interface {
    Source() (string, error)
}

Defines how a version will be retrieved then passed the following stages

Changelog

type Changelog interface {
    Changelog(release string) (string, error)
}

Retrieve the changelog for a specific source.

Condition

type Spec interface {
    Condition(version string) (bool, error)
    ConditionFromSCM(version string, scm scm.Scm) (bool, error)
}

Define a condition which has to pass in order to proceed

Target

type Spec interface {
    Target(source string, dryRun bool) (bool, error)
    TargetFromSCM(source string, scm scm.Scm, dryRun bool) (changed bool, files []string, message string, err error)

Define how a target file will be updated

4. Claim your name

Each stage which can be configured using a yaml/go template has to bind a plugin name and a package name, this is done in the "Unmarshal" function

  import "github.com/olblak/updateCli/pkg/plugins/packageName"
  ...

	case "packageName":
		p := packageName.PackageName{}
		err := mapstructure.Decode(s.Spec, &p)

		if err != nil {
			return err
		}

		spec = &p

Now something like this, should be working:

config.value

# updatecli diff --config config.value

sources:
  lastPackage:
    kind: packageName
    spec:
      field1: "value"
      field3: "value"
targets:
  idName:
    name: "updatecli"
    kind: "yaml"
    prefix: "olblak/polls@256:"
    spec:
      file: "..."
      key:  "..."
5. Testing

Add a manifest to e2e/updatecli.d/success.d/crate.yaml

The manifest cannot return any error or warning message as define on https://github.com/updatecli/updatecli/blob/main/e2e/venom.d/test_diff.yaml

DOCUMENTATION

If you spot phrasing issues or just a lack of documentation, feel free to open an issue and/or a pull request with your contribution.

Last modified on January 17, 2023
Edit this page on GitHub
← Terraform
FAQ →