Merge pull request #80 from espressif/copilot/add-maintenance-policy-document

docs: add MAINTENANCE.md with release and breaking-change policy

Author: dobairoland

.github/copilot-instructions.md

@@ -48,6 +48,7 @@ Base (src/target/base/) - Interface headers only
 CHANGELOG.md                # Version history
 CMakeLists.txt              # Main library build file
 LICENSE-APACHE, LICENSE-MIT # Dual license
+MAINTENANCE.md              # Maintenance & release policy
 README.md                   # Main documentation
 example/                    # Complete example implementation
 include/                    # Public API headers
@@ -163,6 +164,8 @@ body (optional)
 
 **Common types:** feat, fix, docs, style, refactor, test, chore, change (for version bumps)
 
+**Breaking changes:** Use `!` after type/scope (`feat(flash)!: ...`) or add a `BREAKING CHANGE:` footer so commitizen detects and bumps the major version. See [MAINTENANCE.md](../MAINTENANCE.md) for the full breaking-change process.
+
 ### PR and Review Guidelines
 
 **When creating or reviewing PRs, always check if documentation updates are needed:**
@@ -183,6 +186,9 @@ body (optional)
 - **README.md Updates:**
   - Review if changes require updates to repository README.md (e.g., new features, targets, or significant architectural changes)
 
+- **Breaking Changes:**
+  - Any PR that touches `include/esp-stub-lib/**` in a breaking way must follow the process in [MAINTENANCE.md](../MAINTENANCE.md#4-breaking-changes-policy)
+
 ## GitHub Actions CI
 
 **Workflows:**
@@ -297,14 +303,17 @@ cd example
 ```
 
 **Release process (maintainers only):**
+
+See [MAINTENANCE.md](../MAINTENANCE.md) for versioning rules, breaking-change policy, and release quality expectations.
+
 ```bash
 pip install commitizen
 git fetch
-git checkout -b update/release_vX.Y.Z
-git reset --hard origin/master
+git checkout master && git reset --hard origin/master
 cz bump
-git push -u && git push --tags
-# Then create PR and edit draft release notes
+git push && git push --tags
+# A draft GitHub release with auto-generated notes is created automatically.
+# Review and publish the draft — no separate PR is required.
 ```
 
 ---

.pre-commit-config.yaml

@@ -41,6 +41,8 @@ repos:
     hooks:
       - id: conventional-precommit-linter
         stages: [commit-msg]
+        args:
+          - --allow-breaking
 
   - repo: https://github.com/pre-commit/mirrors-clang-format
     rev: v21.1.8

MAINTENANCE.md

@@ -0,0 +1,72 @@
+# esp-stub-lib maintenance & release policy
+
+This document defines the maintenance rules for `esp-stub-lib` when multiple teams develop and integrate in parallel.
+
+## 1) Public API definition
+
+**Public API** is everything exposed by headers under:
+
+- `include/esp-stub-lib/**`
+
+Consumers must not rely on internal headers or internal symbols outside of this directory.
+
+## 2) Versioning & releases (SemVer)
+
+This project follows **Semantic Versioning**: `MAJOR.MINOR.PATCH` (e.g. `1.4.2`).
+
+Releases are created and tagged regularly using **commitizen** (and its generated changelog/release notes).
+
+**Integration rule for downstream projects:**
+- Downstream projects should pin the submodule to **release tags** (e.g. `v1.3.0`), not to branches and not to arbitrary commits.
+- Pinning to the exact commit that an annotated tag points at is equally valid. This is useful when a team has already tested and approved commit X: they can create a tag pointing at X without needing to move to a different commit and re-run their testing pipelines.
+
+Rationale: tags are explicit integration points with a known set of changes and release notes.
+
+## 3) Branch policy
+
+- There is exactly **one maintained branch: `master`**.
+- Feature branches may exist for development, but no other long-lived maintained branches (no `release/*` branches).
+
+## 4) Breaking changes policy
+
+A change is considered **breaking** if it changes **public API or behavior** in a way that can break existing consumers.
+
+This includes (non-exhaustive):
+- Changes to function signatures, types, macros, constants in `include/esp-stub-lib/**`
+- Removal/renaming of any public API surface
+- Behavioral changes that break existing correct usage (even if the header signature is unchanged)
+
+### Required review for breaking changes
+Any PR that introduces a breaking change MUST be reviewed by **all teams** before merge.
+
+Operationally:
+- PR must be clearly marked as breaking (e.g. title prefix `BREAKING:` and/or label `breaking-change`)
+- The merge commit must follow the Conventional Commits breaking-change format so that commitizen detects it automatically:
+  - Use `!` after the type/scope: `feat(flash)!: change read buffer type`, **or**
+  - Include a `BREAKING CHANGE:` footer in the commit body
+- Approval from all teams is required to merge
+
+## 5) Who can release / tag
+
+Each team is allowed to create releases/tags.
+
+Typical flow:
+- Team A merges a change to `master` that they need in their tool.
+- Team A validates the commit with their tool, then performs a release directly on `master`:
+  - Run `cz bump` on the up-to-date `master` branch — this commits a version bump and creates the tag locally.
+  - Push both the commit and the tag: `git push && git push --tags`.
+  - No separate release PR is needed. The push triggers CI and creates a draft GitHub release with auto-generated release notes. The same person who tagged may review and publish the draft.
+- Team B (and any other teams) can run automation that reacts to new tags (e.g., opens a PR to bump the submodule to the new tag) and executes integration tests.
+- Teams can either:
+  - accept and merge the bump to keep up with the flow (reducing future catch-up cost), or
+  - defer if they have a blocking issue, understanding that later upgrades will include more accumulated changes.
+
+## 6) Expectations for release quality
+
+Because tags are the supported integration points:
+- Do not tag a release unless it is buildable and passes the releasing team's integration test(s).
+- If a release is found to be bad, follow SemVer:
+  - ship a new PATCH release with the fix, or
+  - if necessary, ship a revert + PATCH release
+
+(Do not move/retag an existing version tag.)

README.md

@@ -123,6 +123,8 @@ pre-commit install -t pre-commit -t commit-msg
 
 # How To Release (For Maintainers Only)
 
+See [MAINTENANCE.md](MAINTENANCE.md) for the full maintenance and release policy (versioning, breaking changes, branch policy).
+
 ```bash
 pip install commitizen
 git fetch