Merge #372

372: Add a changelog and more automation for releases r=rishflab a=thomaseizinger

Tested workflow runs can be seen here:

- Drafting a new release via `workflow_dispatch`: https://github.com/thomaseizinger/xmr-btc-swap/actions/runs/681852142
- The created PR: https://github.com/thomaseizinger/xmr-btc-swap/pull/11
- The workflow running as a result of merging the PR: https://github.com/thomaseizinger/xmr-btc-swap/actions/runs/681855693
- The release created from that workflow: https://github.com/thomaseizinger/xmr-btc-swap/releases/tag/0.4.0

Fixes #364.

Co-authored-by: Thomas Eizinger <thomas@eizinger.io>

.dprintrc.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://dprint.dev/schemas/v0.json",
+  "projectType": "openSource",
+  "incremental": true,
+  "markdown": {
+  },
+  "includes": ["**/*.{md}"],
+  "excludes": [
+
+  ],
+  "plugins": [
+    "https://plugins.dprint.dev/markdown-0.6.1.wasm"
+  ]
+}

.github/workflows/README.md

@@ -0,0 +1,47 @@
+# Workflow documentation
+
+## `ci.yml`
+
+Defines the Continuous Integration workflow for merging into the `master` branch.
+
+## Releases
+
+The workflows in this repository automate various things around releases.
+The functionality is composed in such a way that a human can easily start the workflow at various points, i.e. instead of being an all-or-nothing automation, we can step in where necessary.
+
+### Preview release
+
+We have a rolling tag `preview` that always points to HEAD of `master`.
+The [preview-release.yml](./preview-release.yml) workflow moves this tag to latest HEAD every time a PR gets merged.
+It also creates a corresponding GitHub "pre-release".
+
+### Building release binaries and attaching changelog
+
+Whenever a new release is created, the [build-release-binaries.yml](build-release-binaries.yml) workflow will build the `swap` and `asb` binaries in release mode and attach them to the release as artifacts.
+
+Because this workflow is triggered on every release, it works for:
+
+- automatically created `preview` releases
+- releases created through the GitHub web interface
+- releases created by merging release branches into `master`
+
+### Making a new release
+
+To create a new release, one has to:
+
+- Create a new branch
+- Update the version in the [swap/Cargo.toml](../../swap/Cargo.toml) manifest file
+- Update the Changelog (convert `Unreleased` section to a release)
+- Make a commit
+- Open and merge a PR
+- Create a release from the resulting merge commit
+
+To avoid errors in this process, we can automate it.
+The [draft-new-release.yml](./draft-new-release.yml) workflow allows the user specify the desired version and the workflow will then open a PR that automates the above.
+
+The created branch will follow the naming of `release/X.Y.Z` for the given version.
+
+Any time a PR with such a branch name is merged, the [create-release.yml](./create-release.yml) workflow kicks in and creates a new release based on the resulting merge commit.
+
+Because these two workflows are de-coupled, a user is free to create a release branch themselves if they wish to do so.
+They may also side-step both of these workflows by creating a release manually using the Github web interface.

.github/workflows/build-release-binaries.yml

@@ -1,12 +1,12 @@
-name: "Release swap and asb"
+name: "Build swap and asb release binaries"
 
 on:
   release:
     types: [created]
 
 jobs:
-  release:
-    name: Release swap
+  build_binaries:
+    name: Build swap and asb binaries
     strategy:
       matrix:
         include:

.github/workflows/ci.yml

@@ -1,12 +1,12 @@
 name: CI
 
 on:
-  pull_request:
+  pull_request: # Need to run on pull-requests, otherwise PRs from forks don't run
   push:
     branches:
-      - 'staging'
-      - 'trying'
-      - 'master'
+      - 'staging' # Bors uses this branch
+      - 'trying' # Bors uses this branch
+      - 'master' # Always build head of master for the badge in the README
 
 jobs:
   static_analysis:
@@ -31,6 +31,9 @@ jobs:
       - name: Check code formatting
         run: cargo fmt --all -- --check
 
+      - name: Check markdown formatting
+        uses: dprint/check@v1
+
       - name: Run clippy with default features
         run: cargo clippy --workspace --all-targets -- -D warnings
 

.github/workflows/create-release.yml

@@ -0,0 +1,41 @@
+name: "Create release"
+
+on:
+  pull_request:
+    types:
+      - closed
+
+jobs:
+  create_release:
+    name: Create from merged release branch
+    if: github.event.pull_request.merged == true && startsWith(github.event.pull_request.head.ref, 'release/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Extract version from branch name
+        id: extract-version
+        shell: python
+        run: |
+          branch_name = "${{ github.event.pull_request.head.ref }}"
+          version = branch_name.split("/")[1]
+
+          print(f"::set-output name=version::{version}")
+
+      - name: Extract changelog section for release
+        id: changelog
+        uses: coditory/changelog-parser@v1
+        with:
+          version: ${{ steps.extract-version.outputs.version }}
+
+      - name: Create release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.BOTTY_GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ steps.extract-version.outputs.version }}
+          release_name: ${{ steps.extract-version.outputs.version }}
+          draft: false
+          prerelease: false
+          body: ${{ steps.changelog.outputs.description }}
+          commitish: ${{ github.event.pull_request.merge_commit_sha }}

.github/workflows/draft-new-release.yml

@@ -0,0 +1,70 @@
+name: "Draft new release"
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'The new version in X.Y.Z format.'
+        required: true
+
+jobs:
+  draft-new-release:
+    name: "Draft a new release"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          token: ${{ secrets.BOTTY_GITHUB_TOKEN }}
+
+      - name: Create release branch
+        run: git checkout -b release/${{ github.event.inputs.version }}
+
+      - name: Update changelog
+        uses: thomaseizinger/keep-a-changelog-new-release@1.2.1
+        with:
+          version: ${{ github.event.inputs.version }}
+          changelogPath: CHANGELOG.md
+
+      - name: Initialize mandatory git config
+        run: |
+          git config user.name "${{ secrets.BOTTY_NAME }}"
+          git config user.email ${{ secrets.BOTTY_EMAIL }}
+
+      - name: Bump version in Cargo.toml
+        uses: thomaseizinger/set-crate-version@1.0.0
+        with:
+          version: ${{ github.event.inputs.version }}
+          manifest: swap/Cargo.toml
+
+      - name: Update Cargo.lock
+        run: cargo update --workspace
+
+      - name: Commit changelog and manifest files
+        id: make-commit
+        run: |
+          curl -fsSL https://dprint.dev/install.sh | sh
+          /home/runner/.dprint/bin/dprint fmt
+
+          git add CHANGELOG.md Cargo.lock swap/Cargo.toml
+          git commit --message "Prepare release ${{ github.event.inputs.version }}"
+
+          echo "::set-output name=commit::$(git rev-parse HEAD)"
+
+      - name: Push new branch
+        run: git push origin release/${{ github.event.inputs.version }} --force
+
+      - name: Create pull request
+        uses: thomaseizinger/create-pull-request@1.0.0
+        with:
+          GITHUB_TOKEN: ${{ secrets.BOTTY_GITHUB_TOKEN }}
+          head: release/${{ github.event.inputs.version }}
+          base: master
+          title: Release version ${{ github.event.inputs.version }}
+          reviewers: ${{ github.actor }}
+          body: |
+            Hi @${{ github.actor }}!
+
+            This PR was created in response to a manual trigger of the release workflow here: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}.
+            I've updated the changelog and bumped the versions in the manifest files in this commit: ${{ steps.make-commit.outputs.commit }}.
+
+            Merging this PR will create a GitHub release and upload any assets that are created as part of the release build.

.github/workflows/preview-release.yml

@@ -21,6 +21,12 @@ jobs:
       - name: Give GitHub some time to process the deletion, otherwise our release shows up as draft. Sigh.
         run: sleep 10
 
+      - name: Extract changelog section for release
+        id: changelog
+        uses: coditory/changelog-parser@v1
+        with:
+          version: unreleased
+
       - name: Create 'preview' release
         uses: actions/create-release@v1
         env:
@@ -30,4 +36,4 @@ jobs:
           release_name: preview
           draft: false
           prerelease: true
-          body: Preview release of `asb` and `swap`
+          body: ${{ steps.changelog.outputs.description }}

CHANGELOG.md

@@ -0,0 +1,14 @@
+# 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/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- A changelog file.
+
+[Unreleased]: https://github.com/comit-network/xmr-btc-swap/compare/v0.3...HEAD

README.md

@@ -1,5 +1,4 @@
-XMR to BTC Atomic Swap
-======================
+# XMR to BTC Atomic Swap
 
 This repository hosts an MVP for atomically swapping BTC to XMR.
 It implements the protocol described in section 3 of [this](https://arxiv.org/abs/2101.12332) paper.

monero-harness/README.md

@@ -1,12 +1,10 @@
-Monero Harness
-==============
+# Monero Harness
 
 Provides an implementation of `testcontainers::Image` for a monero image to run
 `monerod` and `monero-wallet-rpc` in a docker container.
 
 Also provides two standalone JSON RPC clients, one each for `monerod` and `monero-wallet-rpc`.
 
-Example Usage
--------------
+## Example Usage
 
 Please see `tests/*` for example usage.

monero-rpc/README.md

@@ -1,12 +1,10 @@
-Monero Harness
-==============
+# Monero Harness
 
 Provides an implementation of `testcontainers::Image` for a monero image to run
 `monerod` and `monero-wallet-rpc` in a docker container.
 
 Also provides two standalone JSON RPC clients, one each for `monerod` and `monero-wallet-rpc`.
 
-Example Usage
--------------
+## Example Usage
 
 Please see `tests/*` for example usage.

tokio-tar/README.md

@@ -83,10 +83,10 @@ fn main() {
 
 This project is licensed under either of
 
- * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
-   http://www.apache.org/licenses/LICENSE-2.0)
- * MIT license ([LICENSE-MIT](LICENSE-MIT) or
-   http://opensource.org/licenses/MIT)
+- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+  http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or
+  http://opensource.org/licenses/MIT)
 
 at your option.