Update client libraries release procedure in README.md

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