docs: Update commit message guidelines (#1175)

Also adds commitlint checks to verify the guidelines.

JIRA: CPOUI5FOUNDATION-1152

Author: matz3

.github/workflows/commitlint.yml

@@ -0,0 +1,21 @@
+name: Commit Message Linting
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  commitlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: wagoid/commitlint-github-action@b948419dd99f3fd78a6548d48f94e3df7f6bf3ed # v6.2.1

.husky/commit-msg

@@ -0,0 +1 @@
+npm run lint:commit -- --edit "$1" # Lint currently edited commit message

README.md

@@ -8,6 +8,9 @@
 [![OpenUI5 Community Slack (#tooling channel)](https://img.shields.io/badge/slack-join-44cc11.svg)](https://ui5-slack-invite.cfapps.eu10.hana.ondemand.com)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)
 
+This repository contains the current **development state** of the upcoming UI5 CLI v5 release.  
+Note that previous versions (up to v4) are maintained in [dedicated repositories](https://github.com/UI5/cli/tree/v4?tab=readme-ov-file#modules).
+
 > [UI5 CLI v4](https://ui5.github.io/cli/v4) is the latest and stable version 🎉
 >
 > [UI5 CLI v3](https://ui5.github.io/cli/v3) is a stable version and in maintenance mode 🚢

commitlint.config.mjs

@@ -0,0 +1,53 @@
+export default {
+	extends: [
+		"@commitlint/config-conventional",
+	],
+	rules: {
+		"type-enum": [
+			2,
+			"always",
+			[
+				"build",
+				"ci",
+				"deps",
+				"docs",
+				"feat",
+				"fix",
+				"perf",
+				"refactor",
+				"release",
+				"revert",
+				"style",
+				"test",
+			],
+		],
+		"body-max-line-length": [2, "always", 160],
+		"footer-max-line-length": [0],
+		"subject-case": [
+			2, "always",
+			["sentence-case", "start-case", "pascal-case"],
+		],
+		// Limit scope to package names and special cases
+		"scope-enum": [
+			2,
+			"always",
+			[
+				// Package names
+				"builder",
+				"cli",
+				"documentation",
+				"fs",
+				"logger",
+				"project",
+				"server",
+				// Special scope for dev dependencies
+				"deps-dev"
+			]
+		],
+		"scope-case": [2, "always", "lowercase"],
+	},
+	ignores: [
+		// Ignore release commits, as their subject doesn't start with an uppercase letter
+		(message) => message.startsWith("release: v"),
+	],
+};

docs/Guidelines.md

@@ -6,55 +6,97 @@ You may also find an ESLint integration for your favorite IDE [here](https://esl
 ## Testing
 Unit testing is based on the [ava](https://github.com/avajs/ava) test-framework. You can run all tests using `npm test` (this is what our CI will do for all pull requests).
 
-During development, you might want to use `npm run unit` or `npm run unit-watch` (re-runs tests automatically after file changes) to quickly execute all unit tests and see whether your change just broke one of them. 😉
+During development, you might want to use `npm run unit` or `npm run unit-watch` (re-runs tests automatically after file changes; only available within a specific package) to quickly execute all unit tests and see whether your change just broke one of them. 😉
 
 ## Git Guidelines
 ### No Merge Commits
 Please use [rebase instead of merge](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) to update a branch to the latest main. This helps keeping a clean commit history in the project.
 
 ### Commit Message Style
-#### Commit Summary
-The commit summary is the first line of the commit message.
 
-- It should be **50-70 characters** long.
-- It must be **prefixed** by `[FIX]`, `[FEATURE]` or `[INTERNAL]` accordingly, followed by the name of the component or module which was the main subject of the change.
-    + Use `[FIX]` for bugfixes.
-    + Use `[FEATURE]` for new features / enhancements.
-    + Use `[BREAKING]` for breaking / incompatible changes.  
-      _**Note:** The commit body of a breaking change should also include a paragraph starting with `BREAKING CHANGE:`.  
-      This paragraph will be highlighted in the changelog._
-    + Use `[DEPENDENCY]` for dependency updates that should be mentioned in the changelog.
-    + Use `[INTERNAL]` for all other changes (e.g. refactorings, documentation, etc.). These changes will not be listed in the changelog.
-    + Exceptions are changes created by automated processes like releases or dependency updates
-- It must not contain `[` or `]` anywhere but in the prefix.
-- It shall be written in **imperative present tense** (as recommended by [Git](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project))  
-    + Examples: Instead of *"Adding tests for"* or *"I added tests for"* use *"Add tests for"* or *"Add feature xy"*.
+This project uses the [Conventional Commits specification](https://www.conventionalcommits.org/) to ensure a consistent way of dealing with commit messages.
 
-#### Commit Body
-After the commit summary there should be an empty line followed by the commit body.
+#### Structure
 
-- Describe the intention and reasoning of the change
-- If a change fixes an issue reported on GitHub, add the following line to the commit message:
-    + `Fixes: #<issueNumber>` (e.g. `Fixes: #42`)
-- Breaking changes should include a paragraph starting with `BREAKING CHANGE:`. This paragraph will be highlighted in the changelog.
+```
+type(scope): Description
+```
+
+- **Type (required)**: Every commit message must start with a lowercase `type`. The project has defined a set of [valid types](../commitlint.config.mjs#L10)
+- **Scope (conditional)**: Required only for types that appear in the public changelog: `feat`, `fix`, `perf`, `deps`, and `revert`. The scope must be the package folder name (e.g. `cli`, `builder`, `fs`, `logger`, `project`, `server`, `documentation`). No other scopes are allowed (except `build(deps-dev)` for dev dependencies).
+- **Description (required)**: Must follow Sentence Case style. Only the first word and proper nouns are written in uppercase.
+
+#### Dependencies
+
+- Use `deps(scope)` for productive dependency updates that are relevant for end users
+- Use `build(deps-dev)` for development dependency updates
+
+#### Breaking Changes
+
+Breaking changes should follow the [Conventional Commits specification](https://www.conventionalcommits.org/):
+- Add `!` after the type/scope: `feat(cli)!: Remove deprecated command`
+- Include `BREAKING CHANGE:` in the commit footer with details about the change
 
-#### Example
+#### Commitlint Rules
+
+The following rules are enforced by commitlint:
+- Valid commit types are enforced (see [commitlint.config.mjs](../commitlint.config.mjs))
+- When using a scope, it must be one of: package names (`builder`, `cli`, `documentation`, `fs`, `logger`, `project`, `server`) or `deps-dev` for development dependencies
+- Commit messages must follow sentence case for the description
+
+**Important**: Commitlint cannot automatically enforce that scopes are required only for public changelog types. Please manually ensure that:
+- `feat`, `fix`, `perf`, `deps`, `revert` commits always include a package scope
+- Other commit types should not include a scope (except `build(deps-dev)` for dev dependencies) 
+
+#### Examples
+
+**Features and fixes:**
+```
+feat(cli): Add "versions" command
+fix(fs): Correctly handle paths containing non-ASCII characters on Windows
+perf(builder): Improve bundle generation speed by 25%
 ```
-[FIX] npm translator: Correct handling of devDependencies
 
-- devDevependencies should only be included in certain cases
-- Was caused by a refactoring
+**Dependencies:**
+```
+deps(cli): Update @ui5/logger to v4.0.0
+build(deps-dev): Update eslint to v9.0.0
+```
+
+**Breaking changes:**
+```
+feat(cli)!: Remove deprecated "init" command
 
-Fixes: #42
-Fixes: #45
+BREAKING CHANGE: The "init" command has been removed. Use "create" instead.
+```
+
+**Workspace-wide changes (no scope):**
+```
+ci: Update GitHub Actions to use Node.js 20
+docs: Update contribution guidelines
+build: Configure new linting rules
 ```
 
-## Work on Release Branches
-Major releases are typically prepared on dedicated branches like `next`.
+### Multi-Package Changes
 
-There are some things to be aware of when working on these branches.
+When making changes that affect multiple packages, create individual commits for each package to maintain clear scoping and changelog generation. Each commit should follow the conventional commit format with the appropriate package scope.
 
-### Implementing Changes in Multiple Code Lines
-While working on a new major release (e.g. `5.0.0`), any fixes or new features implemented on the **current** (main) code line (e.g. 4.x) should be cherry-picked as `[INTERNAL]` to the dedicated (pre-)release branch (typically `next`). This is to prevent changes declared as `[FEATURE]` or `[FIX]` from appearing in the changelog twice, which can be confusing since the new major version has not yet been released and should naturally contain any fixes or features released in any of the preceding releases. Listing them twice might confuse users. Note that our changelog is generated based on all tags of the repository, independent of the currently checked out branch (also see [git-chglog/issues/123](https://github.com/git-chglog/git-chglog/issues/123)).
+**Exception:** Create a single commit for cross-package changes that do not affect the public changelog, such as:
+- Code style updates and formatting changes
+- Refactoring that doesn't change public APIs
+- Internal tooling and configuration updates
+- Documentation updates across packages
 
-However, once a new major release becomes **current** (i.e. "main", not a pre-release), any changes applied to multiple code lines should be cherry picked with the original prefix, so that they appear for multiple versions in the changelog.
+#### Examples
+
+For a feature spanning multiple packages:
+```
+feat(cli): Add support for new build option
+feat(builder): Implement new build option processing
+feat(fs): Add helper methods for new build option
+```
+
+For refactoring across packages:
+```
+refactor: Standardize error handling across packages
+```