Preparing for 0.1.0.0 release (#129)

* MAde project name optional * Refined readme * Documented the release procedure * Updated versions * Refined the readme some more
typeable · Feb 3, 2022 · 5e2eff7 · 5e2eff7
1 parent db716ee
commit 5e2eff7
Show file tree

Hide file tree

Showing 11 changed files with 78 additions and 35 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,8 +2,8 @@
 
 `comparest` uses [PVP Versioning][1].
 
-## 0.0.0.0
+## 0.1.0.0
 
-* Initially created.
+* Initial release.
 
 [1]: https://pvp.haskell.org
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Aleksey Uymanov
+Copyright (c) 2021 Typeable
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -1,14 +1,35 @@
-# CompaREST
+# compaREST
 
-[![Hackage](https://img.shields.io/hackage/v/comparest.svg?logo=haskell)](https://hackage.haskell.org/package/comparest)
-[![Stackage Lts](http://stackage.org/package/comparest/badge/lts)](http://stackage.org/lts/package/comparest)
+[![Hackage](https://img.shields.io/hackage/v/compaREST.svg?logo=haskell)](https://hackage.haskell.org/package/comparest)
+[![Stackage Lts](http://stackage.org/package/compaREST/badge/lts)](http://stackage.org/lts/package/comparest)
 [![Stackage Nightly](http://stackage.org/package/comparest/badge/nightly)](http://stackage.org/nightly/package/comparest)
 [![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 Compatibility checker for OpenAPI
-# Quick Start Guide
 
-## Your situation
+## Using compaREST in Github Actions
+
+Add the following step to your  Github Actions workflow:
+
+```yaml
+- uses: typeable/comparest
+    if: ${{ github.event_name == 'pull_request' }}
+    with:
+      old: old-openapi.yaml
+      new: new-openapi.yaml
+```
+
+The `new` and `old` values should be paths to your OpenAPI specifications you want to compare.
+
+You will get something like this in your pull requests:
+
+![](docs/img/github-action-report.png)
+
+For more detail please see our [integration guide](docs/Integration_guide.md).
+
+## An example
+
+### Your situation
 
 You are developing a very important server with a REST API. You have clients who use your API that you do not control. Say, you are also developing a mobile app that uses your API and you can't force someone to update to the latest version. (Or you prefer not to for UX reasons.)
 
@@ -75,7 +96,7 @@ components:
         $ref: "#/components/schemas/Pet"
 ```
 
-## Evolving your product
+### Evolving your product
 
 Enthused over your initial success you hurry to release a new and improved version of your API and mobile app.
 
@@ -144,7 +165,7 @@ components:
 
 Looking at the very large and complex API description, you grow more and more concerned that your old mobile app might stop working when you update the server. But the spec is too large and too complex to reasonably assess this manually.
 
-## Assessing compatibility automatically
+### Assessing compatibility automatically
 
 Luckily, you have access to compaREST which can programmatically analyze your APIs and determine what, if anything, breaks compatibility and what doesn't.
 
@@ -158,15 +179,15 @@ Running this command will output a file `report.md`, containing the compatibilit
 
 > # Summary
 >
-> | [⚠️ Breaking changes](#breaking-changes) | [🙆 Non-breaking changes](#non-breaking-changes) | 🤷 Unsupported feature changes |
-> |------------------------------------------|-------------------------------------------------|-------------------------------|
-> | 5                                        | 6                                               | 0                             |
+> | [❌ Breaking changes](#breaking-changes) | [⚠️ Non-breaking changes](#non-breaking-changes) |
+> |------------------------------------------|--------------------------------------------------|
+> | 5                                        | 6                                                |
 >
-> # <span id="breaking-changes"></span>⚠️ Breaking changes
+> # <span id="breaking-changes"></span>❌ Breaking changes
 >
 > ## **GET** /pets
 >
-> ### 📱⬅️ JSON Response – 200
+> ### ⬅️☁️ JSON Response – 200
 >
 > #### `$[*].name(String)`
 >
@@ -176,7 +197,7 @@ Running this command will output a file `report.md`, containing the compatibilit
 >
 > ## **POST** /pets
 >
-> ### 📱➡️ JSON Request
+> ### ➡️☁️ JSON Request
 >
 > #### `$.weight`
 >
@@ -191,7 +212,7 @@ Running this command will output a file `report.md`, containing the compatibilit
 >
 > Value is now a multiple of 1.0.
 >
-> # <span id="non-breaking-changes"></span>🙆 Non-breaking changes
+> # <span id="non-breaking-changes"></span>⚠️ Non-breaking changes
 >
 > ## **GET** /pets
 >
@@ -203,7 +224,7 @@ Running this command will output a file `report.md`, containing the compatibilit
 >
 > Upper bound changed from 20.0 inclusive to 30.0 inclusive.
 >
-> ### 📱⬅️ JSON Response – 200
+> ### ⬅️☁️ JSON Response – 200
 >
 > #### `$[*].weight`
 >
@@ -220,7 +241,7 @@ Running this command will output a file `report.md`, containing the compatibilit
 >
 > ## **POST** /pets
 >
-> ### 📱➡️ JSON Request
+> ### ➡️☁️ JSON Request
 >
 > #### `$.name(String)`
 >
@@ -230,15 +251,17 @@ Running this command will output a file `report.md`, containing the compatibilit
 
 You now know exactly in what situations and in what way your 1.0 version of the app will break if you deploy your 1.1 version of the server.
 
-## Additional formats
+### Additional formats
 
 You can also produce a self-contained HTML report that you can open in your browser by simply omitting the file extension of the output file:
 
 ```bash
 docker run --rm -v $(pwd):/data:rw typeable/comparest --client /data/api-1.0.0.yaml --server /data/api-1.1.0.yaml --output /data/report
 ```
 
-# CLI docs
+## CLI docs
+
+For more detail please see our [user guide](docs/User_guide.md).
 
 ```
 Usage: comparest (-c|--client ARG) (-s|--server ARG)

diff --git a/action.yaml b/action.yaml
@@ -7,29 +7,30 @@ inputs:
     default: "${{ github.token }}"
     required: false
   repo:
-    description: The owner of the repo in which to post the comment.
+    description: The owner of the repo in which to post the results.
     default: "${{ github.repository }}"
     required: false
   project_name:
-    description: The name of the project to which the API pertains.
-    required: true
+    description: The name of the project to which the API pertains. Used to name the check. Useful when you have multiple APIs in the same repo.
+    required: false
+    default: ""
   footer:
-    description: A footer that can be appended to the comment.
+    description: A footer that can be appended to the check body.
     required: false
     default: ""
   old:
-    description: The path to old specification of the API.
+    description: The path to the old (client) specification of the API.
     required: true
   new:
-    description: The path to new specification of the API.
+    description: The path to new (server) specification of the API.
     required: true
   sha:
     description: The sha of the commit to post the check for.
     required: false
     default: "${{ github.event.pull_request.head.sha }}"
 runs:
   using: "docker"
-  image: "docker://typeable/comparest-github-action:latest"
+  image: "docker://typeable/comparest-github-action:0.1.0.0"
   env:
     GITHUB_TOKEN: "${{ inputs.GITHUB_TOKEN }}"
     REPO: "${{ inputs.repo }}"
@@ -44,4 +45,4 @@ runs:
 
 branding:
   icon: crosshair
-  color: gray-dark
+  color: blue
diff --git a/compaREST.cabal b/compaREST.cabal
@@ -1,6 +1,6 @@
 cabal-version:       2.4
 name:                compaREST
-version:             0.0.0.0
+version:             0.1.0.0
 synopsis:            Compatibility checker for OpenAPI
 description:         Compatibility checker for OpenAPI.
 license:             MIT

diff --git a/docs/Releasing.md b/docs/Releasing.md
@@ -0,0 +1,15 @@
+# The release procedure
+
+1. Update the version number everywhere:
+   1. Version in [compaREST.cabal](../compaREST.cabal)
+   2. Docker tag in [action.yaml](../action.yaml)
+   3. Set the version of unreleased changes in [CHANGELOG.md](../CHANGELOG.md)
+2. Publish!
+   1. Create a pre-release on GitHub:
+      ![](img/pre-release.png)
+   2. This will automatically start the release procedure. You can check the state of it in the "Actions" tab on GitHub:
+      ![](img/pre-release-ci.png)
+   3. If everything goes as planned, the release action should pass and all assets should be added to the release:
+      ![](img/pre-release-artifacts.png)
+   4. The new version should be automatically uploaded a release candidate to [Hackage](https://hackage.haskell.org/package/compaREST/candidates/). Make sure everything looks okay and publish it.
+   5. Go to the Releases tab on GitHub and edit the release to make it not a "pre-release".
diff --git a/docs/img/pre-release-artifacts.png b/docs/img/pre-release-artifacts.png
diff --git a/docs/img/pre-release-ci.png b/docs/img/pre-release-ci.png
diff --git a/docs/img/pre-release.png b/docs/img/pre-release.png
diff --git a/github-action/CompaREST/GitHub/API.hs b/github-action/CompaREST/GitHub/API.hs
@@ -29,7 +29,7 @@ postStatusProcessing = do
         repoOwner
         repoName
         Check
-          { checkName = mkName Proxy $ "compaREST – " <> projectName
+          { checkName = mkName Proxy checkName
           , checkSha = sha
           , checkDetailsURL = Nothing
           , checkExternalId = Nothing
@@ -60,7 +60,7 @@ postStatus x = do
         repoOwner
         repoName
         Check
-          { checkName = mkName Proxy $ "compaREST – " <> projectName
+          { checkName = mkName Proxy checkName
           , checkSha = sha
           , checkDetailsURL = Nothing
           , checkExternalId = Nothing

diff --git a/github-action/CompaREST/GitHub/Action/Config.hs b/github-action/CompaREST/GitHub/Action/Config.hs
@@ -8,13 +8,14 @@ import Data.Text (Text)
 import qualified Data.Text as T
 import qualified GitHub as GH
 
+import Data.Functor
 import System.Envy
 
 data Config = Config
   { githubToken :: GH.Auth
   , repoOwner :: GH.Name GH.Owner
   , repoName :: GH.Name GH.Repo
-  , projectName :: Text
+  , checkName :: Text
   , footerText :: Text
   , root :: FilePath
   , sha :: GH.Name GH.Commit
@@ -27,7 +28,10 @@ instance FromEnv Config where
       T.split (== '/') <$> env "REPO" >>= \case
         [owner, name] -> pure (owner, name)
         _ -> fail "malformed repo"
-    projectName <- env "PROJECT_NAME"
+    checkName <-
+      envMaybe "PROJECT_NAME" <&> \case
+        Just pName | not . T.null . T.strip $ pName -> "compaREST – " <> pName
+        _ -> "compaREST"
     footerText <- env "FOOTER"
     root <- envMaybe "ROOT" .!= "."
     sha <- env "SHA"
@@ -36,7 +40,7 @@ instance FromEnv Config where
         { githubToken = token
         , repoOwner = GH.mkName Proxy owner
         , repoName = GH.mkName Proxy repo
-        , projectName = projectName
+        , checkName = checkName
         , footerText = footerText
         , root = root
         , sha = GH.mkName Proxy sha