Contributing to Grafana Mimir

This skill provides guidance for contributing to Grafana Mimir, a horizontally scalable, highly available, multi-tenant, long-term storage solution for Prometheus.

What This Skill Does

Helps you navigate the Grafana Mimir contribution workflow, including:

Instructions

1. Understand the GitHub Workflow

Before contributing:

2. Prepare Your Pull Request

Before submitting, ensure:

3. Code Formatting

Mimir uses `goimports` with specific settings:

```bash

go get golang.org/x/tools/cmd/goimports

goimports -local github.com/grafana/mimir

```

Import organization (three groups, no extra newlines):

1. Standard library imports

2. Third-party package imports

3. Internal Grafana Mimir imports

4. Build and Test

Build the project:

```bash

make

```

Run unit tests:

```bash

make test

```

For integration tests, see `how-integration-tests-work.md` in the repository.

**macOS note:** Install `gnu-sed` for all make targets to work properly.

**Docker/Podman note:** Adjust mount options if needed:

```bash

make CONTAINER_MOUNT_OPTIONS=delegated

```

5. Run Mimir Locally

Use docker-compose during development:

```bash

development/mimir-read-write-mode/compose-up.sh -d

```

This builds your local code and starts Mimir components. Tear down with:

```bash

development/mimir-read-write-mode/compose-down.sh

```

6. Manage Dependencies

Add or update dependencies:

```bash

Latest tagged release

go get example.com/some/module/pkg

Specific version

go get example.com/some/module/[email protected]

```

Tidy and commit:

```bash

go mod tidy

go mod vendor

git add go.mod go.sum vendor

git commit

```

7. Write Changelog Entries

Use the appropriate scope for your changes:

**[CHANGE]**: Behavioral changes without adding features or fixing bugs (e.g., renames, dependency updates)

**[FEATURE]**: New functionality added to the project

**[ENHANCEMENT]**: Improvements to existing functionality (optimizations, simpler syntax, better performance)

**[BUGFIX]**: Fixes for issues that align behavior with expected behavior

**Format:** End the first line with `#<PR>` where `<PR>` is the GitHub PR number:

```bash

./tools/github-next-pr-number.sh

```

**Ordering:** List entries as: `[CHANGE]`, `[FEATURE]`, `[ENHANCEMENT]`, `[BUGFIX]`

8. Add Error Catalog Entries

For user-visible errors:

1. Create a unique ID constant in `pkg/util/globalerror/user.go` (never change after release)

2. Use `globalerror` functions to generate error messages

3. Create a dedicated function if the error is returned from multiple places

4. Add a test comparing actual output with expected hard-coded string

5. Update the runbook in `docs/sources/mimir/manage/mimir-runbooks/_index.md`

9. Build Documentation

Compile and serve documentation locally:

```bash

make docs

```

Documentation is published to https://grafana.com/docs/mimir/latest/

See `how-to-write-documentation.md` for style and organization guidance.

10. Understand Memory Safety Patterns

⚠️ **Critical:** Mimir uses unsafe memory tricks for performance:

**Critical area:** In the distributor, strings must not outlive the `PushFunc` passed to `Handler`.

Important Notes

Resources