CONTRIBUTING.md

How to contribute to k6registry

Thank you for your interest in contributing to k6registry!

Before you begin, make sure to familiarize yourself with the Code of Conduct. If you've previously contributed to other open source project, you may recognize it as the classic Contributor Covenant.

Prerequisites

The tools listed in the [tools] section should be installed before contributing. It is advisable to first install the cdo tool, which can be used to easily perform the tasks described here. The cdo tool can most conveniently be installed using the eget tool.

eget szkiba/cdo

The cdo tool can then be used to perform the tasks described in the following sections.

Help about tasks:

cdo

tools - Install the required tools

Contributing will require the use of some tools, which can be installed most easily with a well-configured eget tool.

eget mikefarah/yq
eget atombender/go-jsonschema
eget szkiba/mdcode
eget golangci/golangci-lint
eget goreleaser/goreleaser

schema - Update schema and generate code

After modifying registry schema (registry.schema.json), the registry_gen.go file must be regenerated.

curl -s -o docs/registry.schema.json https://raw.githubusercontent.com/grafana/k6-extension-registry/main/registry.schema.json
go-jsonschema --capitalization URL --capitalization JavaScript --capitalization OSS -p k6registry --only-models -o registry_gen.go docs/registry.schema.json

example - Update documentation due to example changes

The example registry can be found in example.yaml file, the documentation (registry.md, README.md) must be updated after modification.

go run ./cmd/k6registry --lint -o docs/example.json --catalog docs/example-catalog.json docs/example.yaml
go run ./cmd/k6registry --lint -q --api docs/example-api docs/example.yaml
tree -n --noreport --filesfirst -o docs/example-api.txt docs/example-api 
mdcode update docs/registry.md
mdcode update README.md

custom - Update custom example

export ORIGIN=https://registry.k6.io/registry.json
go run ./cmd/k6registry --lint --catalog docs/custom-catalog.json -o docs/custom.json --origin $ORIGIN docs/custom.yaml

readme - Update README.md

After changing the CLI tool or example registry, the documentation must be updated in README.md.

go run ./tools/gendoc README.md
mdcode update README.md

lint - Run the linter

The golangci-lint tool is used for static analysis of the source code. It is advisable to run it before committing the changes.

golangci-lint run

test - Run the tests

go test -count 1 -race -coverprofile=coverage.txt ./...

coverage - View the test coverage report

Requires : test

go tool cover -html=coverage.txt

build - Build the executable binary

This is the easiest way to create an executable binary (although the release process uses the goreleaser tool to create release versions).

go build -ldflags="-w -s" -o k6registry ./cmd/k6registry

snapshot - Creating an executable binary with a snapshot version

The goreleaser command-line tool is used during the release process. During development, it is advisable to create binaries with the same tool from time to time.

rm -f k6registry
goreleaser build --snapshot --clean --single-target -o k6registry

docker - Build docker image

Building a Docker image. Before building the image, it is advisable to perform a snapshot build using goreleaser. To build the image, it is advisable to use the same Docker.goreleaser file that goreleaser uses during release.

Requires : snapshot

docker build -t k6registry -f Dockerfile.goreleaser .

clean - Delete the build directory

rm -rf build

update - Update everything

The most robust thing is to update everything (both the schema and the example) after modifying the source.

Requires : schema, example, readme

legacy - Convert legacy registry

 go run ./cmd/k6registry . --legacy | yq '.[]|= pick(["module","description","tier","products","imports","outputs","repo","categories"])|sort_by(.module)' > ./docs/legacy.yaml