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
2024-12-25 04:05:05 +03:00 · 2022-02-03 16:07:51 +03:00 · 2022-02-03 16:07:51 +03:00 · 5e2eff7f42
commit 5e2eff7f42
parent db716ee5b2
11 changed files with 78 additions and 35 deletions
--- 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
--- a/2
+++ b/2
@ -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
--- 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,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)
--- 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
--- 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
--- 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".
--- a/docs/img/pre-release-artifacts.png
+++ b/docs/img/pre-release-artifacts.png
--- a/docs/img/pre-release-ci.png
+++ b/docs/img/pre-release-ci.png
--- a/docs/img/pre-release.png
+++ b/docs/img/pre-release.png
--- 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
--- 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