From f775e59075fd17ed617c6412ba2bf67b56b63e1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20SZKIBA?= Date: Mon, 6 Jan 2025 17:21:19 +0100 Subject: [PATCH] docs: how to contribute --- CONTRIBUTING.md | 195 ++++++++++++++++++++++++++++++++++++++++++++++++ Makefile | 110 +++++++++++++++++++++++++++ README.md | 4 + 3 files changed, 309 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 Makefile diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5d3c40f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,195 @@ +# Contributing Guidelines + +Thank you for your interest in contributing to **xk6-faker**! + +Before you begin, make sure to familiarize yourself with the [Code of Conduct](CODE_OF_CONDUCT.md). If you've previously contributed to other open source project, you may recognize it as the classic [Contributor Covenant](https://contributor-covenant.org/). + +If you want to chat with the team or the community, you can [join our community forums](https://community.grafana.com/c/grafana-k6). + +### Filing issues + +Don't be afraid to file issues! Nobody can fix a bug we don't know exists, or add a feature we didn't think of. + +The worst that can happen is that someone closes it and points you in the right direction. + +That said, "how do I..."-type questions are often more suited for [community forums](https://community.grafana.com/c/grafana-k6). + +### Contributing code + +If you'd like to contribute code, this is the basic procedure. + +1. Find an issue you'd like to fix. If there is none already, or you'd like to add a feature, please open one, and we can talk about how to do it. Out of respect for your time, please start a discussion regarding any bigger contributions either in a GitHub Issue, in the community forums **before** you get started on the implementation. + + Remember, there's more to software development than code; if it's not properly planned, stuff gets messy real fast. + +2. Create a fork and open a feature branch - `feature/my-cool-feature` is the classic way to name these, but it really doesn't matter. + +3. Create a pull request! + +4. We will discuss implementation details until everyone is happy, then a maintainer will merge it. + +## Prerequisites + +Prerequisites are listed in the [tools] section in addition to the [go toolchain](https://go101.org/article/go-toolchain.html) and [git](https://git-scm.com/) CLI. + +The `Makefile` is generated from the task list defined in the `CONTRIBUTING.md` file using the [cdo] tool. If the contribution is made to the task list, the `Makefile` must be regenerated, which is why the [cdo] tool is needed. The [cdo] tool can most conveniently be installed using the [eget] tool. + +```bash +eget szkiba/cdo +``` + +[cdo]: https://github.com/szkiba/cdo +[eget]: https://github.com/zyedidia/eget + +## Tasks + +The tasks defined here can be executed manually or conveniently using the make or [cdo] tool. + +**Help about tasks** + +The command below lists the possible tasks. + +using make: + +```bash +make +``` + +using [cdo]: + +```bash +cdo +``` + +**Execute task** + +Tasks are executed by passing the name of the task as a parameter. + +using make: + +```bash +make taskname +``` + +using [cdo]: + +```bash +cdo taskname +``` + +### 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. + +```bash +eget szkiba/mdcode +eget golangci/golangci-lint +eget grafana/xk6 +eget oven-sh/bun +``` + +[tools]: #tools---install-the-required-tools +[xk6]: https://github.com/grafana/xk6 +[mdcode]: https://github.com/szkiba/mdcode +[golangci-lint]: https://github.com/golangci/golangci-lint + +### 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. + +```bash +golangci-lint run +``` + +### test - Run the tests + +The `go test` command is used to run the tests and generate the coverage report. + +```bash +go test -count 1 -race -coverprofile=coverage.out -timeout 60s ./... +``` + +[test]: <#test---run-the-tests> + +### coverage - View the test coverage report + +The go `cover` tool should be used to display the coverage report in the browser. + +Requires +: [test] + +```bash +go tool cover -html=coverage.out +``` + +### build - Build custom k6 with extension + +The [xk6] tool is used to build the k6. + +```bash +xk6 build --with github.com/grafana/xk6-faker=. +``` + +[build]: <#build---build-custom-k6-with-extension> + +### example - Run the examples + +Run the examples embedded in `README.md`. + +```bash +./k6 run examples/default-faker.js +./k6 run examples/custom-faker.js +export XK6_FAKER_SEED=11 + ./k6 run examples/default-faker-env.js +``` + +[example]: #example---run-the-examples + +### readme - Update README.md + +Update the example code and its output in `README.md` using [mdcode] tool. + +```bash +mdcode update +``` + +### clean - Clean the working directory + +Delete the work files created in the work directory (also included in .gitignore). + +```bash +rm -rf ./k6 ./coverage.out ./build ./node_modules ./bun.lockb +``` + +[clean]: #clean---clean-the-working-directory + +### doc - Generate API documentation + +Generate API documentation using `typedoc`. The generated documentation will be placed in the `build/docs` folder. + +```bash +bun x typedoc --out build/docs +``` + +[doc]: #doc---generate-api-documentation + +### all - Clean build + +Performs the most important tasks. It can be used to check whether the CI workflow will run successfully. + +Requires +: [clean], [format], [test], [build], [doc], [example] + +### format - Format the go source codes + +```bash +go fmt ./... +``` + +[format]: #format---format-the-go-source-codes + +### makefile - Generate the Makefile + +```bash +cdo --makefile Makefile +``` diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..5e15c5e --- /dev/null +++ b/Makefile @@ -0,0 +1,110 @@ +# File generated by cdo from CONTRIBUTING.md; DO NOT EDIT. + +SHELL=bash +.SHELLFLAGS=-e -o pipefail -c + +.PHONY: __help__ +__help__: + @echo 'Usage: make [target]' + @echo '' + @echo 'Targets:' + @echo ' all Clean build' + @echo ' build Build custom k6 with extension' + @echo ' clean Clean the working directory' + @echo ' coverage View the test coverage report' + @echo ' doc Generate API documentation' + @echo ' example Run the examples' + @echo ' format Format the go source codes' + @echo ' lint Run the linter' + @echo ' makefile Generate the Makefile' + @echo ' readme Update README.md' + @echo ' test Run the tests' + @echo ' tools Install the required tools' + +# Clean build +.PHONY: all +all: clean format test build doc example + +# Build custom k6 with extension +.PHONY: build +build: + @(\ + xk6 build --with github.com/grafana/xk6-faker=.;\ + ) + +# Clean the working directory +.PHONY: clean +clean: + @(\ + rm -rf ./k6 ./coverage.out ./build ./node_modules ./bun.lockb;\ + ) + +# View the test coverage report +.PHONY: coverage +coverage: test + @(\ + go tool cover -html=coverage.out;\ + ) + +# Generate API documentation +.PHONY: doc +doc: + @(\ + bun x typedoc --out build/docs;\ + ) + +# Run the examples +.PHONY: example +example: + @(\ + ./k6 run examples/default-faker.js;\ + ./k6 run examples/custom-faker.js;\ + export XK6_FAKER_SEED=11;\ + ./k6 run examples/default-faker-env.js;\ + ) + +# Format the go source codes +.PHONY: format +format: + @(\ + go fmt ./...;\ + ) + +# Run the linter +.PHONY: lint +lint: + @(\ + golangci-lint run;\ + ) + +# Generate the Makefile +.PHONY: makefile +makefile: + @(\ + cdo --makefile Makefile;\ + ) + +# Update README.md +.PHONY: readme +readme: + @(\ + mdcode update;\ + ) + +# Run the tests +.PHONY: test +test: + @(\ + go test -count 1 -race -coverprofile=coverage.out -timeout 60s ./...;\ + ) + +# Install the required tools +.PHONY: tools +tools: + @(\ + eget szkiba/mdcode;\ + eget golangci/golangci-lint;\ + eget grafana/xk6;\ + eget oven-sh/bun;\ + ) + diff --git a/README.md b/README.md index 5cab71f..4b4d429 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,10 @@ $ xk6 build --with github.com/grafana/xk6-faker@latest For more build options and how to use xk6, check out the [xk6 documentation](https://github.com/grafana/xk6). +## Contribute + +If you want to contribute or help with the development of **xk6-faker**, start by reading [CONTRIBUTING.md](CONTRIBUTING.md). + ## Feedback If you find the xk6-faker extension useful, please star the repo. The number of stars will determine the time allocated for maintenance.