Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
126 lines (98 loc) · 4.75 KB

CONTRIBUTING.md

File metadata and controls

126 lines (98 loc) · 4.75 KB
Raw

Contributing Guidelines

Thank you for your interest in contributing to k6 Extension Registry!

To contribute, simply open a pull request.

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.

Contributing to the registry

Important

Before registering a new extension, please read the Registry Requirements.

The source of the registry can be found in the [registry.yaml] file. To register an extension, simply add a new entry to the end of the file. The data of the already registered extension can be modified accordingly.

After modifying the [registry.yaml], it is advisable to run the linter.

The schema for the registry [registry.schema.json] file.

Important

The schema is maintained in k6registry it is copied here for convenience but any change in the schema must be done in k6registry's repository.

Tasks

The following sections describe the typical tasks of contributing. As long as the cdo tool is installed, these can be easily executed using it (tip: first run the cdo command without parameters).

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 grafana/k6registry
eget hairyhenderson/gomplate
pip install json-schema-for-humans

lint - Run the linter

After modifying the [registry.yaml] file, it is recommended to run the static analysis using the k6registry command. This may take 1-2 minutes.

k6registry -q --lint registry.yaml

public - Generate static documentation

npx @redocly/cli build-docs -o public/index.html openapi.yaml
generate-schema-doc --config with_footer=false --config collapse_long_descriptions=false registry.schema.json public/schema
mv public/schema/registry.schema.html public/schema/index.html

wiki - Generate API files

The registry is exposed using and API defined in [openapi.yaml]. This API is served using static files generated from the registry using the [generate-api-files.sh] script. The script takes the registry.json generated from [registry.yaml] using k6registry as input to generate the json file to be returned by each endpoint. It also generates a metrics.txt file with metrics for the extensions by tier, grade, and issues found.

export BUILD_DIR=build/api/v1
k6registry registry.yaml > ${BUILD_DIR}/registry.json
./generate-api-files.sh -b ${BUILD_DIR}

Generates the following files

build/api/v1
├── catalog.json
├── metrics.json
├── metrics.txt
├── registry.json
├── grade
│   ├── A.json
│   ├── B.json
│   ├── C.json
│   ├── D.json
│   ├── E.json
│   └── F.json
├── module
│   ├── github.com
│   │   └── grafana
│   │       ├── xk6-dashboard
│   │       │   ├── badge.svg
│   │       │   ├── extension.json
│   │       │   └── grade.svg
│   │       ├── xk6-disruptor
│   │       │   ├── badge.svg
│   │       │   ├── extension.json
│   │       │   └── grade.svg
│   │       ├── xk6-faker
│   │       │   ├── badge.svg
│   │       │   ├── extension.json
│   │       │   └── grade.svg
│   │       └── xk6-sql
│   │           ├── badge.svg
│   │           ├── extension.json
│   │           └── grade.svg
│   ├── gitlab.com
│   │   └── szkiba
│   │       └── xk6-banner
│   │           ├── badge.svg
│   │           ├── extension.json
│   │           └── grade.svg
│   └── go.k6.io
│       └── k6
│           └── extension.json
└── tier
    ├── community-catalog.json
    ├── community.json
    ├── community-metrics.json
    ├── official-catalog.json
    ├── official.json
    └── official-metrics.json

wiki - Generate wiki pages

export BASE_URL=https://registry.k6.io
export API_DIR=build/api/v1
gomplate -c registry=${API_DIR}/registry.json -c metrics=${API_DIR}/metrics.json -c official_metrics=${API_DIR}/tier/official-metrics.json -c schema=registry.schema.json --input-dir wiki --output-map='build/wiki/{{.in|strings.TrimSuffix ".tpl"}}'