Add ChangeLog or NEWS
Weston should have a ChangeLog or NEWS file where we could document all significant changes. Currently the release manager needs to go through the commits while making a release, which can be time consuming. It would be much better if notes were added by the patches or series that implement the significant change.
A first attempt is here: https://patchwork.freedesktop.org/series/16218/ The first patch has some discussion worthy of considering.
The news file should:
- at minimum, include all the changes for the latest Weston release cycle (starting after the previous final release, including alpha, beta, RC and the latest final release) so it gives a good example on how to document changes. For earlier releases it would be enough to point to the release announcements or copy them.
- have such a format that the release manager only needs to add a headline for the release he is making. This means reverse chronological order.
Presumably there are Weston end users who are mostly interested in Weston, and developers who are interested in libweston. These two groups of people should easily see which items apply to them.
Significant Weston changes include:
- command line arguments
- environment variables
- new or removed plugins
- UI behaviour
- new or removed apps and (test) clients
- any change that is likely noticeable by some users, e.g. major bug fixes
Significant libweston changes include:
- major features
- major bug fixes
- public ABI changes
Some changes may fit both categories. The above is just to give an idea of what things to record as news. Explaining what is signficant should be added to some document, maybe the contribution guidelines or the news file itself. The contribution guidelines should at least mention the need to consider news.
Also the releasing documentation needs to gain a note to update the news file when making a release.