📖 5 min read (~ 1100 words).

Maintainer's Guide

TL;DR

This guide covers the practices common to all go-openapi repositories: CI/CD workflows, release procedures, dependency management, and tooling.

Individual projects may document their repo structure and project-specific details in their own docs/MAINTAINERS.md.

Repo configuration

All go-openapi repositories follow the same baseline configuration:

  • Default branch: master
  • Protected branches: master
  • Branch protection rules:
    • require pull requests and approval
    • required status checks:
      • DCO (simple email sign-off)
      • Lint
      • All tests completed
  • Auto-merge enabled (used for dependabot updates and other auto-merged PR’s, e.g. contributors update)

Continuous Integration

CI workflows use a shared workflows setup defined in go-openapi/ci-workflows and shared GitHub Actions in go-openapi/gh-actions.

This approach gives us:

  • custom actions for installing vetted versions of tools
  • better control over updates
  • less noisy dependabot updates across the board (a single update per shared workflow instead of one per repository for every single action update)

Code Quality checks

NOTES

codefactor inherits roles from github. There is no need to create a dedicated account.

The codefactor app is installed at the organization level (github.com/go-openapi).

There is no special token to setup in github for CI usage.

Testing

  • Test reports

  • Test coverage reports

  • Fuzz testing

    • Fuzz tests are handled separately by CI and may reuse a cached version of the fuzzing corpus. At this moment, cache may not be shared between feature branches or feature branch and master. The minimized corpus produced on failure is uploaded as an artifact and should be added manually to testdata/fuzz/....

Coverage threshold status is informative and not blocking. This is because the thresholds are difficult to tune and codecov oftentimes reports false negatives or may fail to upload coverage.

Some repositories may have additional integration tests beyond the standard unit test suite (e.g. go-openapi/strfmt, go-openapi/analysis).

All tests across go-openapi use our fork of stretchr/testify: github.com/go-openapi/testify. This allows for minimal test dependencies.

NOTES

codecov inherits roles from github. There is no need to create a dedicated account. However, there is only 1 maintainer allowed to be the admin of the organization on codecov with their free plan.

The codecov app is installed at the organization level (github.com/go-openapi).

There is no special token to setup in github for CI usage. A organization-level token used to upload coverage and test reports is managed at codecov: no setup is required on github.

Automated updates

  • dependabot

    • configuration: .github/dependabot.yaml in each repository

    Principle:

    • dependabot applies updates and security patches to the github-actions and golang ecosystems.
    • all updates from “trusted” dependencies (github actions, golang.org packages, go-openapi packages) are auto-merged if they successfully pass CI.

  • go version updates

    Principle:

    • we support the 2 latest minor versions of the go compiler (stable, oldstable)
    • go.mod should be updated (manually) whenever there is a new go minor release (e.g. every 6 months).

    This means that our projects always have a 6 months lag to enforce new features from the go compiler.

    However, new features of go may be used with a “go:build” tag: this allows users of the newer version to benefit the new feature while users still running with oldstable use another version that still builds.

  • contributors

    • a CONTRIBUTORS.md file is updated weekly, with all-time contributors to the repository
    • the github-actions[bot] posts a pull request to do that automatically
    • at this moment, this pull request is not auto-approved/auto-merged (bot cannot approve its own PRs)

Vulnerability scanners

There are 3 complementary scanners - obviously, there is some overlap, but each has a different focus.

None of these tools require an additional account or token.

Github CodeQL configuration is set to “Advanced”, so we may collect a CI status for this check (e.g. for badges).

Scanners run on every commit to master and at least once a week.

Reports are centralized in github security reports for code scanning tools.

Releases

Single module repos

A bump release workflow can be triggered from the github actions UI to cut a release with a few clicks.

The release process is minimalist:

  • push a semver tag (i.e v{major}.{minor}.{patch}) to the master branch.

  • the CI handles this to generate a github release with release notes

  • release notes generator: git-cliff https://git-cliff.org/docs/

  • configuration: the .cliff.toml is defined as a shared configuration on remote repo ci-workflows/.cliff.toml

Commits from maintainers are preferably PGP-signed.

Tags are preferably PGP-signed.

We want our releases to show as “verified” on github.

The tag message introduces the release notes (e.g. a summary of this release).

The release notes generator does not assume that commits are necessarily “conventional commits”.

Mono-repos with multiple modules

The release process is slightly different because we need to update cross-module dependencies before pushing a tag.

A bump release workflow (mono-repo) can be triggered from the github actions UI to cut a release with a few clicks.

It works with the same input as the one for single module repos, and first creates a PR (auto-merged) that updates the different go.mod files before pushing the desired git tag.

Commits and tags pushed by the workflow bot are PGP-signed (“go-openapi[bot]”).

Standard documentation files

Every go-openapi repository should include:

  • CONTRIBUTING.md guidelines
  • DCO.md terms for first-time contributors to read
  • CODE_OF_CONDUCT.md
  • SECURITY.md policy: how to report vulnerabilities privately
  • LICENSE terms
  • NOTICE on supplementary license terms (when applicable: original authors, copied code etc)
  • MAINTAINERS.md: this document, plus possible repo-specific instructions

Reference documentation (released):

  • pkg.go.dev hosts the Go reference documentation for each package (see the individual package URLs in the project table)

AI coding agent support

Recent improvements across go-openapi repositories add documentation to support AI coding agents and improve their productivity. The goal is to guide agents so that code and contributions stay aligned with our standards.

Each repository may include the following instruction files:

  • AGENTS.md – top-level agent instructions (often a symlink to .github/copilot-instructions.md)
  • .github/copilot-instructions.md – instructions for GitHub Copilot
  • .claude/CLAUDE.md – instructions for Claude Code, with detailed rules under .claude/rules/

These files typically cover:

  • Go code conventions and formatting (license headers, supported Go versions, etc.)
  • Linting standards (golangci-lint configuration and //nolint policy)
  • Testing requirements (test framework, coverage targets, fuzz tests)
  • Contribution rules (DCO sign-off, commit hygiene, PR quality expectations)
  • GitHub workflow conventions (YAML style, action pinning, secret handling)

See for example the jsonpointer repository for a reference setup.