diff --git a/README.md b/README.md index cff1687e..027424e7 100644 --- a/README.md +++ b/README.md @@ -135,13 +135,24 @@ Repository is open to external contributions. At this end please: 8. Push to the branch (`git push origin my-new-feature`) 9. Create a new Pull Request -### Delivering client libraries (internal use only) +## Client libraries release (internal use only) Described below is the procedure on how to deliver new client libraries: -1. Merge all the requested PRs in [onfido-openapi-spec](https://github.com/onfido/onfido-openapi-spec). -2. Manually trigger an [update-specs-and-client-libraries](https://github.com/onfido/onfido-openapi-spec/actions/workflows/update-specs-and-client-libraries.yaml) by clicking over the _Run workflow_ button -3. Select the type of change: +1. Merge all the requested PRs in [onfido-openapi-spec](https://github.com/onfido/onfido-openapi-spec) and wait for each workflow completion +2. Draft a new [onfido-openapi-spec](https://github.com/onfido/onfido-openapi-spec/releases) release using as _Release title_ last released version bumped accordingly to the type of change(s) (`vMAJOR.MINOR.PATCH`): + + | Type | Description | + | ------- | ------------------------------------------------------ | + | _Patch_ | changes not involving the OpenAPI spec (e.g. template) | + | _Minor_ | backward compatible changes to the OpenAPI spec | + | _Major_ | non-backward compatible changes to the OpenAPI spec | + +3. Use the same _Release title_ (including `v`) to create a tag +4. Review and possibly amend release notes generated by clicking on the appropriate button +5. Enable _Set as a pre-release_ and click on _Publish release_ +6. Trigger client libraries update by opening [update-specs-and-client-libraries](https://github.com/onfido/onfido-openapi-spec/actions/workflows/update-specs-and-client-libraries.yaml) and clicking over the _Run workflow_ button +7. Select the type of change: | Type | Description | | ----------- | --------------------------------------------------------------------------------------------------------------------- | @@ -150,15 +161,21 @@ Described below is the procedure on how to deliver new client libraries: | _Minor_ | backward compatible change to client library interface (e.g. new endpoint, new optional parameters) | | _Major_ | non-backward compatible change to client library interface (e.g. remove or change endpoint, new mandatory parameters) | -4. Select the libraries to update -5. A new PR will be created for each library (or overridden if already present) -6. Update _CHANGELOG_ files adding the new changes just below the new release number -7. Update tests if needed and merge each client-library PR -8. Ship a releases for each client library by: - - - setting tag and release name to _v0.0.0_ (replace _0.0.0_ with the actual version) - - using same contents from the CHANGELOG as release description - - making sure _Set as the latest release_ is enabled - - clicking on the _Publish release_ button - -9. Update [documentation](https://developers.onfido.com/guide/api-versioning-policy#client-libraries) with new client libraries version +8. Select the language(s) for which client library(-ies) should be refreshed +9. Press _Run workflow_, a new PR will be created for each library or overridden if already present (steps 6-9 might be repeated) +10. For one client library at the time, check if workflows are green or update tests as needed (they can't run in parallel) +11. Reference any additional change in auto-generated PR's description, merge the PR and wait for each workflow completion +12. Draft a new client library release, by first clicking on the _Releases_ button and _Draft a new release_ afterwards +13. Use the `release` field's value from `.release.json` file as _Release title_, including the `v` prefix +14. Create a tag with same value as the _Release title_ and click on the _Generate release notes_ button +15. Copy and paste release notes `What's changed` section from onfido-openapi-spec's release notes just below the _Refresh onfido-..._ line, by: + 1. Removing lines that doesn't apply to current library and reference to current language if present + 2. Indenting of two spaces each line and replacing the intial asterix (`*`) with dash (`-`) + 3. Removing `by...` (till the end of the line) for keeping `CHANGELOG.md` file clean +16. Any additional change manually performed in the library (e.g. updated tests, etc) needs to be added before the _Refresh onfido-..._ line, indented as usual (but using `-` as a list marker to make line appearing in the `CHANGELOG.md` file). +17. Click on _Publish release_ button +18. Check that workflows have been succesfully executed (by clicking on the _Action_ button) +19. Replace `Refresh onfido-...` line in Release notes with the more appropriate `Release based on...` line from `CHANGELOG.md` file +20. Repeat steps 12-19 for each client library to deliver +21. Open onfido-openapi-spec release created a few steps before, untick _Set as a pre-release_, tick _Set as the latest release_ and click on the _Update release_ button to save it +22. If client library is targetting a new API version, update the [documentation](https://developers.onfido.com/guide/api-versioning-policy#client-libraries) with new client libraries version