Author: Don Porter <[email protected]>
State: Final
Type: Project
Vote: Done
Created: 27-Mar-2024
Tcl-Version: 8.7 and 9.0
Vote-Summary: Accepted 8/0/0
Votes-For: DP, BG, AK, KW, MC, SL, FV, JN
Votes-Against: none
Votes-Present: none
Abstract
This TIP proposes a re-purposing and reformatting of the changes file.
Background
Both Tcl and Tk have files named changes in the root directory of their source code distributions. These files have been growing since at least 1990. The changes file in Tcl is one of the largest files in the distribution.
New content has been appended to the end of these files. The contents at the start of the files are some of the oldest contents of Tcl/Tk, and of least value to any contemporary reader.
Unlike the recently deleted ChangeLog files (see TIP 663), the maintenance of the changes file is not incorporated into the normal workflow of core developers. This leaves the changes file as a burden of release engineering of increasingly dubious value.
The formatting of items in the changes file has evolved into a set of single line summaries, duplicating information from the Timelines available online, with abbrevation that often becomes too cryptic.
Each release also prompts the creation of a file of Release Notes which announces the release. This is yet another duplication of information, but one that uses more flexible structure and achieves better readability. The Release Notes are available from the download area on SourceForge, but are not included in the release itself at all.
Rationale
The release of Tcl/Tk and the experience of Tcl/Tk users will be improved with a reboot of these files.
Specification
Following the example of the README file, the contents of the changes files will be in Markdown. The file name will become changes.md.
Each minor release will restart with a new file, with no content carried over from the prior minor releases (but see below). The purpose of the file is to summarize differences in the release compared with the previous minor release, limited to those changes that have importance to programmers writing programs with the package.
The intent of the changes.md file is to be read by people. Fitness for automated processing is of secondary importance. The file may begin with a brief introduction, and the bulk of the file is made of Markdown lists of items each describing a change of importance to programmers.
A precise format for each item in the file is not specified. It is trusted that something workable will arise as we go. It is advised to aim for something more like the current Release Notes than the current changes entries. Items in the changes.md file should be suitable to transfer to the Release Notes with little or no editing. Brevity is important, but not to the point of becoming incomprehensible. Markdown features should be used generously to provide hyperlinks to TIPs or tickets or online resources where useful. References to illustrative examples in the test suite are also an option.
Items should not be dated, and need not be presented in chronological order. Credit should not be included. The Timelines and tickets are the place for that. Any change that creates an incompatibility should be indicated either by a mark or by segregation into a separate list.
In an alpha or beta release, the items in the changes.md file are edited to reflect the revised set of changes. The changes.md file does not contain a record of what features appeared in what alpha or beta release.
In a patch release, the changes new to the patch release are pre-pended to appear in section(s) at the beginning of the changes.md file. This keeps the most recent, most useful information at the beginning of the file.
If the same bug is fixed in patch releases of multiple minor release sequences, the changes.md files of those branches may share an item in common. Branch merging should be able to achieve this without undue trouble.
Core developers are encouraged to add items to the changes.md file when they merge a change to the development branch, though it is recognized it will take time to cultivate these habits.
Copyright
This document has been placed in the public domain.