Back to Details

changelog-maintenance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Changelog Maintenance

变更日志维护

Overview

概述

Create and maintain structured changelogs that document all notable changes to your project, following industry best practices like Keep a Changelog and Semantic Versioning.
遵循Keep a Changelog和Semantic Versioning等行业最佳实践，创建并维护结构化的变更日志，记录项目中所有值得关注的变更。

When to Use

适用场景

  • Version history documentation
  • Release notes generation
  • Breaking changes tracking
  • Migration guide creation
  • Deprecation notices
  • Security patch documentation
  • Feature announcements
  • Bug fix tracking
  • 版本历史记录
  • 发布说明生成
  • 破坏性变更跟踪
  • 迁移指南创建
  • 弃用通知发布
  • 安全补丁记录
  • 新功能公告
  • Bug修复跟踪

CHANGELOG.md Template

CHANGELOG.md 模板

markdown
undefined
markdown
undefined

Changelog

Changelog

All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[Unreleased]

Added

Added

  • New feature or capability that has been added
  • Can be multiple items
  • New feature or capability that has been added
  • Can be multiple items

Changed

Changed

  • Changes in existing functionality
  • Updates to how features work
  • Changes in existing functionality
  • Updates to how features work

Deprecated

Deprecated

  • Features that will be removed in upcoming releases
  • Include timeline for removal
  • Features that will be removed in upcoming releases
  • Include timeline for removal

Removed

Removed

  • Features that have been removed
  • Previously deprecated features
  • Features that have been removed
  • Previously deprecated features

Fixed

Fixed

  • Bug fixes
  • Security patches
  • Bug fixes
  • Security patches

Security

Security

  • Security vulnerabilities that have been fixed
  • Important security updates
  • Security vulnerabilities that have been fixed
  • Important security updates

[2.1.0] - 2025-01-15

[2.1.0] - 2025-01-15

Added

Added

  • Added OAuth2 authentication support for GitHub and Google
  • New dashboard widget system for customizable layouts
  • Bulk operations API for processing multiple records
  • Export to Excel functionality with custom templates
  • Dark mode theme support across all pages
  • WebSocket support for real-time notifications
  • GraphQL API alongside existing REST endpoints
  • Internationalization support for 10 new languages
    • Spanish, French, German, Italian, Portuguese
    • Japanese, Korean, Chinese (Simplified/Traditional), Arabic
  • Added OAuth2 authentication support for GitHub and Google
  • New dashboard widget system for customizable layouts
  • Bulk operations API for processing multiple records
  • Export to Excel functionality with custom templates
  • Dark mode theme support across all pages
  • WebSocket support for real-time notifications
  • GraphQL API alongside existing REST endpoints
  • Internationalization support for 10 new languages
    • Spanish, French, German, Italian, Portuguese
    • Japanese, Korean, Chinese (Simplified/Traditional), Arabic

Changed

Changed

  • Updated user profile page with improved layout and performance
  • Migrated from REST to GraphQL for main API endpoints
  • Improved error messages with more context and suggestions
  • Refactored authentication system for better security
  • Updated dependencies to latest versions
    • React 18.2.0 → 19.0.0
    • Node.js 16.x → 18.x (minimum required version)
    • PostgreSQL 13 → 14
  • Changed default pagination from 20 to 50 items
  • Improved search algorithm for 3x faster results
  • Updated user profile page with improved layout and performance
  • Migrated from REST to GraphQL for main API endpoints
  • Improved error messages with more context and suggestions
  • Refactored authentication system for better security
  • Updated dependencies to latest versions
    • React 18.2.0 → 19.0.0
    • Node.js 16.x → 18.x (minimum required version)
    • PostgreSQL 13 → 14
  • Changed default pagination from 20 to 50 items
  • Improved search algorithm for 3x faster results

Deprecated

Deprecated

  • REST API v1 endpoints (will be removed in v3.0.0)
    • Use GraphQL API or REST API v2 instead
    • Migration guide: docs/migration-v1-to-v2.md
  • Legacy authentication tokens (remove by 2025-06-01)
    • Replace with JWT tokens
  • Old configuration format in 
    config.json
    • Use new YAML format in 
      config.yaml
  • REST API v1 endpoints (will be removed in v3.0.0)
    • Use GraphQL API or REST API v2 instead
    • Migration guide: docs/migration-v1-to-v2.md
  • Legacy authentication tokens (remove by 2025-06-01)
    • Replace with JWT tokens
  • Old configuration format in 
    config.json
    • Use new YAML format in 
      config.yaml

Removed

Removed

  • Removed deprecated 
    /api/users/list
    endpoint
    • Use 
      /api/v2/users
      instead
  • Removed support for Internet Explorer 11
    • Minimum browser versions: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
  • Removed jQuery dependency (now pure JavaScript)
  • Removed old dashboard widgets (replaced with new widget system)
  • Removed deprecated 
    /api/users/list
    endpoint
    • Use 
      /api/v2/users
      instead
  • Removed support for Internet Explorer 11
    • Minimum browser versions: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
  • Removed jQuery dependency (now pure JavaScript)
  • Removed old dashboard widgets (replaced with new widget system)

Fixed

Fixed

  • Fixed race condition in order processing causing duplicate charges
    • Affected versions: 2.0.0 - 2.0.5
    • Issue: #1234
  • Fixed memory leak in WebSocket connections
  • Fixed incorrect timezone handling in date pickers
  • Fixed CSV export not including all columns
  • Fixed CSRF vulnerability in form submissions (CVE-2025-12345)
  • Fixed accessibility issues in navigation menu
    • Now fully keyboard navigable
    • Screen reader friendly
  • Fixed mobile responsive issues on iPad Pro
  • Fixed SQL injection vulnerability in search (CVE-2025-12346)
    • Security Impact: High
    • Affected Versions: 2.0.0 - 2.0.9
    • Recommended Action: Upgrade immediately
  • Fixed race condition in order processing causing duplicate charges
    • Affected versions: 2.0.0 - 2.0.5
    • Issue: #1234
  • Fixed memory leak in WebSocket connections
  • Fixed incorrect timezone handling in date pickers
  • Fixed CSV export not including all columns
  • Fixed CSRF vulnerability in form submissions (CVE-2025-12345)
  • Fixed accessibility issues in navigation menu
    • Now fully keyboard navigable
    • Screen reader friendly
  • Fixed mobile responsive issues on iPad Pro
  • Fixed SQL injection vulnerability in search (CVE-2025-12346)
    • Security Impact: High
    • Affected Versions: 2.0.0 - 2.0.9
    • Recommended Action: Upgrade immediately

Security

Security

  • CRITICAL: Fixed SQL injection in user search (CVE-2025-12346)
    • Impact: Allows unauthorized database access
    • Affected: v2.0.0 to v2.0.9
    • Action: Upgrade to v2.1.0 immediately
  • Fixed XSS vulnerability in comment rendering (CVE-2025-12347)
  • Updated all dependencies with known security vulnerabilities
  • Implemented rate limiting on all API endpoints
  • Added CSRF protection to all forms
  • Enabled Content Security Policy headers
  • CRITICAL: Fixed SQL injection in user search (CVE-2025-12346)
    • Impact: Allows unauthorized database access
    • Affected: v2.0.0 to v2.0.9
    • Action: Upgrade to v2.1.0 immediately
  • Fixed XSS vulnerability in comment rendering (CVE-2025-12347)
  • Updated all dependencies with known security vulnerabilities
  • Implemented rate limiting on all API endpoints
  • Added CSRF protection to all forms
  • Enabled Content Security Policy headers

[2.0.5] - 2025-01-08

[2.0.5] - 2025-01-08

Fixed

Fixed

  • Hotfix: Critical bug causing data loss in export functionality
  • Fixed authentication issues with LDAP integration
  • Resolved performance degradation with large datasets
  • Hotfix: Critical bug causing data loss in export functionality
  • Fixed authentication issues with LDAP integration
  • Resolved performance degradation with large datasets

Security

Security

  • Patched authentication bypass vulnerability (CVE-2025-12344)
  • Patched authentication bypass vulnerability (CVE-2025-12344)

[2.0.0] - 2025-01-01

[2.0.0] - 2025-01-01

Added

Added

  • Complete UI redesign with modern look and feel
  • New REST API v2 with better performance
  • User roles and permissions system
  • Audit logging for all administrative actions
  • Email templates customization
  • Two-factor authentication (2FA)
  • API rate limiting
  • Database backup automation
  • Complete UI redesign with modern look and feel
  • New REST API v2 with better performance
  • User roles and permissions system
  • Audit logging for all administrative actions
  • Email templates customization
  • Two-factor authentication (2FA)
  • API rate limiting
  • Database backup automation

Changed

Changed

  • BREAKING: Changed API response format from XML to JSON
    • All API consumers must update their integration
    • See migration guide: docs/api-v1-to-v2.md
  • BREAKING: Renamed database tables for consistency 
    • user
      → 
      users
    • order
      → 
      orders
    • Run migration script: 
      npm run migrate:v2
  • BREAKING: Changed authentication from session-based to JWT
    • Existing sessions will be invalidated
    • Users need to log in again
  • Improved database query performance by 50%
  • Updated minimum Node.js version to 16.x
  • BREAKING: Changed API response format from XML to JSON
    • All API consumers must update their integration
    • See migration guide: docs/api-v1-to-v2.md
  • BREAKING: Renamed database tables for consistency 
    • user
      → 
      users
    • order
      → 
      orders
    • Run migration script: 
      npm run migrate:v2
  • BREAKING: Changed authentication from session-based to JWT
    • Existing sessions will be invalidated
    • Users need to log in again
  • Improved database query performance by 50%
  • Updated minimum Node.js version to 16.x

Removed

Removed

  • BREAKING: Removed support for Node.js 12 and 14
  • BREAKING: Removed deprecated configuration options 
    • USE_OLD_AUTH
      - Use JWT authentication
    • LEGACY_MODE
      - No longer supported
  • BREAKING: Removed support for Node.js 12 and 14
  • BREAKING: Removed deprecated configuration options 
    • USE_OLD_AUTH
      - Use JWT authentication
    • LEGACY_MODE
      - No longer supported

Migration Guide

Migration Guide

From v1.x to v2.0:
  1. Update Node.js to version 16 or higher
  2. Update your API integration:
    javascript
    // Old (v1)
fetch('/api/users/list')
  .then(res => res.text())
  .then(xml => parseXML(xml));

// New (v2)
fetch('/api/v2/users')
  .then(res => res.json())
  .then(data => console.log(data));
  3. Run database migrations:
    bash
    npm run migrate:v2
  4. Update environment variables:
    env
    # Remove
USE_OLD_AUTH=true
LEGACY_MODE=true

# Add
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=7d
From v1.x to v2.0:
  1. Update Node.js to version 16 or higher
  2. Update your API integration:
    javascript
    // Old (v1)
fetch('/api/users/list')
  .then(res => res.text())
  .then(xml => parseXML(xml));

// New (v2)
fetch('/api/v2/users')
  .then(res => res.json())
  .then(data => console.log(data));
  3. Run database migrations:
    bash
    npm run migrate:v2
  4. Update environment variables:
    env
    # Remove
USE_OLD_AUTH=true
LEGACY_MODE=true

# Add
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=7d

[1.5.2] - 2024-12-15

[1.5.2] - 2024-12-15

Fixed

Fixed

  • Fixed pagination bug on user list page
  • Resolved timezone issues in reports
  • Fixed email notification delays
  • Fixed pagination bug on user list page
  • Resolved timezone issues in reports
  • Fixed email notification delays

[1.5.0] - 2024-12-01

[1.5.0] - 2024-12-01

Added

Added

  • New reporting dashboard
  • Custom fields for user profiles
  • Webhook support for integrations
  • New reporting dashboard
  • Custom fields for user profiles
  • Webhook support for integrations

Changed

Changed

  • Improved search performance
  • Updated UI components library
  • Improved search performance
  • Updated UI components library

[1.0.0] - 2024-10-01

[1.0.0] - 2024-10-01

Added

Added

  • Initial release
  • User management
  • Basic API
  • Authentication and authorization
  • Database migrations
  • Unit and integration tests
undefined
  • Initial release
  • User management
  • Basic API
  • Authentication and authorization
  • Database migrations
  • Unit and integration tests
undefined

Release Notes Template

发布说明模板

markdown
undefined
markdown
undefined

Release Notes - Version 2.1.0

Release Notes - Version 2.1.0

Release Date: January 15, 2025
Download: v2.1.0
Release Date: January 15, 2025
Download: v2.1.0

🎉 Highlights

🎉 Highlights

  • OAuth2 Authentication: Sign in with GitHub and Google
  • GraphQL API: New GraphQL endpoint alongside REST API
  • Dark Mode: Full dark mode support across all pages
  • Real-time Notifications: WebSocket-powered live updates
  • 10 New Languages: Expanded internationalization support
  • OAuth2 Authentication: Sign in with GitHub and Google
  • GraphQL API: New GraphQL endpoint alongside REST API
  • Dark Mode: Full dark mode support across all pages
  • Real-time Notifications: WebSocket-powered live updates
  • 10 New Languages: Expanded internationalization support

📦 What's New

📦 What's New

OAuth2 Authentication

OAuth2 Authentication

You can now sign in using your GitHub or Google account. Configure OAuth in Settings > Authentication.
javascript
// Enable OAuth in your config
{
  "auth": {
    "providers": ["github", "google"],
    "github": {
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret"
    }
  }
}
You can now sign in using your GitHub or Google account. Configure OAuth in Settings > Authentication.
javascript
// Enable OAuth in your config
{
  "auth": {
    "providers": ["github", "google"],
    "github": {
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret"
    }
  }
}

GraphQL API

GraphQL API

Access your data with GraphQL for more efficient queries:
graphql
query GetUser {
  user(id: "123") {
    id
    name
    email
    orders {
      id
      total
      items {
        product {
          name
          price
        }
      }
    }
  }
}
Endpoint: 
https://api.example.com/graphql
Documentation: GraphQL API Docs
Access your data with GraphQL for more efficient queries:
graphql
query GetUser {
  user(id: "123") {
    id
    name
    email
    orders {
      id
      total
      items {
        product {
          name
          price
        }
      }
    }
  }
}
Endpoint: 
https://api.example.com/graphql
Documentation: GraphQL API Docs

Dark Mode

Dark Mode

Enable dark mode in Settings > Appearance or use system preferences.
Dark Mode Screenshot
Enable dark mode in Settings > Appearance or use system preferences.
Dark Mode Screenshot

🔧 Improvements

🔧 Improvements

  • 3x Faster Search: Improved search algorithm
  • Better Error Messages: More helpful error messages with suggestions
  • Enhanced Performance: 50% faster page loads
  • Mobile Improvements: Better responsive design for tablets
  • 3x Faster Search: Improved search algorithm
  • Better Error Messages: More helpful error messages with suggestions
  • Enhanced Performance: 50% faster page loads
  • Mobile Improvements: Better responsive design for tablets

🐛 Bug Fixes

🐛 Bug Fixes

  • Fixed race condition in order processing
  • Fixed memory leak in WebSocket connections
  • Fixed timezone handling in date pickers
  • Fixed accessibility issues in navigation
  • Fixed race condition in order processing
  • Fixed memory leak in WebSocket connections
  • Fixed timezone handling in date pickers
  • Fixed accessibility issues in navigation

🔒 Security Updates

🔒 Security Updates

  • CRITICAL: Fixed SQL injection vulnerability (CVE-2025-12346)
    • Impact: High - Allows unauthorized database access
    • Action: Upgrade immediately if using v2.0.0 - v2.0.9
  • Fixed XSS vulnerability in comment rendering (CVE-2025-12347)
  • Updated dependencies with security patches
  • CRITICAL: Fixed SQL injection vulnerability (CVE-2025-12346)
    • Impact: High - Allows unauthorized database access
    • Action: Upgrade immediately if using v2.0.0 - v2.0.9
  • Fixed XSS vulnerability in comment rendering (CVE-2025-12347)
  • Updated dependencies with security patches

📋 Breaking Changes

📋 Breaking Changes

Deprecated APIs (Removal in v3.0.0)

Deprecated APIs (Removal in v3.0.0)

The following REST API v1 endpoints are deprecated and will be removed in v3.0.0:
Old EndpointNew EndpointMigration Guide
/api/users/list
/api/v2/users
Link
/api/products/search
/api/v2/products?q=
Link
Timeline: These endpoints will continue working until June 2025.
The following REST API v1 endpoints are deprecated and will be removed in v3.0.0:
Old EndpointNew EndpointMigration Guide
/api/users/list
/api/v2/users
Link
/api/products/search
/api/v2/products?q=
Link
Timeline: These endpoints will continue working until June 2025.

Updated Dependencies

Updated Dependencies

  • Node.js: Minimum version is now 18.x (was 16.x)
  • React: Upgraded to 19.0.0
  • PostgreSQL: Minimum version is now 14 (was 13)
  • Node.js: Minimum version is now 18.x (was 16.x)
  • React: Upgraded to 19.0.0
  • PostgreSQL: Minimum version is now 14 (was 13)

📖 Documentation

📖 Documentation

🔄 Upgrading

🔄 Upgrading

From v2.0.x

From v2.0.x

bash
undefined
bash
undefined

Backup your database first

Backup your database first

pg_dump your_database > backup.sql
pg_dump your_database > backup.sql

Pull latest version

Pull latest version

git pull origin main
git pull origin main

Install dependencies

Install dependencies

npm install
npm install

Run migrations

Run migrations

npm run migrate
npm run migrate

Restart application

Restart application

npm start
undefined
npm start
undefined

From v1.x

From v1.x

Please see the v1 to v2 Migration Guide for detailed upgrade instructions.
Please see the v1 to v2 Migration Guide for detailed upgrade instructions.

🙏 Contributors

🙏 Contributors

Thanks to all contributors who made this release possible:
  • @contributor1 - OAuth2 implementation
  • @contributor2 - GraphQL API
  • @contributor3 - Dark mode
  • @contributor4 - Performance improvements
Thanks to all contributors who made this release possible:
  • @contributor1 - OAuth2 implementation
  • @contributor2 - GraphQL API
  • @contributor3 - Dark mode
  • @contributor4 - Performance improvements

📞 Support

📞 Support

🔜 What's Next?

🔜 What's Next?

Coming in v2.2.0:
  • Advanced analytics dashboard
  • Plugin system for extensibility
  • Mobile apps (iOS and Android)
  • Improved team collaboration features
Stay tuned!
undefined
Coming in v2.2.0:
  • Advanced analytics dashboard
  • Plugin system for extensibility
  • Mobile apps (iOS and Android)
  • Improved team collaboration features
Stay tuned!
undefined

Semantic Versioning Guide

Semantic Versioning 指南

Version: MAJOR.MINOR.PATCH

MAJOR version: Incompatible API changes
MINOR version: Add functionality (backwards-compatible)
PATCH version: Backwards-compatible bug fixes

Examples:
- 1.0.0 → 1.0.1: Bug fixes
- 1.0.1 → 1.1.0: New features (backwards-compatible)
- 1.1.0 → 2.0.0: Breaking changes
Version: MAJOR.MINOR.PATCH

MAJOR version: Incompatible API changes
MINOR version: Add functionality (backwards-compatible)
PATCH version: Backwards-compatible bug fixes

Examples:
- 1.0.0 → 1.0.1: Bug fixes
- 1.0.1 → 1.1.0: New features (backwards-compatible)
- 1.1.0 → 2.0.0: Breaking changes

Best Practices

最佳实践

✅ DO

✅ 建议做法

  • Follow Keep a Changelog format
  • Use Semantic Versioning
  • Document breaking changes prominently
  • Include migration guides
  • Link to relevant issues/PRs
  • Categorize changes (Added, Changed, Fixed, etc.)
  • Include security fixes in separate section
  • Date all releases (YYYY-MM-DD format)
  • Link to release tags
  • Document deprecations with timelines
  • Include upgrade instructions
  • Mention contributors
  • 遵循Keep a Changelog格式
  • 使用Semantic Versioning
  • 突出记录破坏性变更
  • 包含迁移指南
  • 链接到相关问题/拉取请求（PR）
  • 对变更进行分类（新增、变更、修复等）
  • 在单独章节中包含安全修复
  • 为所有版本添加日期（YYYY-MM-DD格式）
  • 链接到版本标签
  • 记录弃用功能及时间线
  • 包含升级说明
  • 提及贡献者

❌ DON'T

❌ 避免做法

  • Skip documenting breaking changes
  • Forget to update changelog before release
  • Mix multiple types in one category
  • Use vague descriptions
  • Skip dates on releases
  • Forget semantic versioning
  • Hide security issues
  • 跳过记录破坏性变更
  • 发布前忘记更新变更日志
  • 在一个分类中混合多种类型的变更
  • 使用模糊的描述
  • 不为版本添加日期
  • 忽略语义化版本控制
  • 隐瞒安全问题

Resources

参考资源