releases-docs/guideline.md
This document provides guidelines for writing consistent and effective release notes for Bit releases.
Each release note file follows this structure:
title: v{VERSION}
tag: v{VERSION}
draft: false
prerelease: false
immutable: false
author: {AUTHOR_GITHUB_USERNAME}
created: {ISO_DATE}
published: {ISO_DATE}
url: https://github.com/teambit/bit/releases/tag/v{VERSION}
--
{RELEASE_CONTENT}
Release notes should include sections in the following order (include only sections that have content):
Use ### (H3) for section headers in most releases:
### New Features
### Improvements
### Performance
### Bug Fixes
### Internal
Note: Some older releases use ## (H2) - either is acceptable, but ### is preferred for consistency.
Example:
### New Features
- Introduce new **Lane History** to log changes of multiple components (#8381, #8370, #8383)
- `bit lane history` command to inspect and control history of changes
- `bit lane checkout` to "jump" back in time to a state of a lane
- `bit lane revert` to revert implementation of all components in the last to a previous state (they will be `modified`)
- Introduce ability to mark dependencies as `optional` (#8169, #8290)
Example:
### Improvements
- Allow setting up per-workspace with `--local` option `bit config set user.token xxx --local`, or `--local-track` to have config in `workspace.jsonc` (#9557, #9555)
- Enable auto-formatting components before snap/tag with `workspace.jsonc` config (#9497)
"teambit.defender/formatter": { "formatOnPreSnap": true }
- Improve various CLI/UI outputs and errors for better DX (#9507, #9502, #9506)
Example:
### Performance
- Reduce memory usage during peer dependencies resolution (#9156)
- Optimize build capsule creation for unmodified exported dependencies (#9820)
- Don't read and parse the lockfile multiple times for calculating deps graph (#10019)
Example:
### Bug Fixes
- Fix an issue where `bit login` didn't validate the token when it announced user is "logged in" (#9562)
- Fix an issue where `bit install` crashed when it failed to delete unwanted items in `node_modules` (#9224)
- Fix an issue where components marked as `local-only` where still printed in the `snapped` or `pending` in `bit status` (#9266)
This section covers changes that don't directly affect end users:
Example:
### Internal
- Update dependencies (#9299, #9227, #9310, #9298)
- Refactor old code and cleanups (#9324, #9326, #9325)
- Bit-Server improvements for IDE plugin (#9320, #9253, #9252)
- Move to node 22.14.0 (#9548)
(#XXXX) or (#XXXX, #YYYY, #ZZZZ) for multiple related PRsbit install, bit start--generate-types, --localworkspace.jsonc, package.json, .bitmapcomponentRangePrefix, formatOnPreSnap**bold** for:
[linkText](https://pnpm.io/settings#minimumreleaseage)"teambit.defender/formatter": {
"formatOnPreSnap": true
}
Include all sections with detailed explanations and sub-bullets for complex features.
It's acceptable to have only 1-2 sections. A release with just bug fixes is valid:
### Bug Fixes
- Fix issue where `bit start` failed to handle `null` for the new Developer Dropdown (#8499)
- Fix an issue where variables and class names weren't renamed correctly on `bit new` (#8501)
If a release is published but notes are not ready, use:
WIP
When deciding where to place an item:
When multiple PRs contribute to the same feature area, group them:
- Bit MCP updates (#10004, #9967, #9965, #9963, #9953, #9951, #9952, #9980, #9979)
- Improve `bit_component_details` tool for consumers, including batch support and improved data
- `bit_remote_search` supports parallel query support
- Update rules template
- Added dedicated `bit_create` tool
Generic UX improvements can be grouped together:
- Improve various CLI/UI outputs and errors for better DX (#9507, #9502, #9506)
- UI, CLI, error messages, outputs and various Dev-Ex improvements (#9297, #9217, #9311, #9275)
Group all dependency updates in Internal:
- Update dependencies (#9299, #9227, #9310, #9298, #9222, #9315)
- Removed dependencies (#9342, #9369, #9210, #9456)
Before publishing release notes, verify: