From 106fee5229baab93dcb6557bb300b3e26aecb79a Mon Sep 17 00:00:00 2001 From: Rune Morling Date: Fri, 1 Mar 2024 19:52:52 +0100 Subject: [PATCH] new package: Update example to subject: verb version (#496) * new package: Update example to subject: verb version With the monorepo, we use the `worklog.py` script and the GH UI, which shows the git shortlog at a glance. Therefore, the git shortlog messages should be as informative as possible so people don't have to go chasing the individual commit logs for relevant version information when looking for specific updates or summarising the weekly development churn in the forum sync notes. This commit changes the old (and no longer useful) "Initial inclusion" git shortlog message to a more useful "packagename: Add at version" git shortlog message. Note that we already require "packagename: Update to version" for the same reason. Signed-off-by: Rune Morling * update-existing-pkg: Add suitable shortlog examples The reasoning is the same as for the new packages. The git shortlog examples shown in this in this commit have already been proven useful in the context of the serpent recipe monorepo. --------- Signed-off-by: Rune Morling --- docs/packaging/creating-a-new-package.md | 2 +- .../packaging/updating-an-existing-package.md | 25 +++++++++++++++++-- 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/docs/packaging/creating-a-new-package.md b/docs/packaging/creating-a-new-package.md index f5b4fc04a..9c019ba0a 100644 --- a/docs/packaging/creating-a-new-package.md +++ b/docs/packaging/creating-a-new-package.md @@ -174,7 +174,7 @@ There should be a summary line (with the package name), a blank line, and then t Here is an example in our standard format (make sure to check the box in the checklist): ``` -tree: initial inclusion in the repository +tree: Add at v2.1.1 **Summary** diff --git a/docs/packaging/updating-an-existing-package.md b/docs/packaging/updating-an-existing-package.md index 7c493c342..b91303fe6 100644 --- a/docs/packaging/updating-an-existing-package.md +++ b/docs/packaging/updating-an-existing-package.md @@ -112,9 +112,17 @@ If all looks well, commit your changes. git commit ``` -### Commit message format for updated / bumped packages +## Commit message format -There should be a meaningful summary line (which starts with the package name), a blank line, and then the rest of the commit message. +With the switch to a single large package git repository, having a regular, easy-to-read, and standardized commit message format helps enable quick and efficient "at-a-glance" reading of git commit messages for packagers and Staff alike. + +Each commit message should consist of a meaningful summary line (which starts with the package name), a blank line, and then the rest of the commit message body. + +Note that `[NFC]` (listed in an example below) is an abbreviation for "No Functional Change". + +### Package update + +The following guidelines apply to the commit message body: - Bullet point lists should start with a dash. - Include a changelog with a brief list of updates from the upstream release notes, with no links or issue numbers. @@ -167,6 +175,19 @@ Full release notes: - [ ] Package was built and tested against unstable ``` +### Other commit message format examples + +In the cases where you are not updating a package to a new version, but simply applying a patch or fixing an existing version, the following commit messages are considered suitable: + +- Add the `homepage` metadata key: + - `package: Add homepage` +- Fix a packaging issue (including adding a patch to fix the package) + - `package: Fix (...)` +- Updating a README, [monitoring.yml file](monitoring.yml.md) or other stuff that does not directly _change_ the package, meaning the package release number didn't need a bump: + - `package: [NFC] Add README.md and monitoring.yml` + +As stated previously, `[NFC]` is an abbreviation of "No Functional Change". + For more information on suitable commit messages, please check the [tooling central documentation](https://github.com/solus-project/tooling-central/blob/master/README.rst#using-git). Next, you'll [submit a pull request for review](submitting-a-pull-request.md).