docs: how to contribute

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
+```

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;\
+	)
+

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.