Contributing

Contributing to updatecli

Instead of rewriting the "almost" same script over and over, this project has been created to easily implement update pipelines. The project is open to contributions.

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

CONTRIBUTE

There are many ways to contribute which don’t necessarily involve coding. Providing feedback, improving documentation, processes.

FEEDBACK

It’s 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 working on a local optimum. So we welcome any feedback 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. Core is designed to be independent and to provide the skeleton for the updatecli, while plugins define specific third party behaviors. Working on plugins is a little easier as it allows contributions independently of core development.

CORE

This section is still evolving. There 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 are set when unmarshalling from your 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 contracts by defining appropriate functions.

Table 1. Rules
StageInterfaceDescription

Source

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

Defines how a version is retrieved then in 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 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 to 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 work:

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 can’t 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 July 2, 2024
Edit this page on GitHub
← Terragrunt
FAQ →