changelog

Changelog

Every user-facing PR is recorded once in ## Unreleased of CHANGELOG.md. Add the entry right after gh pr create, on the PR branch, so it lands with the squash merge. scripts/release.sh turns Unreleased into the version heading on stable releases only (betas skip it).

1. New entry, extend, or skip

"Shipped" means in the latest stable release: git describe --tags --abbrev=0 --exclude '*-*' origin/v3 (e.g. v3.11.18). main is the unreleased v4; its betas don't count — a PR already published in a v4.0.0-beta.* is still unreleased, and so is any bug it introduced.

• Extend an existing Unreleased entry when the PR follows up on it: a fix or polish for an unreleased feature, a second PR of the same change, or another update to the same skill, guide, or example upgrade. Append the PR link (and any new contributors) and reword only if the behavior described changes. E.g. #911 + #919 + #925 (dimColor), #904 + #923 (e2e skill), #799 + #848 + #877 (truesheet-usage skill).
• Skip a fix for a bug that never shipped — the code only exists in Unreleased (git show <tag>:<path> fails) or the regression came from an Unreleased PR, including one already out in a beta — unless it changes what an entry says, or the fix belongs to that PR's feature (extend instead). E.g. #907, #908, and #922 (TrueSheetOverlay is v4-only). Also skip changes nobody using or contributing to the library would notice: small docs notes, CI, tests, example-only build fixes.
• New entry otherwise.

2. Section and platform

Section	For	Commit type
🎉 New features	New props, events, methods, components, platform support	feat
🐛 Bug fixes	Fixed behavior	fix
💥 Breaking changes	Anything requiring user action to upgrade	! (e.g. refactor!)
💡 Others	Docs, guides, examples, agent skills, internal refactors, tooling	docs, chore, refactor

One entry per PR, under its primary section, even when it touches several.

Prefix **iOS**:, **Android**:, or **Web**: when the change is limited to one platform (the commit scope usually says, e.g. fix(android)); no prefix when it spans platforms. Within a section, keep entries grouped iOS → Android → Web → unprefixed, and add the new one at the end of its group.

3. Write it

- **Android**: Grabber colors now support `PlatformColor` resource references as well as static colors. ([#916](https://github.com/lodev09/react-native-true-sheet/pull/916) by [@hukpo](https://github.com/hukpo))

Several PRs or authors:

([#911](https://github.com/lodev09/react-native-true-sheet/pull/911), [#919](https://github.com/lodev09/react-native-true-sheet/pull/919) by [@IjzerenHein](https://github.com/IjzerenHein), [@nickcernera](https://github.com/nickcernera) and [@lodev09](https://github.com/lodev09))

• One or two short sentences on what the user sees. No implementation details (native classes, internal flags, how it was fixed).
• Bug fixes state the fixed behavior: "X no longer Y", "X now Y" — not "Fixed a bug where".
• Features say what's new and what it's for: "Added dismissThreshold on Android and Web. Set it to 'short' to ...".
• Breaking changes say what changed and what to do: "... — pass flex: 1 via style to fill."
• Props, events, methods, and values go in backticks.

Credits: the PR author plus commit co-authors who contributed real changes, and the author of any PR this one supersedes (#909 credits #906's author). @lodev09 goes last. Join with , and a final and.

gh pr view <n> --json author,commits --jq '[.author.login] + [.commits[].authors[].login] | unique'

4. Commit

On the PR branch:

git add CHANGELOG.md
git commit -m "docs: add changelog entry for #<n>"      # "docs: update changelog entry for #<n>" when extending
git push

Then make sure "I added a changelog entry (if needed)" is ticked in the PR body. Skipped entries need no commit; say why in the PR or to the user.