pgEdge · jason-lynch · Dec 1, 2025 · Nov 30, 2025 · Nov 30, 2025
diff --git a/.changie.yaml b/.changie.yaml
@@ -6,6 +6,12 @@ versionExt: md
 versionFormat: '## {{.Version}} - {{.Time.Format "2006-01-02"}}'
 kindFormat: '### {{.Kind}}'
 changeFormat: '- {{.Body}}'
+newlines:
+  afterChangelogHeader: 1
+  afterKind: 1
+  afterChangelogVersion: 1
+  beforeKind: 1
+  endOfVersion: 1
 kinds:
   - label: Added
   - label: Changed

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,37 +1,56 @@
 # Changelog
+
 ## v0.5.1 - 2025-11-24
+
 ### Added
+
 - Added support for Postgres 16.11, 17.7, and 18.1.
+
 ### Changed
+
 - Default Postgres version to 18.1.
+
 ### Removed
+
 - Removed unsupported Postgres 17.5.
+
 ### Fixed
+
 - Fixed a bug where database instance state would not be properly set to unknown when status updates were missed for two consecutive monitor intervals.
 - Fixed a bug where port validation would prevent databases from updating.
 
 ## v0.5.0 - 2025-11-04
+
 ### Added
+
 - Added support for Postgres 18.0.
 - Added a new "client-only" Etcd mode to enable larger clusters and clusters with an even number of hosts.
 - Added access logging.
 - Added ability to run the Control Plane on Docker Swarm worker nodes.
+
 ### Changed
+
 - Moved the cluster ID configuration setting to be an optional parameter on the init-cluster endpoint.
 - Changed the default behavior when adding a node. Instead of initializing to an empty state, new nodes will always be populated from an existing node unless the new node has a `restore_config`.
 - Changed the shape of the return type for `list-hosts`, `restart-instance`, `stop-instance`, and `start-instance`.
 - Renamed Etcd server and client configuration options.
+
 ### Removed
+
 - Removed cohort ID from host API endpoints.
+
 ### Fixed
+
 - Fixed unknown host status and missing component status in host API endpoints.
 - Fixed a bug that prevented users from using Service Accounts for pgBackRest credentials in GCS.
 - Fixed missing replication sets after restoring from backup.
 - Fixed incorrect response in `update-database` when a non-existent host ID is specified.
 - Fixed a bug with scheduled instance restarts.
 
 ## v0.4.0 - 2025-10-06
+
 ### Added
+
 - Introduced stop-instance and start-instance APIs to allow users to manually trigger a stop/start of a specific Postgres instance.
 - Added support for adding new database nodes with zero downtime.
 - Added stopped state for instances
@@ -41,7 +60,9 @@
 - Added support for mTLS to the Control Plane API via user-managed certificates.
 - Implemented the "get host" and "get cluster" endpoints.
 - Added Failover support via the control plane API
+
 ### Changed
+
 - Switched to the new images from github.com/pgEdge/postgres-images.
 - Added the postgres minor version to the `postgres_version` fields in the database and host APIs.
 - Changed the database creation behavior so that the first host in `host_ids` gets the primary instance for a node.
@@ -51,25 +72,35 @@
 - Changed MQTT interface in client library to take an endpoint. This removes the need to generate unique client IDs per server. Callers are responsible for calling `Connect()` and `Disconnect()` on the endpoint.
 - Enable fast basebackup for new nodes. This noticeably speeds up the creation process for a node with replicas.
 - Changed patroni configuration to use pg_rewind for faster recovery after a switchover.
+
 ### Fixed
+
 - Fixed join cluster timeouts when requests were submitted to a member other than the raft leader.
 - Ensure that join and init cluster calls only return once the server is ready to take requests. Any errors during the initialization process will now be returned to callers.
 
 ## v0.3.0 - 2025-08-19
+
 ### Added
+
 - Added ability to override 'database modifiable state' check via `force` parameters on several endpoints.
 - Added a `client` package that wraps the generated client code in a friendlier interface.
+
 ### Changed
+
 - Merged separate Go modules into single top-level `github.com/pgEdge/control-plane` module.
+
 ### Fixed
+
 - Fixed high CPU usage from Etcd after recovering from some network partition scenarios.
 - Fixed error in restore database workflow when the request is submitted to a host that is not running the target instance.
 - Fixed client-side validation errors from missing enum values in our generated client code.
 - Fixed timing issue where a new database operation could not be started immediately after the task was marked as completed.
 - Fixed a bug in the restore database workflow where, sometimes, the restore would start before Postgres had finished shutting down.
 
 ## v0.2.0 - 2025-07-22
+
 ### Added
+
 - Tasks and task logs for every database operation.
 - `parent_id`, `node_name`, `host_id`, and `instance_id` fields to task API entities.
 - Support for performing database backups to a mounted file system using the posix repository type via pgBackRest.
@@ -82,7 +113,9 @@
 - Add support to disable direct database port exposure on the host in Swarm deployments.
 - `remove-host` endpoint.
 - Added scheduling functionality in the Control Plane.
+
 ### Changed
+
 - Create, update, delete, and restore API responses to include task information.
 - `initiate-database-backup` operation name to `backup-database-node`
 - Task logs entries from log lines to structured log entries.
@@ -94,13 +127,19 @@
 - Updated `pgedge` images to 5.0.0-1
 - Moved pgEdge and Control Plane images to ghcr.io
 - `control-plane` base image from `scratch` to `gcr.io/distroless/static-debian12` for CA certificates
+
 ### Removed
+
 - Unused fields from API specification.
+
 ### Fixed
+
 - Delay when resuming workflows after a restart.
 - Database operation errors when instance IPs change after restarting.
 - Method to determine default IPv4 address to always return IPv4.
 
 ## v0.1.0 - 2025-05-28
+
 ### Added
+
 - Release process to publish Docker images for the Control Plane server.
diff --git a/Makefile b/Makefile
@@ -208,14 +208,12 @@ endif
 	$(MAKE) -C api generate
 	VERSION=$(VERSION) yq -i \
 		'.extra.control_plane_version = strenv(VERSION)' mkdocs.yml
+	cp CHANGELOG.md docs/changelog.md
 	git checkout -b release/$(VERSION)
-	git add api changes CHANGELOG.md mkdocs.yml
+	git add api changes docs CHANGELOG.md mkdocs.yml
 	git -c core.pager='' diff --staged
 	git -c core.pager='' diff --staged --compact-summary
 	@echo -n "Are you sure? [y/N] " && read ans && [ $${ans:-N} == y ]
-	# copy/add changelog here in case formatting fix were required
-	cp CHANGELOG.md docs/changelog.md
-	git add docs/changelog.md
 	git commit -m "build(release): bump version to $(VERSION)"
 	git push origin release/$(VERSION)
 	git tag $(VERSION)-rc.1

diff --git a/changes/v0.1.0.md b/changes/v0.1.0.md
@@ -1,3 +1,5 @@
 ## v0.1.0 - 2025-05-28
+
 ### Added
+
 - Release process to publish Docker images for the Control Plane server.
diff --git a/changes/v0.2.0.md b/changes/v0.2.0.md
@@ -1,5 +1,7 @@
 ## v0.2.0 - 2025-07-22
+
 ### Added
+
 - Tasks and task logs for every database operation.
 - `parent_id`, `node_name`, `host_id`, and `instance_id` fields to task API entities.
 - Support for performing database backups to a mounted file system using the posix repository type via pgBackRest.
@@ -12,7 +14,9 @@
 - Add support to disable direct database port exposure on the host in Swarm deployments.
 - `remove-host` endpoint.
 - Added scheduling functionality in the Control Plane.
+
 ### Changed
+
 - Create, update, delete, and restore API responses to include task information.
 - `initiate-database-backup` operation name to `backup-database-node`
 - Task logs entries from log lines to structured log entries.
@@ -24,9 +28,13 @@
 - Updated `pgedge` images to 5.0.0-1
 - Moved pgEdge and Control Plane images to ghcr.io
 - `control-plane` base image from `scratch` to `gcr.io/distroless/static-debian12` for CA certificates
+
 ### Removed
+
 - Unused fields from API specification.
+
 ### Fixed
+
 - Delay when resuming workflows after a restart.
 - Database operation errors when instance IPs change after restarting.
-- Method to determine default IPv4 address to always return IPv4.
+- Method to determine default IPv4 address to always return IPv4.
diff --git a/changes/v0.3.0.md b/changes/v0.3.0.md
@@ -1,12 +1,18 @@
 ## v0.3.0 - 2025-08-19
+
 ### Added
+
 - Added ability to override 'database modifiable state' check via `force` parameters on several endpoints.
 - Added a `client` package that wraps the generated client code in a friendlier interface.
+
 ### Changed
+
 - Merged separate Go modules into single top-level `github.com/pgEdge/control-plane` module.
+
 ### Fixed
+
 - Fixed high CPU usage from Etcd after recovering from some network partition scenarios.
 - Fixed error in restore database workflow when the request is submitted to a host that is not running the target instance.
 - Fixed client-side validation errors from missing enum values in our generated client code.
 - Fixed timing issue where a new database operation could not be started immediately after the task was marked as completed.
-- Fixed a bug in the restore database workflow where, sometimes, the restore would start before Postgres had finished shutting down.
+- Fixed a bug in the restore database workflow where, sometimes, the restore would start before Postgres had finished shutting down.
diff --git a/changes/v0.4.0.md b/changes/v0.4.0.md
@@ -1,5 +1,7 @@
 ## v0.4.0 - 2025-10-06
+
 ### Added
+
 - Introduced stop-instance and start-instance APIs to allow users to manually trigger a stop/start of a specific Postgres instance.
 - Added support for adding new database nodes with zero downtime.
 - Added stopped state for instances
@@ -9,7 +11,9 @@
 - Added support for mTLS to the Control Plane API via user-managed certificates.
 - Implemented the "get host" and "get cluster" endpoints.
 - Added Failover support via the control plane API
+
 ### Changed
+
 - Switched to the new images from github.com/pgEdge/postgres-images.
 - Added the postgres minor version to the `postgres_version` fields in the database and host APIs.
 - Changed the database creation behavior so that the first host in `host_ids` gets the primary instance for a node.
@@ -19,6 +23,8 @@
 - Changed MQTT interface in client library to take an endpoint. This removes the need to generate unique client IDs per server. Callers are responsible for calling `Connect()` and `Disconnect()` on the endpoint.
 - Enable fast basebackup for new nodes. This noticeably speeds up the creation process for a node with replicas.
 - Changed patroni configuration to use pg_rewind for faster recovery after a switchover.
+
 ### Fixed
+
 - Fixed join cluster timeouts when requests were submitted to a member other than the raft leader.
-- Ensure that join and init cluster calls only return once the server is ready to take requests. Any errors during the initialization process will now be returned to callers.
+- Ensure that join and init cluster calls only return once the server is ready to take requests. Any errors during the initialization process will now be returned to callers.
diff --git a/changes/v0.5.0.md b/changes/v0.5.0.md
@@ -1,19 +1,27 @@
 ## v0.5.0 - 2025-11-04
+
 ### Added
+
 - Added support for Postgres 18.0.
 - Added a new "client-only" Etcd mode to enable larger clusters and clusters with an even number of hosts.
 - Added access logging.
 - Added ability to run the Control Plane on Docker Swarm worker nodes.
+
 ### Changed
+
 - Moved the cluster ID configuration setting to be an optional parameter on the init-cluster endpoint.
 - Changed the default behavior when adding a node. Instead of initializing to an empty state, new nodes will always be populated from an existing node unless the new node has a `restore_config`.
 - Changed the shape of the return type for `list-hosts`, `restart-instance`, `stop-instance`, and `start-instance`.
 - Renamed Etcd server and client configuration options.
+
 ### Removed
+
 - Removed cohort ID from host API endpoints.
+
 ### Fixed
+
 - Fixed unknown host status and missing component status in host API endpoints.
 - Fixed a bug that prevented users from using Service Accounts for pgBackRest credentials in GCS.
 - Fixed missing replication sets after restoring from backup.
 - Fixed incorrect response in `update-database` when a non-existent host ID is specified.
-- Fixed a bug with scheduled instance restarts.
+- Fixed a bug with scheduled instance restarts.
diff --git a/changes/v0.5.1.md b/changes/v0.5.1.md
@@ -1,10 +1,18 @@
 ## v0.5.1 - 2025-11-24
+
 ### Added
+
 - Added support for Postgres 16.11, 17.7, and 18.1.
+
 ### Changed
+
 - Default Postgres version to 18.1.
+
 ### Removed
+
 - Removed unsupported Postgres 17.5.
+
 ### Fixed
+
 - Fixed a bug where database instance state would not be properly set to unknown when status updates were missed for two consecutive monitor intervals.
-- Fixed a bug where port validation would prevent databases from updating.
+- Fixed a bug where port validation would prevent databases from updating.