Changelog
{{Short description|Record of changes made to a project}}
{{for|information on Wikipedia changelogs|Help:Page history|selfref=y}}
A changelog (also spelled change log){{cite journal |last1=Kuchenrither |first1=Richard D. |last2=Hite |first2=Robert W. |last3=Gerali |first3=Catherine R. |last4=Brennan |first4=William F. |last5=Wilson |first5=David |title=New Innovations for Program Management … Challenges and Successes |journal=Proceedings of the Water Environment Federation |date=1 January 2008 |volume=2008 |issue=14 |pages=2331–2344 |doi=10.2175/193864708788734656}} is a log or record of all notable changes made to a project.{{cite book |last1=Lewko |first1=Caroline |title=Developer Relations: How to Build and Grow a Successful Developer Program |date=2021 |publisher=Apress L. P |location=Berkeley, CA |isbn=978-1484271636 |pages=189–194}} The project is often a website or software project, and the changelog usually includes records of changes such as bug fixes, new features, etc. Some open-source projects include a changelog as one of the top-level files in their distribution.
A changelog has historically included all changes made to a project. An alternative approach has been suggested that the log should instead contain "a curated, chronologically ordered list of notable changes for each version of a project" and should not be a "dump" of a git log "because this helps nobody".{{Cite web|url=https://keepachangelog.com/en/1.0.0/|title=Keep a Changelog|website=keepachangelog.com}}
Although the GNU (Automake) canonical naming convention for the file is ChangeLog,[https://www.gnu.org/software/automake/manual/html_node/Gnits.html#Gnits The GNU automake manual]. it is sometimes alternatively named as CHANGES or HISTORY (NEWS is usually a different file reflecting changes between releases, not between the commits). Another convention is to call it a CHANGELOG. Some project maintainers will append a .txt suffix to the file name if the changelog is plain text, a .md suffix if it is in Markdown, or a .rst suffix if it is in reStructuredText.
Some revision control systems are able to generate the relevant information for a changelog, if the goal is to include all changes.{{Cite web|last=Atlassian|title=What is version control {{!}} Atlassian Git Tutorial|url=https://www.atlassian.com/git/tutorials/what-is-version-control|access-date=2022-02-17|website=Atlassian|language=en}}
Format
Changelog files are organized by paragraphs, which define a unique change within a function or file.
The GNU Coding standards recommend the following format:{{cite web |url=https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html |title=GNU Coding Standards: Style of Change Logs |website=Gnu.org |access-date=2019-09-03}}
YYYY-MM-DD␣␣John Doe␣␣
* myfile.ext (myfunction): my changes made
additional changes.
* myfile.ext (unrelated_change): my changes made
to myfile.ext but completely unrelated to the above.
* anotherfile.ext (somefunction): more changes made by me.
Between the date and the name, and again between the name and the email address, there are two spaces each. It is common to enclose the email address in < and >. The Emacs editor creates such entries when creating additional changelog entries.
Changelogs in wikis
Most wiki software includes changelogs as a fundamental feature (often called history in this context). For example, the "View history" link at the topHelp:Page_history. of a Wikipedia entry links to that page's changelog. This feature is vital for complying with the attribution requirements of some copyright licenses.{{Citation needed|reason=This sentence needs a reliable source, how is the page history vital to this?|date=September 2017}}
Product changelogs
A product changelog can keep customers in the loop about what's new. It helps to announce new features, latest releases, and relevant news directly in-app.{{cn|date=February 2022}}
See also
Notes
{{reflist}}
External links
- [https://www.gnu.org/prep/standards/standards.html#Change-Logs GNU Coding Standards: Change Logs]
- [http://keepachangelog.com/ Keep a CHANGELOG]
- [https://co-pilot.dev/changelog Checklist for creating a changelog]
{{Wiktionary|changelog}}