Set up release process (#71)

Sets up a goreleaser-based release process,
using changie to track unreleased changes and generate the chaneglog.

Adds a CONTRIBUTING file with instructions for contributors,
including the release instructions for maintainers.

.changes/header.tpl.md

@@ -0,0 +1,6 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
+and is generated by [Changie](https://github.com/miniscruff/changie).

.changie.yaml

@@ -0,0 +1,26 @@
+changesDir: .changes
+unreleasedDir: unreleased
+headerPath: header.tpl.md
+changelogPath: CHANGELOG.md
+versionExt: md
+versionFormat: '## {{.Version}} - {{.Time.Format "2006-01-02"}}'
+kindFormat: '### {{.Kind}}'
+changeFormat: '- {{.Body}}'
+kinds:
+- label: Added
+  auto: minor
+- label: Changed
+  auto: major
+- label: Deprecated
+  auto: minor
+- label: Removed
+  auto: major
+- label: Fixed
+  auto: patch
+- label: Security
+  auto: patch
+newlines:
+  afterChangelogHeader: 0
+  beforeChangelogVersion: 1
+  endOfVersion: 1
+envPrefix: CHANGIE_

.github/workflows/release.yml

@@ -0,0 +1,69 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release, including the 'v' prefix."
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        ref: ${{ inputs.version || github.ref }}
+
+    - name: Set up Go
+      uses: actions/setup-go@v5
+      with:
+        go-version: 1.22.x
+
+    - name: Install parse-changelog
+      uses: taiki-e/install-action@v2
+      with:
+        tool: [email protected]
+
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Determine version (tagged release)
+      if:  github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+      run: |
+        set -eou pipefail
+        REF=${{ github.ref }}
+        echo "VERSION=${REF#refs/tags/v}" >> "$GITHUB_ENV"
+    - name: Determine version (manual dispatch)
+      if:  github.event_name == 'workflow_dispatch'
+      run: |
+        echo "VERSION=${INPUT_VERSION#v}" >> "$GITHUB_ENV"
+      env:
+        INPUT_VERSION: ${{ inputs.version }}
+
+    - name: Extract changelog
+      run: |
+        parse-changelog CHANGELOG.md ${{ env.VERSION }} > ${{ github.workspace }}-CHANGELOG.txt
+        echo ::group::CHANGELOG
+        cat ${{ github.workspace }}-CHANGELOG.txt
+        echo ::endgroup::
+
+    - name: Release
+      uses: goreleaser/goreleaser-action@v5
+      with:
+        distribution: goreleaser
+        version: latest
+        args: release --clean --release-notes ${{ github.workspace }}-CHANGELOG.txt
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        GORELEASER_CURRENT_TAG: v${{ env.VERSION }}

.gitignore

@@ -1,3 +1,4 @@
 /bin
+/dist
 cover.out
 cover.html

.goreleaser.yml

@@ -0,0 +1,66 @@
+project_name: git-spice
+
+builds:
+  - env:
+      - CGO_ENABLED=0
+    main: .
+    binary: gs
+    goos: [darwin, linux]
+    goarch: [amd64, arm64]
+    goarm: [5, 6, 7]
+    ldflags: '-s -w -X main._version={{.Version}}'
+    flags:
+      - -trimpath
+
+archives:
+  - format: tar.gz
+    # uname compatible archive name.
+    name_template: >-
+      {{- .ProjectName }}.
+      {{- title .Os }}-
+      {{- if eq .Arch "amd64" }}x86_64
+      {{- else if eq .Arch "386" }}i386
+      {{- else }}{{ .Arch }}{{ end }}
+      {{- if .Arm }}v{{ .Arm }}{{ end }}
+
+# TODO: Enable when public
+# aurs:
+#   - name: git-spice-bin
+#     homepage: https://github.com/abhinav/git-spice
+#     description: "Stitch multiple Markdown files together into a single document."
+#     maintainers:
+#       - 'Abhinav Gupta <[email protected]>'
+#     license: "GPL-3.0"
+#     git_url: "ssh://[email protected]/git-spice-bin.git"
+#     skip_upload: auto
+#     private_key: '{{ .Env.AUR_KEY }}'
+#     package: |-
+#       install -Dm755 "./git-spice" "${pkgdir}/usr/bin/gs"
+#       install -Dm644 "./LICENSE" "${pkgdir}/usr/share/licenses/git-spice/LICENSE"
+#       install -Dm644 "./README.md" "${pkgdir}/usr/share/doc/git-spice/README.md"
+#       install -Dm644 "./CHANGELOG.md" "${pkgdir}/usr/share/doc/git-spice/CHANGELOG.md"
+#     commit_author:
+#       name: Abhinav Gupta
+#       email: [email protected]
+#
+# brews:
+#   - tap:
+#       owner: abhinav
+#       name: homebrew-tap
+#       token: "{{ .Env.HOMEBREW_TAP_GITHUB_TOKEN }}"
+#     commit_msg_template: "{{ .ProjectName }}: Update formula to {{ .Tag }}"
+#     commit_author:
+#       name: Abhinav Gupta
+#       email: [email protected]
+#     homepage: https://github.com/abhinav/git-spice
+#     description: "Stitch multiple Markdown files together into a single document."
+#     license: "GPL-3.0"
+#     skip_upload: auto
+#     test: |
+#       system "#{bin}/gs -version"
+
+checksum:
+  name_template: 'checksums.txt'
+
+snapshot:
+  name_template: "{{ incminor .Tag }}-dev"

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
+and is generated by [Changie](https://github.com/miniscruff/changie).
+
+
+No releases yet, this file will be updated when generating your first release.

CONTRIBUTING.md

@@ -0,0 +1,127 @@
+# Contributing
+
+We welcome contributes to the project,
+but please discuss features or significant changes
+in an issue before starting work on them.
+
+## Tools
+
+The following tools are needed to work on this project:
+
+- [Go](https://go.dev/):
+  The project is written in Go, so you need the Go compiler.
+- [Changie](https://changie.dev/):
+  We use Changie to manage the changelog.
+  You'll need this if you make user-facing changes.
+- [stitchmd](https://github.com/abhinav/stitchmd):
+  We use stitchmd to generate the README from files inside the doc/ directory.
+  You'll need this to edit the README.
+
+## Making contributions
+
+Follow the usual GitHub contribution process for making changes
+with the following notes:
+
+- Add changelog entries for user-facing changes with `changie new`.
+- If you edit documentation in doc/, run `make README.md` to update the README.
+  This requires stitchmd to be installed.
+- All commits must include meaningful commit messages.
+- Test new features and bug fixes.
+  If it doesn't have a test, it's not fixed.
+- Verify tests pass before submitting a pull request.
+
+### Stacking changes
+
+Unfortunately, it's not possible to submit a stack of pull requests
+to a repository that you do not have write access to.
+To work around this, we advise the following workflow
+to stack changes with git-spice for a contribution:
+
+1. Set your fork as the upstream remote for git-spice.
+
+    ```bash
+    gh repo fork --remote fork
+    gs repo init --remote fork
+    ```
+
+2. After preparing your stack of branches, submit them to your fork.
+
+    ```bash
+    gs stack submit
+    ```
+
+3. Create a pull request to the upstream repository with the top branch
+   of your stack.
+
+## Testing
+
+We use standard Go testing.
+
+```sh
+go test ./...
+```
+
+Use `make` to get a coverage report:
+
+```sh
+make cover
+```
+
+### Test scripts
+
+Tests for the project make heavy use of the
+[testscript package](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript).
+Tests scripts are stored inside the testdata/script directory.
+Read more about the test script format in the documentation of the package.
+
+## Releasing a new version
+
+(For maintainers only.)
+
+To release a new version, take the following steps:
+
+1. Create a new branch for the release. For example:
+
+    ```sh
+    VERSION=$(changie next minor)
+    gs branch create release-$VERSION -m "Release $VERSION"
+    ```
+
+2. Combine unreleased changes into a single Markdown document.
+
+    ```sh
+    changie batch $VERSION
+    ```
+
+3. Open up this file and verify everything looks good.
+
+    ```sh
+    $EDITOR .changes/$(changie latest).md
+    ```
+
+4. Merge these changes into CHANGELOG.md.
+
+    ```sh
+    changie merge
+    ```
+
+5. Commit the changes.
+
+    ```sh
+    git add CHANGELOG.md .changes
+    gs commit amend --no-edit
+    ```
+
+6. Create a pull request for the release.
+
+    ```sh
+    gh pr create
+    ```
+
+7. Once the pull request is merged, tag the release
+   either with the GitHub UI or with the following command:
+
+    ```sh
+    git tag v$VERSION
+    git push origin v$VERSION
+    ```

Makefile

@@ -16,8 +16,7 @@ STITCHMD_FLAGS ?= -o README.md -preface doc/preface.txt doc/SUMMARY.md
 
 GS = bin/gs
 MOCKGEN = bin/mockgen
-STITCHMD = bin/stitchmd
-TOOLS = $(MOCKGEN) $(GS) $(STITCHMD)
+TOOLS = $(MOCKGEN) $(GS)
 
 # Non-test Go files.
 GO_SRC_FILES = $(shell find . \
@@ -33,7 +32,7 @@ all: build lint test
 build: $(GS)
 
 .PHONY: lint
-lint: golangci-lint tidy-lint generate-lint stitchmd-lint
+lint: golangci-lint tidy-lint generate-lint
 
 .PHONY: generate
 generate: $(TOOLS)
@@ -52,10 +51,7 @@ cover:
 tidy:
 	go mod tidy
 
-.PHONY: stitchmd
-stitchmd: README.md
-
-README.md: $(STITCHMD) $(DOC_MD_FILES)
+README.md: $(DOC_MD_FILES)
 	stitchmd $(STITCHMD_FLAGS)
 
 .PHONY: golangci-lint
@@ -76,13 +72,13 @@ generate-lint: $(TOOLS)
 		git diff --exit-code || \
 		(echo "'go generate' changed files" && false)
 
-# stitchmd-lint depends on generate-lint
+# readme-lint depends on generate-lint
 # because that updates doc/reference.md.
 # In the future, that can be make-managed.
-.PHONE: stitchmd-lint
-stitchmd-lint: $(STITCHMD) generate-lint
-	@echo "[lint] stitchmd"
-	@DIFF=$$($(STITCHMD) -diff $(STITCHMD_FLAGS)); \
+.PHONE: readme-lint
+readme-lint: generate-lint
+	@echo "[lint] readme"
+	@DIFF=$$(stitchmd -diff $(STITCHMD_FLAGS)); \
 	if [[ -n "$$DIFF" ]]; then \
 		echo "stitchmd would change README:"; \
 		echo "$$DIFF"; \
@@ -94,6 +90,3 @@ $(GS): $(GO_SRC_FILES)
 
 $(MOCKGEN): go.mod
 	go install go.uber.org/mock/mockgen
-
-$(STITCHMD): go.mod
-	go install go.abhg.dev/stitchmd