Description
Problem
The current Keep a Changelog guidelines do not include a dedicated section for documenting code refactoring efforts. While the "Changed" section is used for modifications to existing functionality, it conflates changes that alter behavior with those that purely improve internal code quality. This lack of distinction makes it harder for developers to communicate non-functional improvements, such as code restructuring, performance optimizations, or adherence to new best practices.
Proposal
Introduce a "Refactored" section to the guidelines, explicitly for documenting internal changes that improve the quality, structure, or performance of the codebase without altering its external behavior.
Benefits
- Improved Clarity: Differentiating between behavioral changes ("Changed") and internal improvements ("Refactored") makes the changelog more informative for both developers and users.
- Recognition of Refactoring Efforts: Highlights the importance of maintaining code quality, encouraging teams to document their work even if it doesn’t directly impact functionality.
- Alignment with Development Practices: Reflects the modern software development workflow, where refactoring is a continuous process.
Suggested Update to the Guidelines
Add "Refactored" as a section, with a definition like the following:
Refactored - Internal changes to the codebase that improve maintainability, readability, or performance without affecting functionality.
This would align the changelog with developer needs, ensuring a clear distinction between behavior-altering changes and internal improvements.
Let me know your thoughts on this! If this seems like a good fit, I’d be happy to further refine the proposal.
Activity