Skip to content
This repository was archived by the owner on Jun 5, 2026. It is now read-only.

CONTRIBUTING.md

Latest commit

 

History

History
232 lines (170 loc) · 6.42 KB

CONTRIBUTING.md

File metadata and controls

232 lines (170 loc) · 6.42 KB
Raw

Contributing to xk6-ai

Thank you for your interest in contributing to xk6-ai! This document provides guidelines for contributing to this k6 extension project.

Getting Started

Prerequisites

  • Go 1.21 or later
  • xk6 tool installed
  • Git configured with your credentials
  • Basic understanding of k6 and Go development

Development Setup

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/your-username/xk6-ai.git
cd xk6-ai
  3. Install dependencies: 
    go mod download
  4. Run tests to ensure everything works: 
    go test ./...

Development Process

Using the Makefile

The project includes a comprehensive Makefile with targets for common development tasks:

# Install development tools (golangci-lint, xk6, gosec, govulncheck, act)
make install-tools

# Code quality
make fmt          # Format code
make lint         # Run linting
make lint-fix     # Auto-fix linting issues
make security     # Run security scans

# Testing
make test         # Run unit tests
make test-coverage # Run tests with coverage
make test-race    # Run tests with race detection

# Building
make build        # Build k6 extension
make build-local  # Build from local source

# CI testing with act
make ci-test      # Run test job locally
make ci-lint      # Run lint job locally
make ci-all       # Run all CI jobs locally

# Full validation
make release-test # Run all CI checks
make release-check # Full release validation

Quick Development Workflow

  1. make install-tools - Install required tools
  2. make fmt lint test - Format, lint, and test
  3. make ci-all - Run full CI locally
  4. make release-check - Final validation before PR

Contribution Guidelines

Code Review Process

  • All changes require peer review before merging
  • Review for constitution compliance (see AGENTS.md)
  • Check test coverage and quality
  • Verify security best practices are followed
  • Ensure documentation is updated appropriately

Issue Management

  • Use GitHub Issues for bug reports and feature requests
  • Follow conventional commit messages for clear history
  • Link issues to specifications when applicable (spec-driven development)
  • Maintain clear issue templates and descriptions
  • Use appropriate labels for issue categorization

Branching Strategy

  • Use feature branches for all development work
  • Follow conventional branch naming (e.g., feature/llm-integration, fix/memory-leak)
  • Keep branches focused and atomic (one feature/fix per branch)
  • Regular integration with main branch to avoid conflicts
  • Delete feature branches after successful merge

Commit Guidelines

Follow conventional commit format:

type(scope): description

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore

Examples:

  • feat(llm): add OpenAI integration
  • fix(memory): resolve goroutine leak in client
  • docs(api): update README with usage examples

Development Workflow

Spec-Driven Development

This project follows spec-driven development principles:

  1. Clarify: Use structured clarification workflow before planning
  2. Specify: Create detailed specifications in .specify/specs/
  3. Plan: Generate implementation plans with technical details
  4. Implement: Follow TDD approach with spec-kit implementation commands
  5. Validate: Ensure compliance with constitution and specifications

Testing Requirements

  • Write unit tests for all public functions
  • Use table-driven tests for multiple test cases
  • Aim for high test coverage, especially for critical business logic
  • Include smoke tests in test/smoke.test.js
  • Run xk6 lint to check extension compliance

Code Quality

  • Use gofmt and goimports for formatting
  • Follow Go naming conventions
  • Keep functions short and focused
  • Write self-documenting code with clear comments
  • Use golangci-lint for static analysis

k6 Extension Specific Guidelines

Build Process

  • Use xk6 build --with github.com/grafana/xk6-ai@latest for testing
  • Ensure compatibility with target k6 versions
  • Test with xk6 lint for compliance checking (target grade C or higher)

Required Files

  • go.mod - Valid Go module definition
  • README.md - Comprehensive project documentation
  • LICENSE - Acceptable open source license
  • examples/ - Usage examples directory
  • test/smoke.test.js - Working smoke test
  • docs/index.d.ts - TypeScript API declarations

Compliance Checklist

Before submitting PRs, ensure:

  • xk6 lint passes with grade C or higher
  • All tests pass (go test ./...)
  • Smoke test runs successfully
  • Documentation is updated
  • Examples are provided for new features
  • Security scan passes (gosec, govulncheck)

Pull Request Process

  1. Create a feature branch from main
  2. Make your changes following the guidelines above
  3. Write tests for new functionality
  4. Update documentation as needed
  5. Run compliance checks (xk6 lint, tests, security scans)
  6. Create a pull request with:
    • Clear description of changes
    • Reference to related issues
    • Screenshots for UI changes
    • Test results and compliance scores

PR Review Criteria

Reviewers will check for:

  • Code quality and style compliance
  • Test coverage and quality
  • Documentation completeness
  • Security best practices
  • Performance considerations
  • k6 extension compliance

Reporting Issues

Bug Reports

When reporting bugs, please include:

  • k6 version and xk6-ai version
  • Operating system and architecture
  • Steps to reproduce
  • Expected vs actual behavior
  • Error messages and logs
  • Minimal test case if possible

Feature Requests

For feature requests, please include:

  • Use case description
  • Proposed solution
  • Alternative solutions considered
  • Impact assessment

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. Please be respectful and constructive in all interactions.

Getting Help

  • Check existing issues and discussions
  • Join the k6 community Discord/Slack
  • Create a new issue for questions
  • Review the AGENTS.md file for development guidelines

License

By contributing to xk6-ai, you agree that your contributions will be licensed under the same license as the project (see LICENSE file).

Thank you for contributing to xk6-ai! Your contributions help make this project better for everyone.