Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
158 lines (112 loc) · 5.42 KB

CONTRIBUTING.md

File metadata and controls

158 lines (112 loc) · 5.42 KB

Contributing

Thanks for taking the time to contribute!

Prerequisites

  • Go (see go.mod for the required version)

Setup

go mod download

Quick check

go run ./... --help

Local development

Run these before opening a PR:

gofmt -w $(git ls-files '*.go')
go vet ./...
go test ./...

Optional test layers

Use these opt-in commands when working on higher-level test coverage:

# Contract fixture decode checks
go test ./internal/niconico -run TestNicoDataContract -count=1

# Fuzz smoke run (short)
go test ./... -run=^$ -fuzz=Fuzz -fuzztime=10s

# E2E against real API (requires env var)
GO_NICO_LIST_E2E_USER_ID=<user-id> go test -tags=e2e ./internal/niconico -run TestGetVideoListE2E -count=1

# Bench baseline
go test ./internal/niconico -run=^$ -bench=BenchmarkNiconicoSort -benchmem -count=1

Third-party notices

If your change updates dependencies (changes go.mod / go.sum), run:

go mod tidy

If your change updates dependencies (changes go.mod / go.sum), also update:

bash scripts/gen-third-party-notices.sh

The script uses go-licenses (pinned in the script) and excludes test-only dependencies by default. Set GO_LICENSES_SAVE_PATH when you also want to save license texts to a directory. Requires bash and network access.

Project structure

  • main.go: bootstrap (version, cancelable context)
  • cmd/: CLI (flags, IO, validation, concurrency, exit codes)
  • internal/niconico/: domain logic (fetch, retry, sorting, types)

If the user-facing behavior changes, update README.md and docs/DESIGN.md. If the idea is not finalized yet, keep it out of docs/DESIGN.md and track it in a GitHub Issue. Keep WORKLOG.md local-only (git-ignored); do not commit it.

Docstring policy

  • Add docstrings for all non-test functions, methods, and types.
  • Start docstrings with the identifier name and keep them to a single sentence when possible.
  • Test functions (Test*, Benchmark*, Example*) are exempt.
  • Docstrings for const/var are optional; add them when intent is non-obvious.

Pull requests

  • Keep diffs small and focused.
  • Avoid adding new runtime dependencies without prior discussion.
  • Releases are performed by the maintainer.
  • CI runs on pull requests to master and pushes to master.
  • master is protected by a repository ruleset: changes must go through PRs, require conversation resolution, and pass the required go-ci status check.
  • CI checks generated-file drift (go mod tidy, go generate ./..., git diff --exit-code).
  • CI checks THIRD_PARTY_NOTICES.md drift (bash scripts/gen-third-party-notices.sh + diff check).
  • CI runs gofmt, go vet, go test, and go test -race.
  • Workflow actions are pinned by commit SHA. When upgrading action versions, update the pinned SHAs intentionally.
  • Include an auto-close keyword for related issues (e.g. Closes #123) in the PR body.
  • After addressing review feedback, request a Codex re-review in chat.
  • When using gh pr create, always use --body-file with .github/PULL_REQUEST_TEMPLATE.md to avoid literal \n in the description.

Release process

  1. Ensure master is green and up to date.
  2. If a versioned milestone is complete, release using the same version number.
  3. Create and push a version tag: vX.Y.Z.
    • Release tags are protected by a repository ruleset for refs/tags/v*.
  4. GitHub Actions runs the release workflow, verifying generated files (go mod tidy, go generate ./...) and running gofmt/go vet/go test/go test -race.
  5. The workflow regenerates THIRD_PARTY_NOTICES.md and fails if it is out of date.
  6. GoReleaser publishes the GitHub Release and uploads artifacts.
  7. After the release workflow succeeds, close the milestone.

Branch strategy

  • Use master as the only long-lived branch.
  • Create short-lived branches (e.g. feature/*) and merge via squash PR into master.
  • Tags for releases (vX.Y.Z) are cut from master.

Review criteria

  • CI must be green (generated files, third-party notices, gofmt, go vet, go test, go test -race).
  • If behavior changes, add or update tests; otherwise explain why in the PR.
  • If user-facing behavior changes, update README.md and docs/DESIGN.md.
  • If dependencies change, run go mod tidy and update THIRD_PARTY_NOTICES.md.
  • Breaking changes must be called out in the PR and docs.

Commit messages

  • Use type: summary (Conventional Commits style), e.g. fix: handle empty output.
  • Allowed types: feat, fix, docs, ci, chore, refactor, test, build.
  • Keep the summary on the first line.
  • For complex changes (multiple files or behavior changes), add a blank line, then details from line 3 onward.
  • When Codex is used, add the trailer line: AI-Assisted: Codex.

Example:

refactor: split client package

- move fetch/retry/sort into internal/niconico
- update tests to match new entry points

Reporting issues

Please use the issue templates and include:

  • your OS / shell
  • tool version (go-nico-list --version)
  • the exact command you ran
  • whether the issue is reproducible
  • expected vs actual behavior
  • any relevant logs (stderr or --logfile output)

Issue status labels

Use status labels to separate confirmed items from open questions:

  • confirmed: use when the owner decides the issue is confirmed.
  • needs-decision: use when the idea is not finalized yet.
  • needs-clarification: use when more information is required from the reporter, and remove it once clarified.