add a "Refactored" section to the changelog guidelines

[BALOGHBence]

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.

[EpicWink]

I would argue that end-users don't care about internal code refactoring, generally ¹. I think the changelog is best for telling users about changes that could affect them. Refactoring can be discovered via version-control.

Footnotes

1. Only in situations where the end-user is familiar with the internals of a project, and something breaks for these users which they know is likely caused by that refactor ↩