Skip to content

MAINTAINERS.md

Latest commit

 

History

History
156 lines (122 loc) · 6.6 KB

MAINTAINERS.md

File metadata and controls

156 lines (122 loc) · 6.6 KB

Maintainers guide

Operational notes for the people who run this repository. External contributors should read CONTRIBUTING.md instead.

Required GitHub repository settings

These settings enforce the fork → pull request → squash-merge flow that CONTRIBUTING.md describes. Apply them once when the repository is created (or before going public), and re-verify after any change to the protected-branch policy.

1. Branch protection on main

Settings → Branches → Add rule → Branch name pattern: main

Setting Value Why
Require a pull request before merging on Direct pushes to main are forbidden — every change must come through a PR
Required approvals 1 (or 2 when more than one maintainer is active) At least one maintainer reviews every PR
Dismiss stale pull request approvals when new commits are pushed on Force re-review after rework
Require review from Code Owners on if CODEOWNERS is added Auto-route to the right reviewer
Require status checks to pass before merging on Block merges that fail CI
Status checks (required) build-and-test (ubuntu-latest / Go 1.25), cross-build (linux/amd64), cross-build (linux/arm64), cross-build (darwin/arm64), cross-build (windows/amd64) All matrix jobs from .github/workflows/ci.yml
Require branches to be up to date before merging on Refuse merge of stale branches; contributor rebases first
Require conversation resolution before merging on All review threads must be resolved
Require signed commits optional Enable if signing is part of the maintainer policy
Require linear history on Combined with squash-only merge keeps main linear
Restrict who can push to matching branches maintainers team only Backstop in case the "require PR" rule is ever disabled
Allow force pushes off Force-push to main is never the right answer
Allow deletions off main cannot be deleted

External contributors do not appear in the Restrict who can push allowlist. With the require PR rule above, the only way for them to land a change is to fork, push to their fork, and open a PR — which is what we want.

2. Pull request settings

Settings → General → Pull Requests

  • Allow merge commits: off
  • Allow squash merging: on (default merge button)
  • Allow rebase merging: off
  • Default to PR title for squash merge commit messages: on
  • Default to pull request description for squash merge commit messages: on
  • Automatically delete head branches after merge: on

These settings keep main linear, give every commit on main a PR-shaped title and body, and keep the branch list clean.

3. Actions / CI permissions

Settings → Actions → General

  • Workflow permissions: Read repository contents permission (least privilege; CI does not push or write)
  • Allow GitHub Actions to create and approve pull requests: off
  • Fork pull request workflows from outside collaborators: Require approval for first-time contributors (prevents a malicious fork-PR from running CI without review)

4. Vulnerability reporting

Settings → Security & analysis

  • Private vulnerability reporting: on (used by SECURITY.md)
  • Dependency graph + Dependabot alerts: on
  • Dependabot security updates: on

5. Discussion of CODEOWNERS

CODEOWNERS is not required for fork+PR enforcement (the branch protection rule already covers that), but adding it routes review notifications. A minimal CODEOWNERS once a maintainer team is defined:

# .github/CODEOWNERS
*               @Postmath/ncode-sdk-maintainers
/pdf/           @Postmath/ncode-sdk-maintainers
/pattern/neolab @Postmath/ncode-sdk-maintainers
/tools/ncode-cli @Postmath/ncode-sdk-maintainers

Until a maintainer team exists, leave CODEOWNERS absent rather than pointing at individuals — turnover is a documentation hazard.

Review workflow

For each incoming PR:

  1. Triage within 5 business days. Add labels (bug, enhancement, breaking-change, docs, ci, etc.). If the PR sits in Draft, leave a short note acknowledging it and move on.
  2. Sanity-check CI. All required checks must be green before substantive review. If CI is red, ask the contributor to fix before maintainer time is spent.
  3. Review against CONTRIBUTING.md scope, conventions, and public-API stability rules. Reviewer's job is policy compliance, not typo hunting.
  4. Squash-merge when approved. The PR title becomes the commit subject; trim the description to the why before merging.
  5. Tag breaking changes in the merge commit body with BREAKING CHANGE: so release notes pick them up.

Releases and tags

The SDK uses semantic versioning. Pre-1.0 (the current state) means the public surface is still movable; minor bumps may include breaking changes as long as they are documented.

To cut a release:

  1. Confirm main is green on CI.

  2. Decide the version: bump vMAJOR.MINOR.PATCH per semver.org.

  3. Update CHANGELOG.md (create on first release) — list user-visible changes since the previous tag, grouped under Added, Changed, Fixed, Removed, Deprecated, Security, Breaking.

  4. Tag from main:

    git checkout main
git pull --ff-only
git tag -a v0.1.0 -m "v0.1.0"
git push origin v0.1.0

    Annotated tags only — pkg.go.dev and go get index annotated tags more reliably than lightweight ones.

  5. Create a GitHub Release pinned to the tag. Paste the relevant CHANGELOG.md section as the release body.

  6. Do not publish pre-built binaries that link pdf/ (i.e. that statically include MuPDF) without a NOTICE file documenting the AGPL-3.0 obligation. Source-only releases via go get / pkg.go.dev do not have this constraint.

Dependency hygiene

  • go-fitz (MuPDF) and pdfcpu are the heavy dependencies. Bumping them across major versions warrants a cycle-spanning PR with a manual smoke test (examples/publish with NeoLAB credentials — see CONTRIBUTING.md for the offline test loop too).
  • Dependabot PRs land like any other contribution — they go through CI and review, not auto-merge.
  • Adding a new dependency requires a maintainer issue first.

Out-of-band tasks

  • Yearly licence-notice review — confirm the third-party notice in LICENSE still reflects current dependencies (especially the go-fitz / MuPDF AGPL-3.0 disclosure).
  • Yearly contributor list refresh — README.md Contributors section is hand-maintained.