Change commit messages in all repositories

[wtrocki]

Currently our commits have:

chore(openapi) ...

I think we should include name of the component inside the commit and use fix.
This way we can ensure that we will get meaningful changelog.

fix(kafka-admin) ...

[wtrocki]

Created for discussion after getting feedback that there is no clear way what PR's should have commit changed and how to flag changes etc. I think change should be added to code PR's (OpenAPI updates can be still chore)

[wtrocki]

CC @rkpattnaik780

[craicoverflow]

I think we should include name of the component inside the commit and use fix.

What if it is a feat? Maybe the commit type should match whatever thenew semver type is?

I think change should be added to code PRs (OpenAPI updates can be still chore)

I agree with this.

[wtrocki]

I think feat or fix are easier to change than chore as PR's are merged and they are not appearing in changelog.
What we want at minimum is information about:

• What APIs were regenerated for that version and what are the same (Especially for golang that has all apis in one bundle)
• If there are breaking changes in any of those apis
• Distinct between fix and feat (but that is lower importance IMHO than two above)

If I read changelog later changing from fix to feat is easy - problem is if there is no entries for entire release :D

[craicoverflow]

I think using a tool like https://github.com/Tufin/oasdiff would come in handy here.

I tried to include it into the PR created through the Update OpenAPI specification workflow but it did not seem to work.

https://github.com/redhat-developer/app-services-sdk-go/blob/main/.github/workflows/update_openapi.yaml#L85

[craicoverflow]

chore(all): re-generate OpenAPI client(s)

A problem is that our SDK generation workflow generates for all SDKs, so technically it is challenging to provide granular commit messages when there are multiple SDKs updated, where one could have a fix, one could have a feat and one could have a breaking change. Do you just go with the most major change?

[wtrocki]

It does generate all SDK's but in practice it only generates single one due to single OpenAPI change so never had problem with this specifically.

Problems I have right now:

1. Commit messages and changelogs are very unformalized across all SDK's.
   We can document them but still this brings some challenges.
   Having information in changelog what API was changed and if it was breaking is enough for my point of view.
   This problem is going to be addressed in this issue

2. Golang SDK is missing changelog. Will be resolved by Add changelog for releases and in the main repository. #166

After all is resolved we would have very good way to let people know about changes without sending specific emails etc.

[wtrocki]

After checking I think we could keep original message in the openapi file (and use generation as form of keeping repo up to date with openapi files.

[craicoverflow]

I actually think conventional commits are not suitable as a changelog for the SDKs as they are limited to the size of the commit message which really does not tell you enough of what has changed in the OpenAPI.

Tufin/oasdiff can be used to generate a PR description, which will be helpful for the maintainer to review. We can also use a diff tool to generate a changelog between two tags.

[wtrocki]

Amazing idea. I was wondering if possible to use second lines from commits in gitchangelog when adding support to js-sdk

[craicoverflow]

Actually I retract that - this will focus too much on the OpenAPI differences, but users will not even care about this since they are using the SDK only. I will try again to generate an OpenAPI diff and use it to create better commits.

[wtrocki]

@craicoverflow another idea worth checking

Import commits from source repo into description.
Including PR that caused change (always single PR)
Then we can use this to manually transform changelog to sdk level

[craicoverflow]

Yeah maybe - but I imagine source repo commits might focus more on low level details and might not transcribe well to the changelog for an SDK - which should be understandable with little context of the change details.

[wtrocki]

Yes. Feel free to do what you feel is best.