diff --git a/CHANGELOG.md b/CHANGELOG.md
index cd6f0dc4..1875239a 100644
--- 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
index 7cf5bb97..25a7d054 100644
--- 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
index f21938c8..c6082034 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,35 @@
-# CompaREST
+# compaREST
-[](https://hackage.haskell.org/package/comparest)
-[](http://stackage.org/lts/package/comparest)
+[](https://hackage.haskell.org/package/comparest)
+[](http://stackage.org/lts/package/comparest)
[](http://stackage.org/nightly/package/comparest)
[](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:
+
+
+
+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 |
>
-> # ⚠️ Breaking changes
+> # ❌ 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.
>
-> # 🙆 Non-breaking changes
+> # ⚠️ 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,7 +251,7 @@ 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:
@@ -238,7 +259,9 @@ You can also produce a self-contained HTML report that you can open in your brow
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
index 9593793d..ac33f181 100644
--- a/action.yaml
+++ b/action.yaml
@@ -7,21 +7,22 @@ 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.
@@ -29,7 +30,7 @@ inputs:
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
index b317a74f..3c98b45c 100644
--- 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
new file mode 100644
index 00000000..20147a9a
--- /dev/null
+++ 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:
+ 
+ 2. This will automatically start the release procedure. You can check the state of it in the "Actions" tab on GitHub:
+ 
+ 3. If everything goes as planned, the release action should pass and all assets should be added to the release:
+ 
+ 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
new file mode 100644
index 00000000..ea9fd6e0
Binary files /dev/null and b/docs/img/pre-release-artifacts.png differ
diff --git a/docs/img/pre-release-ci.png b/docs/img/pre-release-ci.png
new file mode 100644
index 00000000..505f6d2a
Binary files /dev/null and b/docs/img/pre-release-ci.png differ
diff --git a/docs/img/pre-release.png b/docs/img/pre-release.png
new file mode 100644
index 00000000..a12ea79c
Binary files /dev/null and b/docs/img/pre-release.png differ
diff --git a/github-action/CompaREST/GitHub/API.hs b/github-action/CompaREST/GitHub/API.hs
index d8161a79..ab0a43f7 100644
--- 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
index 3478554e..b22ce759 100644
--- 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