docs: Update development guidelines

Author: matz3

commitlint.config.mjs

@@ -27,6 +27,24 @@ export default {
 			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

docs/Guidelines.md

@@ -12,8 +12,6 @@ During development, you might want to use `npm run unit` or `npm run unit-watch`
 ### 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
 
 This project uses the [Conventional Commits specification](https://www.conventionalcommits.org/) to ensure a consistent way of dealing with commit messages.
@@ -24,27 +22,59 @@ This project uses the [Conventional Commits specification](https://www.conventio
 type(scope): Description
 ```
 
-- required: every commit message has to start with a lowercase `type`. The project has defined a set of [valid types](../commitlint.config.mjs#L10)
-  - Note that the types `feat`, `fix`, `perf`, `deps`, and `revert` will appear in the public changelog of the released packages
-- required: the `scope` is required for changes that will appear in the public changelog. The scope must be the package folder name (e.g. `cli`, `builder`, ...). Other scopes are not allowed.
+- **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
 
-- required: the `description` has to follow the Sentence Case style. Only the first word and proper nouns are written in uppercase.
+#### 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
 
-Rules (for commitlint checks)
-- Require a scope for all types that appear in the commit message (TBD: what about deps?)
-- Limit the scope to the package folder names (cli, builder, ..., incl. documentation)
-- 
+#### 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%
 ```
 
+**Dependencies:**
 ```
-fix(fs): Correctly handle paths containing non-ASCII characters on Windows
+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
+
+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
 ```
 
 ### Multi-Package Changes