Skip to content

CONTRIBUTING.adoc

Latest commit

 

History

History
246 lines (176 loc) · 6.87 KB

CONTRIBUTING.adoc

File metadata and controls

246 lines (176 loc) · 6.87 KB

Contributing

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

Table of Contents

Requirements

To build the project, make sure that you have installed https://go.dev/, GNU Make and goreleaser, then execute the command make build, or use Docker with:

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

Contribute

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

Feedback

It’s significantly harder to build a solution that could be used by different people. It involves many different skills hard to master and it’s easy to get stuck in local optimum. So feel free to reach out to say what’s wrong and what could be improved.

Code

The code is divided into two categories, core and plugins. The core is designed to be independent and to provide the skeleton for the application, while the plugins define how things are automated for a specific use-case. 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’re many areas that need attention.

Financially

If you’re using this project and it’s saving you time, consider supporting it financially. It’s a great way to show appreciation and to help the project grow. You can sponsor the project on GitHub at link

Plugins

Plugins can be easily added by 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
│       ├── spec.go
│       ├── target_test.go
│       ├── target.go
│       ├── main_test.go
│       └── main.go
└── main_test.go
2. Define configuration

In the spec.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

/*
    One multiline comment is required
*/
type Spec struct {
  /*
    One multiline comment is required per field
  */
	Field1        string `yaml:",omitempty"`
	Field2        string `yaml:",omitempty" jsonschema:"required"`
	Field3        string `yaml:",omitempty"`
	Field4        string `yaml:",omitempty"`
}

Tags

Fields tags are important components and can come from one of the two following modules:

Comments

Fields comments are critical as they are used to generate Updatecli documentation available both from www.updatecli.io and your favorite IDE.

Our objective is to have Spec comments such as

A short one-line description of the parameter

  compatible
    <A list of compatible stages>
    * source
    * condition
    * target

  default:
    A short explanation of the default value. It's also the place for explaining if the value is inherited from the source output.

  remarks:
    A list of information to be aware of when using the parameter such
    * info 1
    * info 2

  example:
    If useful, a simple example of how to use it
3. Respect the contract

Your 'packageName' must provide a struct which implements the Resource interface by defining the following functions:

Table 1. Rules
Stage Interface Description

Source

 
Source(workingDir string, resultSource *result.Source) error

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

Changelog

 
Changelog() string

Retrieve the changelog for a specific source.

Condition

 
Condition(source string, scm scm.ScmHandler) (pass bool, message string, err error)

Define a condition which has to pass in order to proceed

Target

 
Target(source string, scm scm.ScmHandler, dryRun bool, resultTarget *result.Target) error

Define how a target file is updated
4. Claim your name

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

  import "github.com/updatecli/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:
  default:
    kind: packageName
    spec:
      field1: "value"
      field3: "value"
targets:
  idName:
    name: "updatecli"
    kind: "yaml"
    spec:
      file: "..."
      key:  "..."
    transformers:
      - addPrefix: "olblak/polls@256:"

TEST

Unit Tests

Unit tests are golang test which are executed by default, even with the -short flag set up (e.g. executed when testing.Short() == "true").

They usually uses mocks as they should:

  • Have no external dependencies such as database or external API

  • Avoid as much as possible network requests

  • Run in less than 2s (compilation excluded)

make test-short

Integration Tests

Integration tests are golang test which are executed by default but not with the -short flag set up (e.g. not executed when testing.Short() == "true").

make test

End to End (e2e) Tests

  • OVH’s Venom CLI is required

  • A GitHub Personal Access Token (PAT) is required with read access to public repositories

  • Define the following environment variables (otherwise the make command will fail with a message telling you which variable is missing):`

    • $GITHUB_TOKEN set to the GitHub PAT mentioned above

    • $GITHUB_ACTOR set to the GitHub username associated to the aforementioned GitHub PAT

export GITHUB_TOKEN=$(<command to get token from password manager>) # Treat this as a SENSITIVE value!
export GITHUB_ACTOR=xxxxx

venom version # expect v1.2.0

make test-e2e

The execution log is written by Venom into ./e2e/venom.log.

DOCUMENTATION

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