Contributing Guidelines
Thank you for your interest in contributing to xk6-python!
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.
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.
Ensure the bug was not already reported by searching on GitHub under Issues.
If you’re unable to find an open issue addressing the problem, open a new one. Be sure to include a title and clear description, as much relevant information as possible.
The worst that can happen is that someone closes it and points you in the right direction.
Contributing code
If you’d like to contribute code to xk6-python, you will need Go, golangci-lint and xk6.
The starlark REPL tool can be useful for experimentation:
go install go.starlark.net/cmd/starlark@latest
This is the basic procedure.
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 in a GitHub Issue before you get started on the implementation.
Create a fork and open a feature branch -
feature/my-cool-featureis the classic way to name these, but it really doesn’t matter.Create a pull request!
We will discuss implementation details until everyone is happy, then a maintainer will merge it.
Implement a module
The new module can be implemented in two ways:
built-in module using the go programming language
embedded module using the starlark programming language
local module using the starlark programming language
Regardless of the way of implementation, the modules are used in the same way. The builtin module takes precedence if there is a builtin and an embedded module with the same name.
Builtin module
The builtin module must be written in the go programming language. Each module is placed in a separate go package within the py/builtin directory. The package must have a public loader function to load the module’s global starlark symbols.
type BuiltinLoaderFunc func(moduleName string, thread *starlark.Thread, vu modules.VU) (starlark.StringDict, error)
The builtin module must be registered in the Bootstrap() function (in the py/bootstrap.go file) using a registerBuiltin() function call.
Embedded module
The embedded modules are to be implemented in starlark (Python). Each module is placed in a separate file within the py/embedded directory. The file extension can be .py or .star, the advantage of .star is that using the bazel-stack-vscode Visual Studio Code extension, quite good editor support is available for the starlark language.
Embedded modules are loaded without using a file extension. This way, the embedded module can later be rewritten as a builtin module.
No registration is required for modules placed in the py/embedded directory. This folder will be embedded in the go code of the k6 extension and the modules here will be automatically available in the test script.
If justified, additional embedded filesystems can be added to the search path of embeddedd modules. Additional embedded filesystems can be registered in the Bootstrap() function (in the py/bootstrap.go file) using a registerFilesystem() or registerSubFilesystem function call.
Remote module
The remote modules are to be implemented in starlark (Python). The remote modules must be deployed on a static web server and can be accessed from there using the https protocol.
The grafana/k6pylib GitHub repository is an example remote module collection. The repository is automatically deployed using GitHub Pages.
The easiest way to try out remote modules is to use the grafana/k6pylib repository. You simply need to create a Python/starlark module and merge it into the main branch.
Local module
The local module is only included in this list for the sake of completeness. The local modules are not part of the xk6-python extension, they are located locally next to the test script, in files with the extension .py or .star. To load the local module, you must always specify the file extension.
Typical tasks
This section describes the typical tasks of contributing code.
If the cdo tool is installed, the tasks can be easily executed. Otherwise, you’ll need to type or copy the commands here.
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
Run all tests and collect coverage data.
go test -count 1 -race -coverprofile=coverage.txt ./...
coverage - View the test coverage report
Requires : test
go tool cover -html=coverage.txt
build - Build k6 executable binary
Extensions can be integrated into the k6 executable using the xk6 CLI tool.
xk6 build --with github.com/grafana/xk6-python=.
run - Run Python test script with k6
With the xk6 CLI tool, python test scripts can be run from the repository base directory without building k6.
xk6 run ${1:-script.py}
readme - Update exmaple in README.md
Using the mdcode tool, the example script in README.md can be updated from the script.py file.
mdcode update
docs-install - Install documentation tools
Create a Python virtual environment, activate, and install the needed dependencies (for the first time only).
python3 -m venv env
source env/bin/activate
pip install -r docs/requirements.txt
docs - Generate documentation
Generate project documentation in build/docs directory.
Requires : docs-install
source env/bin/activate
sphinx-build -b html docs build/docs
ci - Run all ci-relevant tasks
Run all the tasks that will run in the Continuous Integration system.