Clarify Change-type and Changelog-entry in commit messages

[kbumsik]

Hi, I made a PR #1666. While making the PR I was struggle to figure out what to put in Change-type: in the commit message. I looked through CONTRIBUTING.md and the OpenEmbedded Guildline, but no one really explains them.

It would be nice if CONTRIBUTING.md explains about Change-type and Changelog-entry fields in detail, just like how OpenEmbedded describes Upstream-status.

[imrehg]

Very good point @kbumsik! The workflow of this repo can be a bit complicated, especially because a lot of things we are still figuring out with continuously re-evaluated experience, and processes can change, required tags can change, etc. But we should have a better baseline, explaining the tags and development/release flows for this repo. Thanks for bringing this up, we'll follow up soon.

[agherzan]

@kbumsik there are two paragraphs in https://github.com/balena-os/meta-balena/blob/master/CONTRIBUTING.md describing these footers. Have you read that section of the document?

[kbumsik]

@agherzan I read them but they don't intuitively describes those fields to contributors. It is a bit hard to see what maintainers usually expects from the contributors and what actually will happen using the fields.

It would be nice if CONTRIBUTING.md describes them more explicitly, roughly like this (the added description may be wrong, but I'm just suggesting how the format would look like.)

- Please refer to: [Yocto Contribution Guidelines] and try to use the commit log format as stated there. Example:
+ The commit log format is based on [Yocto Contribution Guidelines] with additional fields: `Change-type` and `Changelog-entry`
+ Example:
---
test.bb: I added a test

[Issue #01]

I'm going to explain here what my commit does in a way that history
would be useful.

+ Change-type: patch
+ Changelog-entry: Add test.bb
Signed-off-by: Joe Developer <joe.developer@example.com>
---

+ When a PR is merged the Balena CI system will tag a new build based on `Change-type` and `Changelog-entry`.
+ * `Change-type` (Required): `[patch|minor|major]`
+   * This follows [Semantic Versioning]. Contributors are expected to use `patch` for a PR
+ unless it is significant. The CI system will add a tag when PRs is merged.
+ * `Changelog-entry` (optional)
+   * The CI will add this value to CHANGELOG.md. If this field is omitted the subject line
+ of the commit log is used.

+ [Semantic Versioning](https://semver.org/#semantic-versioning-specification-semver)

We take advantage of a change log file to keep track of what was changed in a specific version. We used to handle that file manually by adding entries to it at every pull request. In order to avoid racing issues when pushing multiple PRs, we started to use versionist which will generate the change log at every release. This tool uses two footers from commit log: `Change-type` and `Changelog-entry`. Each PR needs to have at least one commit which will specify both of these two commit log footers. In this way, when a new release is handled, the next version will be computed based on `Change-type` and the entries in the change log file will be generated based on `Changelog-entry`.

In the common case where each PR addresses one specific task (issue, bug, feature etc.) the PR will contain a commit which will include `Change-type` and `Changelog-entry` in its commit log. Usually, but not necessary, this commit is the last one in the branch.

- `Change-type` is mandatory and, because meta-resin follows semver, can take one of the following values: patch, minor or major. `Changelog-entry` defaults to the subject line.

[agherzan]

That makes sense.