changelog-updates

开发者关心的变更日志和产品更新

发行说明是面向开发者的沟通内容，而非文档。做好发行说明，能够建立信任、展现发展势头，并让更新成为营销契机。

概述

变更日志面向多个受众，也有多种用途：

• 活跃开发者：“哪些变更会影响我的集成？”
• 正在评估的开发者：“这个产品是否在积极维护？”
• 开发者布道师：“有哪些值得分享给我的受众？”
• 你的团队：记录发布内容及发布时间的历史档案

本技能介绍如何创建能够提供信息、建立信任，有时还能带来惊喜的变更日志。

开始之前

查看 developer-audience-context 技能，了解：

• 开发者更喜欢通过什么方式接收更新？
• 哪些变更最受他们关注？
• 他们需要多详细的信息？
• 他们对破坏性变更的接受程度如何？

变更日志的语气和详细程度应与受众相符。

变更日志格式

标准结构

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]
### Added
- New feature in development

## [2.3.0] - 2024-01-15
### Added
- New `analyze()` method for sentiment analysis
- Support for batch processing up to 100 items

### Changed
- Improved error messages with troubleshooting links
- Default timeout increased from 30s to 60s

### Deprecated
- `old_analyze()` will be removed in v3.0.0

### Fixed
- Race condition in concurrent requests (#234)
- Memory leak when processing large files (#256)

## [2.2.1] - 2024-01-08
### Fixed
- Critical security patch for authentication bypass

## [2.2.0] - 2024-01-01
...

变更类别

类别	用途
Added	新功能、新端点、新参数
Changed	行为变更、性能改进
Deprecated	正在逐步淘汰的功能（仍可使用）
Removed	已不再存在的功能
Fixed	Bug 修复
Security	与安全相关的变更

好的条目与不好的条目

好的变更日志条目：

### Added
- New `batch_analyze()` method processes up to 100 items in a single
  request, reducing API calls by 90% for bulk operations.
  [See docs](link) (#198)

### Fixed
- Fixed timeout errors when processing files larger than 10MB.
  Uploads now stream in chunks, eliminating memory issues. (#234)

### Deprecated
- `legacy_auth()` will be removed in v3.0.0 (scheduled for March 2024).
  Migrate to `oauth_auth()` using our [migration guide](link).

不好的变更日志条目：

### Added
- New feature

### Fixed
- Fixed bug
- Fixed another bug
- Various improvements

### Changed
- Updated dependencies

写作风格

具体说明：

❌ "Improved performance"
✅ "Reduced API response time by 40% for list operations"

补充背景信息：

❌ "Fixed issue #234"
✅ "Fixed timeout errors when uploading large files (#234)"

添加资源链接：

✅ "New batch API - [documentation](link) | [migration guide](link)"

说明影响：

✅ "Breaking: `user_id` parameter renamed to `id`.
    Update your code before upgrading."

应包含的内容

必须包含

API 变更：

• 新端点
• 新参数
• 响应格式变更
• 错误代码变更

SDK 变更：

• 新方法
• 方法签名变更
• 新配置选项

破坏性变更：

• 任何需要修改代码的变更
• 已移除的功能
• 默认值变更

安全修复：

• 即使无法详述，也要说明有安全更新
• 遵循负责任的信息披露时间表

可考虑包含

性能改进：

### Changed
- List operations now 3x faster through pagination optimization

开发者体验：

### Added
- Error messages now include troubleshooting links
- SDK now validates API keys at initialization

基础设施：

### Changed
- New data center in EU (eu-west.api.example.com)
- Increased rate limits from 100 to 500 requests/minute

可省略或尽量简化

内部重构：

❌ "Refactored authentication module"
(unless it affects developers)

次要依赖更新：

❌ "Updated lodash from 4.17.20 to 4.17.21"
(unless security-related)

拼写错误修正：

❌ "Fixed typo in error message"
(batch these into "Various documentation improvements")

版本号沟通

向用户解释语义化版本控制

帮助开发者理解版本号的含义：

# Versioning

We follow [Semantic Versioning](https://semver.org/):

- **Major versions (3.0.0)**: May include breaking changes.
  Check the migration guide before upgrading.

- **Minor versions (2.3.0)**: New features, backward compatible.
  Safe to upgrade.

- **Patch versions (2.3.1)**: Bug fixes only.
  Always safe to upgrade.

版本固定建议

帮助开发者做出合适的选择：

# Recommended Version Constraints

For stability, we recommend:
- `"myapi": "^2.3.0"` - Get patches and minor updates
- `"myapi": "~2.3.0"` - Get patches only

For production systems:
- Pin exact versions: `"myapi": "2.3.0"`
- Review changelogs before upgrading
- Test in staging first

API 版本控制沟通

# API Versions

## Current Versions
- **v2** (current): Full support, recommended for new integrations
- **v1** (legacy): Security fixes only, sunset March 2025

## Version Lifecycle
| Status | Duration | What It Means |
|--------|----------|---------------|
| Current | Ongoing | Full support, new features |
| Legacy | 12 months | Security fixes only |
| Deprecated | 6 months | No updates, migration required |
| Sunset | - | No longer available |

## Specifying Version
```bash
curl https://api.example.com/v2/users
# or
curl -H "API-Version: 2024-01-15" https://api.example.com/users

## Breaking Changes

### Breaking Change Announcement Template

```markdown
# Breaking Change: [Brief Description]

**Affects**: SDK v3.0.0, API version 2024-03
**Timeline**: Changes take effect March 15, 2024

## What's Changing
[Clear description of the change]

## Why We're Making This Change
[Honest explanation - better performance, security, consistency]

## Who's Affected
- ✅ Users of SDK v2.x - no action required
- ⚠️ Users of SDK v3.0.0+ - update required
- ⚠️ Direct API users on v1 - update required

## Required Actions

### If you use our SDK:
```python
# Before (v2.x)
client.old_method(user_id="123")

# After (v3.x)
client.new_method(id="123")

如果你直接调用 API：

# Before
POST /v1/users/123/analyze

# After
POST /v2/users/123/analyze

迁移指南

[详细迁移文档链接]

时间线

• 现在：v3.0.0 beta 可供测试
• 2 月 1 日：发布 v3.0.0 稳定版
• 3 月 1 日：v2.x 进入旧版本支持阶段
• 3 月 15 日：API 中的破坏性变更生效
• 9 月 15 日：v2.x 终止支持（不再提供支持）

需要帮助？

• 迁移指南
• 办公时间报名
• 支持渠道

### Breaking Change Communication Timeline

提前 6 个月：宣布即将发生的变更 提前 3 个月：发布新版本并提供迁移路径 提前 1 个月：向受影响用户发送直接邮件 提前 2 周：发送最后提醒 变更当天：变更生效 变更后 1 周：跟进尚未完成迁移的用户

## Deprecation Notices

### In-Code Deprecation

```python
import warnings

def old_method(self, user_id):
    """
    .. deprecated:: 2.3.0
       Use :meth:`new_method` instead. Will be removed in v3.0.0.
    """
    warnings.warn(
        "old_method() is deprecated and will be removed in v3.0.0. "
        "Use new_method() instead. "
        "Migration guide: https://docs.example.com/migrate-v3",
        DeprecationWarning,
        stacklevel=2
    )
    return self.new_method(id=user_id)

API 弃用标头

HTTP/1.1 200 OK
Deprecation: Sun, 15 Sep 2024 00:00:00 GMT
Sunset: Sun, 15 Mar 2025 00:00:00 GMT
Link: <https://docs.example.com/migrate-v3>; rel="deprecation"

{
  "data": {...},
  "_deprecation": {
    "message": "This endpoint is deprecated",
    "sunset": "2025-03-15",
    "migration": "https://docs.example.com/migrate-v3"
  }
}

弃用变更日志条目

### Deprecated
- **`/v1/analyze` endpoint**: Use `/v2/analyze` instead.
  - Migration guide: [link]
  - Sunset date: March 15, 2025
  - After sunset: Requests will return 410 Gone

营造期待感

“即将推出”公告

为即将推出的功能营造期待：

# Coming in Q2 2024

## Batch Processing API (Beta available now)
Process up to 1,000 items in a single request.
[Join the beta](link)

## Python SDK v3.0
Complete rewrite with async support, type hints, and 50% faster.
[Preview documentation](link)

## EU Data Residency
For customers with European data requirements.
[Join waitlist](link)

发布节奏沟通

明确预期：

# Release Schedule

**SDK Releases**: First Monday of each month
**API Updates**: Continuous (backward compatible)
**Breaking Changes**: Twice per year (March, September)

Subscribe to updates:
- [GitHub releases](link)
- [Email newsletter](link)
- [Discord announcements](link)
- [Twitter/X](link)

将功能发布打造成活动

让重要版本成为值得关注的时刻：

# 🚀 SDK v3.0 Launch

We're excited to announce the biggest SDK update in 2 years!

## Highlights
- **50% faster** request processing
- **Full async support** for high-throughput applications
- **Type hints** throughout for better IDE support
- **Simplified auth** - configure once, use everywhere

## Launch Week
- **Monday**: SDK v3.0 stable release
- **Tuesday**: Live coding session (YouTube)
- **Wednesday**: Migration office hours
- **Thursday**: Community showcase
- **Friday**: AMA with the SDK team

## Resources
- [Documentation](link)
- [Migration guide](link)
- [Video walkthrough](link)

## Thank You
Special thanks to our 47 beta testers who found 23 bugs
and suggested 12 improvements that made it into this release!

分发渠道

发布渠道

渠道	受众	内容级别
GitHub Releases	仓库中的开发者	完整变更日志
文档变更日志	所有开发者	完整变更日志
博客	更广泛的受众	重点内容 + 背景信息
电子邮件	活跃用户	摘要 + 行动事项
Twitter/X	社区	仅重点内容
Discord/Slack	活跃社区	讨论 + 重点内容

电子邮件模板

常规发布：

Subject: [Product] v2.3.0 Released - Batch Processing + Bug Fixes

Hey [name],

We just released v2.3.0 with some improvements you'll like:

✨ New batch processing API - handle 100 items at once
🐛 Fixed timeout issues with large files
⚡ 40% faster list operations

Full changelog: [link]
Upgrade guide: [link]

Happy building,
The [Product] Team

破坏性变更：

Subject: ⚠️ Action Required: [Product] Breaking Change on March 15

Hey [name],

We're making changes to improve [X], and you'll need to
update your integration before March 15.

What's changing: [one sentence]
What you need to do: [one sentence]
Full details: [link]

Need help? Reply to this email or join our office hours: [link]

Best,
The [Product] Team

工具

变更日志生成

• Conventional Commits：结构化提交消息
• semantic-release：根据提交自动生成变更日志
• changesets：单体仓库变更日志管理
• Keep a Changelog：格式规范

分发

• GitHub Releases：适用于大多数开发者工作流
• Beehiiv/Buttondown：开发者新闻简报平台
• Twitter/X：向社区快速发布更新
• Discord/Slack：社区讨论

监控

• GitHub Stars/Watchers：参与度指标
• npm 下载统计：采用情况跟踪
• 电子邮件打开率：沟通成效

相关技能

• sdk-dx：SDK 版本管理与迁移
• docs-as-marketing：将变更日志作为文档
• developer-community：社区沟通渠道
• developer-metrics：衡量变更日志参与度
• technical-content-strategy：将变更日志作为内容