5e2eff7 · typeable/compaREST

git.iko.soy/typeable/compaREST

on master help sign in

Preparing for 0.1.0.0 release (#129)

5e2eff7iko5 years ago

CHANGELOG.md+2−2

compare with master

unifiedsplit

@@ -2,8 +2,8 @@

3`comparest` uses [PVP Versioning][1].

5−## 0.0.0.0

5+## 0.1.0.0

7−* Initially created.

7+* Initial release.

9[1]: https://pvp.haskell.org

LICENSE+1−1

@@ -1,6 +1,6 @@

1MIT License

5Permission is hereby granted, free of charge, to any person obtaining a copy

6of this software and associated documentation files (the "Software"), to deal

README.md+41−18

@@ -1,14 +1,35 @@

1−# CompaREST

1+# compaREST

3−[![Hackage](https://img.shields.io/hackage/v/comparest.svg?logo=haskell)](https://hackage.haskell.org/package/comparest)

3+[![Hackage](https://img.shields.io/hackage/v/compaREST.svg?logo=haskell)](https://hackage.haskell.org/package/comparest)

4−[![Stackage Lts](http://stackage.org/package/comparest/badge/lts)](http://stackage.org/lts/package/comparest)

4+[![Stackage Lts](http://stackage.org/package/compaREST/badge/lts)](http://stackage.org/lts/package/comparest)

5[![Stackage Nightly](http://stackage.org/package/comparest/badge/nightly)](http://stackage.org/nightly/package/comparest)

6[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

8Compatibility checker for OpenAPI

9−# Quick Start Guide

10+## Using compaREST in Github Actions

11+

12+Add the following step to your Github Actions workflow:

13+

14+```yaml

15+- uses: typeable/comparest

16+ if: ${{ github.event_name == 'pull_request' }}

17+ with:

18+ old: old-openapi.yaml

19+ new: new-openapi.yaml

20+```

21+

22+The `new` and `old` values should be paths to your OpenAPI specifications you want to compare.

23+

24+You will get something like this in your pull requests:

25+

26+![](docs/img/github-action-report.png)

27+

28+For more detail please see our [integration guide](docs/Integration_guide.md).

29+

30+## An example

31+

11−## Your situation

32+### Your situation

13You 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.)

34You 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:

75 $ref: "#/components/schemas/Pet"

96 $ref: "#/components/schemas/Pet"

76```

97```

78−## Evolving your product

99+### Evolving your product

100

80Enthused over your initial success you hurry to release a new and improved version of your API and mobile app.

101Enthused over your initial success you hurry to release a new and improved version of your API and mobile app.

102

@@ -144,7 +165,7 @@ components:

144

165

145Looking 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.

166Looking 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.

146

167

147−## Assessing compatibility automatically

168+### Assessing compatibility automatically

148

169

149Luckily, you have access to compaREST which can programmatically analyze your APIs and determine what, if anything, breaks compatibility and what doesn't.

170Luckily, you have access to compaREST which can programmatically analyze your APIs and determine what, if anything, breaks compatibility and what doesn't.

150

171

@@ -158,15 +179,15 @@ Running this command will output a file `report.md`, containing the compatibilit

158

179

159> # Summary

180> # Summary

160>

181>

161−> | [⚠️ Breaking changes](#breaking-changes) | [🙆 Non-breaking changes](#non-breaking-changes) | 🤷 Unsupported feature changes |

182+> | [❌ Breaking changes](#breaking-changes) | [⚠️ Non-breaking changes](#non-breaking-changes) |

162−> |------------------------------------------|-------------------------------------------------|-------------------------------|

183+> |------------------------------------------|--------------------------------------------------|

163−> | 5 | 6 | 0 |

184+> | 5 | 6 |

164>

185>

165−> # ⚠️ Breaking changes

186+> # ❌ Breaking changes

166>

187>

167> ## **GET** /pets

188> ## **GET** /pets

168>

189>

169−> ### 📱⬅️ JSON Response – 200

190+> ### ⬅️☁️ JSON Response – 200

170>

191>

171> #### `$[*].name(String)`

192> #### `$[*].name(String)`

172>

193>

@@ -176,7 +197,7 @@ Running this command will output a file `report.md`, containing the compatibilit

176>

197>

177> ## **POST** /pets

198> ## **POST** /pets

178>

199>

179−> ### 📱➡️ JSON Request

200+> ### ➡️☁️ JSON Request

180>

201>

181> #### `$.weight`

202> #### `$.weight`

182>

203>

@@ -191,7 +212,7 @@ Running this command will output a file `report.md`, containing the compatibilit

191>

212>

192> Value is now a multiple of 1.0.

213> Value is now a multiple of 1.0.

193>

214>

194−> # 🙆 Non-breaking changes

215+> # ⚠️ Non-breaking changes

195>

216>

196> ## **GET** /pets

217> ## **GET** /pets

197>

218>

@@ -203,7 +224,7 @@ Running this command will output a file `report.md`, containing the compatibilit

203>

224>

204> Upper bound changed from 20.0 inclusive to 30.0 inclusive.

225> Upper bound changed from 20.0 inclusive to 30.0 inclusive.

205>

226>

206−> ### 📱⬅️ JSON Response – 200

227+> ### ⬅️☁️ JSON Response – 200

207>

228>

208> #### `$[*].weight`

229> #### `$[*].weight`

209>

230>

@@ -220,7 +241,7 @@ Running this command will output a file `report.md`, containing the compatibilit

220>

241>

221> ## **POST** /pets

242> ## **POST** /pets

222>

243>

223−> ### 📱➡️ JSON Request

244+> ### ➡️☁️ JSON Request

224>

245>

225> #### `$.name(String)`

246> #### `$.name(String)`

226>

247>

@@ -230,7 +251,7 @@ Running this command will output a file `report.md`, containing the compatibilit

230

251

231You 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.

252You 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.

232

253

233−## Additional formats

254+### Additional formats

234

255

235You 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:

256You 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:

236

257

@@ -238,7 +259,9 @@ You can also produce a self-contained HTML report that you can open in your brow

238docker 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

259docker 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

239```

260```

240

261

241−# CLI docs

262+## CLI docs

263+

264+For more detail please see our [user guide](docs/User_guide.md).

242

265

243```

266```

244Usage: comparest (-c|--client ARG) (-s|--server ARG)

267Usage: comparest (-c|--client ARG) (-s|--server ARG)

action.yaml+9−8

@@ -7,21 +7,22 @@ inputs:

7 default: "${{ github.token }}"

8 required: false

9 repo:

10− description: The owner of the repo in which to post the comment.

10+ description: The owner of the repo in which to post the results.

11 default: "${{ github.repository }}"

12 required: false

13 project_name:

14− description: The name of the project to which the API pertains.

14+ 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.

15− required: true

15+ required: false

16+ default: ""

16 footer:

17 footer:

17− description: A footer that can be appended to the comment.

18+ description: A footer that can be appended to the check body.

18 required: false

19 required: false

19 default: ""

20 default: ""

20 old:

21 old:

21− description: The path to old specification of the API.

22+ description: The path to the old (client) specification of the API.

22 required: true

23 required: true

23 new:

24 new:

24− description: The path to new specification of the API.

25+ description: The path to new (server) specification of the API.

25 required: true

26 required: true

26 sha:

27 sha:

27 description: The sha of the commit to post the check for.

28 description: The sha of the commit to post the check for.

@@ -29,7 +30,7 @@ inputs:

29 default: "${{ github.event.pull_request.head.sha }}"

30 default: "${{ github.event.pull_request.head.sha }}"

30runs:

31runs:

31 using: "docker"

32 using: "docker"

32− image: "docker://typeable/comparest-github-action:latest"

33+ image: "docker://typeable/comparest-github-action:0.1.0.0"

33 env:

34 env:

34 GITHUB_TOKEN: "${{ inputs.GITHUB_TOKEN }}"

35 GITHUB_TOKEN: "${{ inputs.GITHUB_TOKEN }}"

35 REPO: "${{ inputs.repo }}"

36 REPO: "${{ inputs.repo }}"

@@ -44,4 +45,4 @@ runs:

45branding:

46branding:

46 icon: crosshair

47 icon: crosshair

47− color: gray-dark

48+ color: blue

compaREST.cabal+1−1

@@ -1,6 +1,6 @@

1cabal-version: 2.4

2name: compaREST

3−version: 0.0.0.0

3+version: 0.1.0.0

4synopsis: Compatibility checker for OpenAPI

5description: Compatibility checker for OpenAPI.

6license: MIT

docs/Releasing.mdnew file+15

@@ -0,0 +1,15 @@

1+# The release procedure

3+1. Update the version number everywhere:

4+ 1. Version in [compaREST.cabal](../compaREST.cabal)

5+ 2. Docker tag in [action.yaml](../action.yaml)

6+ 3. Set the version of unreleased changes in [CHANGELOG.md](../CHANGELOG.md)

7+2. Publish!

8+ 1. Create a pre-release on GitHub:

9+ ![](img/pre-release.png)

10+ 2. This will automatically start the release procedure. You can check the state of it in the "Actions" tab on GitHub:

11+ ![](img/pre-release-ci.png)

12+ 3. If everything goes as planned, the release action should pass and all assets should be added to the release:

13+ ![](img/pre-release-artifacts.png)

14+ 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.

15+ 5. Go to the Releases tab on GitHub and edit the release to make it not a "pre-release".

docs/img/pre-release-artifacts.pngnew file

Binary file not shown.

docs/img/pre-release-ci.pngnew file

Binary file not shown.

docs/img/pre-release.pngnew file

Binary file not shown.

github-action/CompaREST/GitHub/API.hs+2−2

@@ -29,7 +29,7 @@ postStatusProcessing = do

29 repoOwner

30 repoName

31 Check

32− { checkName = mkName Proxy $ "compaREST – " <> projectName

32+ { checkName = mkName Proxy checkName

33 , checkSha = sha

34 , checkDetailsURL = Nothing

35 , checkExternalId = Nothing

@@ -60,7 +60,7 @@ postStatus x = do

60 repoOwner

61 repoName

62 Check

63− { checkName = mkName Proxy $ "compaREST – " <> projectName

63+ { checkName = mkName Proxy checkName

64 , checkSha = sha

65 , checkDetailsURL = Nothing

66 , checkExternalId = Nothing

github-action/CompaREST/GitHub/Action/Config.hs+7−3

@@ -8,13 +8,14 @@ import Data.Text (Text)

8import qualified Data.Text as T

9import qualified GitHub as GH

11+import Data.Functor

11import System.Envy

12import System.Envy

13data Config = Config

14data Config = Config

14 { githubToken :: GH.Auth

15 { githubToken :: GH.Auth

15 , repoOwner :: GH.Name GH.Owner

16 , repoOwner :: GH.Name GH.Owner

16 , repoName :: GH.Name GH.Repo

17 , repoName :: GH.Name GH.Repo

17− , projectName :: Text

18+ , checkName :: Text

18 , footerText :: Text

19 , footerText :: Text

19 , root :: FilePath

20 , root :: FilePath

20 , sha :: GH.Name GH.Commit

21 , sha :: GH.Name GH.Commit

@@ -27,7 +28,10 @@ instance FromEnv Config where

27 T.split (== '/') <$> env "REPO" >>= \case

28 T.split (== '/') <$> env "REPO" >>= \case

28 [owner, name] -> pure (owner, name)

29 [owner, name] -> pure (owner, name)

29 _ -> fail "malformed repo"

30 _ -> fail "malformed repo"

31+ checkName <-

30− projectName <- env "PROJECT_NAME"

32+ envMaybe "PROJECT_NAME" <&> \case

33+ Just pName | not . T.null . T.strip $ pName -> "compaREST – " <> pName

34+ _ -> "compaREST"

31 footerText <- env "FOOTER"

35 footerText <- env "FOOTER"

32 root <- envMaybe "ROOT" .!= "."

36 root <- envMaybe "ROOT" .!= "."

33 sha <- env "SHA"

37 sha <- env "SHA"

@@ -36,7 +40,7 @@ instance FromEnv Config where

36 { githubToken = token

40 { githubToken = token

37 , repoOwner = GH.mkName Proxy owner

41 , repoOwner = GH.mkName Proxy owner

38 , repoName = GH.mkName Proxy repo

42 , repoName = GH.mkName Proxy repo

39− , projectName = projectName

43+ , checkName = checkName

40 , footerText = footerText

44 , footerText = footerText

41 , root = root

45 , root = root

42 , sha = GH.mkName Proxy sha

46 , sha = GH.mkName Proxy sha