Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add a "Refactored" section to the changelog guidelines #645

Open
BALOGHBence opened this issue Dec 2, 2024 · 0 comments
Open

add a "Refactored" section to the changelog guidelines #645

BALOGHBence opened this issue Dec 2, 2024 · 0 comments

Comments

@BALOGHBence
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant