Skip to main content

Change Log Style

In software development, a change log is an important document that tracks the changes made to a project over time. It provides a clear and concise record of updates, bug fixes, new features, and other modifications. A well-structured and consistent change log style is crucial for effective communication and collaboration among team members and stakeholders.

Why is Change Log Style Important?​

  1. Clarity: A well-defined change log style ensures that information is presented in a clear and understandable manner. This helps developers, testers, and other team members easily grasp the changes that have been made and their impact on the project.

  2. Collaboration: A consistent change log style promotes collaboration among team members. When everyone follows the same format and structure, it becomes easier to review, discuss, and provide feedback on the changes.

  3. Documentation: Change logs serve as valuable documentation for future reference. Maintaining a conscistent style makes it easier to search and retrieve information from previous versions of the project.

How to Define a Good Change Log​

It's a good question!

A good Change Log must meet the following requirements:

  • It's written for people, not machines. Remember, speak human words.

  • Quickly jump to any segment. Therefore, markdown format is adopted

  • One version corresponds to one chapter.

  • The latest version is on, and the oldest one is below.

  • 'yyyy-mm-dd' is adopted for all dates (For example, August 8, 2008 of the Beijing Olympic Games is 2008-08-08), which is internationally used and can be understood in any language, and is also recognized by xkcdRecommended!

  • Mark whether it complies with semantic version format

  • Each software version must:

  • Indicate the date (use the specification mentioned above)

  • Indicate the classification (in English). The specifications are as follows:

  • 'added' added new features

  • 'changed' function change

  • 'deprecated 'is not recommended and will be deleted in the future

  • 'removed 'features that were not recommended before are really deleted this time

  • 'fixed' bug

  • Security related bugs modified by 'security'

Example​

Here is an example of a change log entry following the recommended style:

## [1.2.0] - 2022-01-01

### Added
- Implemented new feature XYZ.
  - This feature allows users to customize their profile settings.

### Changed
- Updated the UI layout for better user experience.

### Fixed
- Resolved issue with login authentication.
  - Users were unable to log in due to a bug in the authentication process.

### Removed
- Deprecated feature ABC.
  - This feature is no longer supported and has been removed from the application.

Conclusion​

A well-defined change log style is essential for effective communication, collaboration, and documentation in software development projects. By following the recommended change log style outlined in this document, you can ensure that your change logs are clear, concise, and consistent, facilitating smooth project management and development processes.