Contributing Guide

We welcome contributions to conc! This guide will help you get your development environment set up and walk you through the process of making a contribution.

Development Setup

  1. Fork and Clone: Fork the repository on GitHub and clone your fork locally.

    git clone https://github.com/YOUR_USERNAME/conc.git
cd conc

  2. Install Dependencies: The project has minimal dependencies, which will be downloaded automatically by Go commands.

Running Tests

To run the test suite, you can use the go test command or the provided Makefile target. The -race flag is important for detecting race conditions in concurrent code.

# Using the Makefile
make test

# Or directly with go
go test -race -v ./...

Tests should pass before you submit a pull request.

Linting

This project uses golangci-lint to enforce code quality and style. The configuration is defined in .golangci.yml.

  1. Install golangci-lint: If you don't have it, you can install it with: 

    go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

    The Makefile can also install it for you if it's missing.

  2. Run the Linter:

    make lint

    This command will run the linter and automatically fix any issues it can.

Running Benchmarks

The repository contains benchmarks to measure the performance of the concurrency primitives.

To run the benchmarks, use the bench target in the Makefile:

make bench

This will execute go test ./... -bench . -benchtime 5s ... and output the results.

Submitting a Pull Request

  1. Create a new branch for your feature or bug fix: 
    git checkout -b my-new-feature
  2. Make your changes. Remember to add tests for any new functionality.
  3. Ensure all tests and linters pass.
  4. Commit your changes with a clear and descriptive message.
  5. Push your branch to your fork: 
    git push origin my-new-feature
  6. Open a pull request from your fork to the main branch of sourcegraph/conc.

Continuous Integration

We use GitHub Actions for continuous integration. When you open a pull request, the following checks will be run automatically:

  • Build: The code is built against multiple Go versions.
  • Lint: golangci-lint is run to check for style issues.
  • Test: The test suite is run with the race detector enabled.
  • Code Coverage: Code coverage is reported to Codecov.
  • Benchmarks: Benchmarks are run and compared against the main branch to detect performance regressions.

Your pull request must pass all these checks to be eligible for merging.