23
loading...
What is a Changelog and how to write one?
Working on applications or APIs, we want to be aware of changes (new functionalities, updates, fix...) that another person did, or make them aware about what you've done.
If you are using a VCS (Version Control System - Git, Subversion...), you can think that its logs are enough to know what happend. But if you and your coworkers are commiting a lot and maybe working at the same time in the same project, you may lose a proper track.
It can work, but it will take more time and efforts to do it properly. (And it will be less easier to refactor commits to have a beautiful track)
As we can found on Wikipedia
A changelog is a log or record of all notable changes made to a project.
Generally, all the Changelog are contains in a single file where version descriptions are listed from the latest version to the earliest.
Technically, you can do what ever you want. If you want to build a specific standard for your project or your enterprise, you can!
But if you are not looking for a custom format or if you want to have base, some standards already exists on the internet.
It can be defined as the "old school way".
Written in a text file, it looks like this
2019-08-29 Noam Postavsky <[email protected]>
Handle completely undecoded input in term (Bug#29918)
* lisp/term.el (term-emulate-terminal): Avoid errors if the whole
decoded string is eight-bit characters. Don't attempt to save the
string for next iteration in that case.
* test/lisp/term-tests.el (term-decode-partial)
(term-undecodable-input): New tests.
2019-06-15 Paul Eggert <[email protected]>
Port to platforms where tputs is in libtinfow
* configure.ac (tputs_library): Also try tinfow, ncursesw (Bug#33977).
2019-02-08 Eli Zaretskii <[email protected]>
Improve documentation of 'date-to-time' and 'parse-time-string'
* doc/lispref/os.texi (Time Parsing): Document
'parse-time-string', and refer to it for the description of
the argument of 'date-to-time'.
* lisp/calendar/time-date.el (date-to-time): Refer in the doc
string to 'parse-time-string' for more information about the
format of the DATE argument. (Bug#34303)We can see a bloc for each update with the date where it was made, the name of the updater and what they did (in a single line and/or with a detail for each updated file).
I think that we have a lack of information and presentation with.
Keep a Changelog is the new way, and it's the principal standard you can found on the Open Sources projects.
Written in Markdown, the file is more structured and once transformed is more pleasant to read.
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [0.0.4] - 2014-08-09
### Added
- Better explanation of the difference between the file ("CHANGELOG")
and its function "the change log".
### Changed
- Refer to a "change log" instead of a "CHANGELOG" throughout the site
to differentiate between the file and the purpose of the file — the
logging of changes.
### Removed
- Remove empty sections from CHANGELOG, they occupy too much space and
create too much noise in the file. People will have to assume that the
missing sections were intentionally left out because they contained no
notable changes.
## [0.0.3] - 2014-08-09
### Added
- "Why should I care?" section mentioning The Changelog podcast.
## [0.0.2] - 2014-07-10
### Added
- Explanation of the recommended reverse chronological release ordering.
## [0.0.1] - 2014-05-31
### Added
- This CHANGELOG file to hopefully serve as an evolving example
[Unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...HEAD
[0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4
[0.0.3]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.2...v0.0.3
[0.0.2]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.1...v0.0.2
[0.0.1]: https://github.com/olivierlacan/keep-a-changelog/releases/tag/v0.0.1Here we can see each versions created for the project, with the detail of what was Added, Changed or Removed, and with what was done in each category.
Related to that, we can add more informations like which ticket was related to the update with its link...
Sure, by default we lose the name of the person who worked on it. But with the version and the links, it will be much more easier to find the analysis and documentation of a change...
On the internet you may be able to find more Changelog specifications. And don't forget to have something easy to use for you and your team! If both solutions presented here are too hard or complicated, search for something may be lighter or adapt it to your needs.
I hope it will help you!
Please, don't hesitate to give a feedback about this post to help me to improve my writing skills.