You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
The text was updated successfully, but these errors were encountered:
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
Suggested Update to the Guidelines
Add "Refactored" as a section, with a definition like the following:
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.
The text was updated successfully, but these errors were encountered: