a day ago
- The author accidentally upgraded Rust dependencies and faced difficulties because projects lacked CHANGELOG.md files, relying solely on GitHub releases.
- GitHub releases have downsides: pagination makes cross-referencing hard, they are not part of the repository, and they are at risk of being lost if GitHub declines.
- A CHANGELOG.md file in the repository migrates with the code and should be the primary source of release notes.
- The principle extends beyond changelogs: commit messages should explain why changes were made, documentation should be in markdown files, and any project-related data expressible as files should be stored as files in the repository.