updatecli/CONTRIBUTING.adoc at main · alecharp/updatecli · GitHub
Skip to content

CONTRIBUTING.adoc

Latest commit

 

History

History
136 lines (90 loc) · 5.24 KB

CONTRIBUTING.adoc

File metadata and controls

136 lines (90 loc) · 5.24 KB
Raw

Contributing

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

This file covers what you need in a local checkout: building, testing, and getting a change reviewed. The full contributor guide — including how to write a new resource plugin — lives at updatecli.io/docs/help/contributing.

Table of Contents

Requirements

To build the project, install Go, GNU Make and goreleaser, then:

make build

The required Go version is the one declared in go.mod. To build in a container instead, without installing Go at all:

GO_VERSION="$(awk '/^go /{print $2}' go.mod)"

docker run --rm -v "$PWD":/usr/src/updatecli -w /usr/src/updatecli \
  "golang:${GO_VERSION}" go build -v -buildvcs=false -o updatecli

make help lists every available target.

Tests

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.3.0

make test-e2e

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

The manifests exercised by these suites live in e2e/updatecli.d/, grouped by expected outcome: success.d (must produce no warning and no error), warning.d, deprecated.d, and skipped.targets.d. Each group has a matching Venom suite in e2e/venom.d/.

Linters

make lint

Commits and pull requests

Commits carry a Signed-off-by: trailer — use git commit --signoff. This is not enforced by CI, but it is the convention across the history, so please follow it.

The repository provides a pull request template; filling it in is the quickest route to a review.

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.

Adding a resource plugin means creating a package under pkg/plugins/resources/<name>/, implementing the Resource interface from pkg/core/pipeline/resource/main.go, and registering the kind in GetResourceMapping(). The step-by-step walkthrough — the interface, the Spec conventions that generate the documentation and the JSON schema, and how to test it — is on the website:

pkg/plugins/resources/gitcommit is a small, recent plugin worth reading as a model.

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.

Documentation

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

The documentation site is a separate repository: updatecli/website.

Note that a plugin’s parameter documentation is not written there — it is generated from the Go doc comments on the plugin’s Spec fields, so a wrong or missing parameter description is fixed in this repository.