Skip to content

Development

Jump to bottom
Brandon Young edited this page Nov 5, 2026 · 1 revision

Development

Build and test

make build          # bin/notion-md-sync
make test           # go test ./...
make lint           # golangci-lint run
make fmt            # go fmt ./...
make clean
make dev-setup      # install development tools

Without make:

go build -o notion-md-sync ./cmd/notion-md-sync
go test ./...
go test -run TestName ./pkg/sync
go test -coverprofile=coverage.out ./... && go tool cover -html=coverage.out

Where things are

Package What
pkg/notion Notion API client (Notion-Version: 2026-03-11), block diff, kept-block rules
pkg/sync Sync engine, Markdown ↔ block converter, folder layout, CSV export, conflicts
pkg/markdown Frontmatter parsing
pkg/staging add / reset / status
pkg/watcher watch
pkg/tui Terminal UI (Bubble Tea)
pkg/cli Cobra commands
internal/notionfake In-memory Notion API used by tests

Tests don't need a Notion account. pkg/notion/fake_server_test.go and internal/notionfake stand in for the API, and pkg/sync/memnotion_test.go is an in-memory client for engine scenarios. If you change the converter, add a case to TestConverter_RoundTripIsStable.

CI

  • CI (ci.yml) runs on pushes and pull requests to main: gofmt, vet, tests with the race detector, and golangci-lint.
  • Release (release.yml) runs on v* tags: builds Linux, macOS and Windows binaries for amd64 and arm64, and creates the GitHub release.

Releasing

  1. Write the notes in docs/releases/vX.Y.Z.md.
  2. Tag and push: 
    git tag vX.Y.Z
git push origin vX.Y.Z
  3. GitHub Actions builds the binaries and publishes the release using those notes.

Contributing

See CONTRIBUTING.md. In short: fork, branch, keep go test ./... and golangci-lint run clean, open a pull request.

notion-md-sync

Clone this wiki locally