docs: Add release process details and workflow (#353)

placer14 · web-flow · commit c09eb8254d87 · 2021-02-16T17:52:47.000-05:00
* docs: Add release process details and workflow

* chore(docs): Extract detailed docs from README.md

* chore: Update process w latest feedback; Remove chglog Makefile directive

* chore: Apply go-mod manipulation recommendations to build process/docs

* fix: repair link after document was relocated
diff --git a/Makefile b/Makefile
@@ -66,7 +66,7 @@ lint:
 .PHONY: visor
 visor:
 	rm -f visor
-	go build $(GOFLAGS) -o visor .
+	go build $(GOFLAGS) -o visor -mod=readonly .
 
 BINS+=visor
 
@@ -84,10 +84,6 @@ dist-clean:
 	git submodule deinit --all -f
 .PHONY: dist-clean
 
-.PHONY: changelog
-changelog:
-	go run github.com/git-chglog/git-chglog/cmd/git-chglog -o CHANGELOG.md
-
 test-coverage:
 	VISOR_TEST_DB="postgres://postgres:password@localhost:5432/postgres?sslmode=disable" go test -coverprofile=coverage.out ./...
 .PHONY: test-coverage
diff --git a/README.md b/README.md
@@ -5,7 +5,6 @@ A component of [**Sentinel**](https://github.com/filecoin-project/sentinel), a c
 
 A **Visor** process collects _permanent_ Filecoin chain meterics from a [**Lotus**](https://github.com/filecoin-project/lotus/) daemon, and writes them to a [**TimescaleDB**](https://github.com/timescale/timescaledb) time-series and relational datastore.
 
-
 ## Getting Started
 
 Clone the repo and build the dependencies:
@@ -113,61 +112,17 @@ or by specifying the following flags:
   --jaeger-sampler-type=const jaeger-sampler-param=1
 ```
 
-## Deployment
-
-### Schema Migrations
-
-The database schema is versioned and every change requires a migration script to be executed. See [storage/migrations/README.md](storage/migrations/README.md) for more information.
-
-### Checking current schema version
-
-The visor `migrate` subcommand compares the **database schema version** to the **latest schema version** and reports any differences.
-It also verifies that the **database schema** matches the requirements of the models used by visor. It is safe to run and will not alter the database.
-
-Visor also verifies that the schema is compatible when the index or process subcommands are executed.
-
-### Migrating schema to latest version
-
-To migrate a database schema to the latest version, run:
-
-    visor migrate --latest
-
-Visor will only migrate a schema if it determines that it has exclusive access to the database. 
-
-Visor can also be configured to automatically migrate the database when indexing or processing by passing the `--allow-schema-migration` flag.
-
-### Reverting a schema migration
-
-To revert to an earlier version, run:
-
-    visor migrate --to <version>
-
-**WARNING: reverting a migration is very likely to lose data in tables and columns that are not present in the earlier version**
-
-
 ## Versioning and Releases
 
 Feature branches and master are designated as **unstable** which are internal-only development builds. 
 
 Periodically a build will be designated as **stable** and will be assigned a version number by tagging the repository
 using Semantic Versioning in the following format: `vMajor.Minor.Patch`.
- 
-### Release Process
-
-Between releases we keep track of notable changes in CHANGELOG.md.
-
-When we want to make a release we should update CHANGELOG.md to contain the release notes for the planned release in a section for
-the proposed release number. This update is the commit that will be tagged with as the actual release which ensures that each release
-contains a copy of it's own release notes. 
-
-We should also copy the release notes to the Github releases page, but CHANGELOG.md is the primary place to keep the release notes. 
-
-The release commit should be tagged with a signed tag:
-
-    git tag -s vx.x.x
-    git push --tags
 
+## Other Topics
 
+- [Release Management](docs/release_management.md)
+- [Schema/Migration Management](docs/migrations.md)
 
 ## Code of Conduct
 
diff --git a/docs/migrations.md b/docs/migrations.md
@@ -0,0 +1,29 @@
+# Schema Migrations
+
+The database schema is versioned and every change requires a migration script to be executed. See [../storage/migrations/README.md](../storage/migrations/README.md) for more information.
+
+## Checking current schema version
+
+The visor `migrate` subcommand compares the **database schema version** to the **latest schema version** and reports any differences.
+It also verifies that the **database schema** matches the requirements of the models used by visor. It is safe to run and will not alter the database.
+
+Visor also verifies that the schema is compatible when the index or process subcommands are executed.
+
+## Migrating schema to latest version
+
+To migrate a database schema to the latest version, run:
+
+    visor migrate --latest
+
+Visor will only migrate a schema if it determines that it has exclusive access to the database. 
+
+Visor can also be configured to automatically migrate the database when indexing or processing by passing the `--allow-schema-migration` flag.
+
+## Reverting a schema migration
+
+To revert to an earlier version, run:
+
+    visor migrate --to <version>
+
+**WARNING: reverting a migration is very likely to lose data in tables and columns that are not present in the earlier version**
+
diff --git a/docs/release_management.md b/docs/release_management.md
@@ -0,0 +1,61 @@
+# Release Process
+
+Between releases we keep track of notable changes in CHANGELOG.md.
+
+When we want to make a release we should update CHANGELOG.md to contain the release notes for the planned release in a section for
+the proposed release number. This update is the commit that will be tagged with as the actual release which ensures that each release
+contains a copy of it's own release notes. 
+
+We should also copy the release notes to the Github releases page, but CHANGELOG.md is the primary place to keep the release notes. 
+
+The release commit should be tagged with an annotated and signed tag:
+
+    git tag -asm vx.x.x vx.x.x
+    git push --tags
+
+A non-prescriptive example of the release process might look like the following:
+
+```sh
+git checkout master
+git pull                                # checkout/pull latest master
+git checkout -b vX.Y.Z(-rcN)-release          # create release branch
+vi CHANGELOG.md                         # update CHANGELOG.md
+go mod tidy                             # ensure tidy go.mod for release
+make visor                              # validate build
+git add CHANGELOG.md go.mod go.sum
+git commit -m "chore(docs): Update CHANGELOG for vX.Y.Z(-rcN)"
+                                        # commit CHANGELOG/go.mod updates
+git tag -asm vX.Y.Z-rcN vX.Y.Z(-rcN)    # create signed/annotated tag
+git push --tags origin vX.Y.Z(-rcN)-release
+                                        # push release branch and tags
+```
+
+NOTE: `sentinel-visor` pull requests prefer to be squash-merged into `master`, however considering this workflow tags release candidate within the release branch which we want to easily resolve in the repository's history, it is preferred to not squash and instead merge the release branch into `master`.
+
+
+## Updating CHANGELOG.md
+
+The format is a variant of [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) combined with categories from [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). The [github.com/git-chglog](https://github.com/git-chglog/git-chglog) utility assists us with maintaing CHANGELOG.md.
+
+The sections within each release have a preferred order which prioritizes by largest-user-impact-first: `Feat > Refactor > Fix > {Area-specific or Custom Sections} > Chore`
+
+Here is an example workflow of how CHANGELOG.md might be updated.
+
+```sh
+# checkout master and pull latest changes
+git checkout master
+git pull
+
+# output the CHANGELOG content for the next release (assuming next release is v0.5.0-rc1)
+go run github.com/git-chglog/git-chglog/cmd/git-chglog -o CHANGELOG_updates.md --next-tag v0.5.0-rc1
+
+# reconcile CHANGELOG_updates.md into CHANGELOG.md applying the preferred section order
+vi CHANGELOG*.md
+rm CHANGELOG_updates.md
+
+# commit changes
+git add CHANGELOG.md
+git commit -m 'chore(docs): Update CHANGELOG for v0.5.0-rc1'
+```
+
+Here is an [example of how the diff might look](https://github.com/filecoin-project/sentinel-visor/pull/326/commits/9536df9e39991a3b78013d1d1b36fef94562556d).
