What about NEWS instead of CHANGELOG?

[gggeek]

In the days of Git, it seems generally redundant to manually include a detailed changelog file in a package, as the changelog can easily be viewed by either running git log, or checking the project in its source repo, be it github, gitlab, bbcloud or other.

On the other hand, I find extremely valuable the presence of a hand-curated NEWS file, which highlights the most important user-visible changes for each release. It is true that many well-behaved packages do add release notes in their repo of choice, but having the complete list of changes available locally, for all releases, does add extra value.

(See https://www.gnu.org/prep/standards/standards.html#NEWS-File for a description of what should go into NEWS, and as an example of why that file name is already a well known standard and not my personal invention).

Given the above, why not recommending usage of NEWS instead of CHANGELOG?

[pmjones]

why not recommending usage of NEWS instead of CHANGELOG?

Because CHANGELOG (in multiple variations) appears 7000+ times in the research, and NEWS (in multiple variations) appears only about 20 times.

cf. https://github.com/php-pds/skeleton_research/blob/1.x/results/01-files.txt

[gggeek]

Because CHANGELOG (in multiple variations) appears 7000+ times in the research, and NEWS (in multiple variations) appears only about 20 times.

😭

what about recommending it as an option / alternative then?

I have no particular problems with usage of the CHANGELOG file name, except for the fact that it does seem to be widely used to describe two different things (which I shall call for brevity "changelog" and "release notes").

Encouraging its usage without clearly stating the difference does, imho, kind of nudge developers towards the idea that use of automated tools for detailed changelog generation is the golden standard, whereas they provide in general less value to end users than the hand-written release notes.

[gggeek]

ps: CHANGES at least seems to be in use more than 400 times - even though it is not part of other coding standards (as far as I am aware of)

[pmjones]

what about recommending it as an option / alternative then?

That's kind of against the founding principle of the project: "This initiative researches the PHP package ecosystem to recognize commonly adopted development practices. It rationalizes and refines those practices, then publishes them as PDS packages for reference by PHP package authors."

cf. http://php-pds.com/

So to suggest/recommend/encourage/etc something not revealed by the research, isn't appropriate here.

Encouraging its usage

The PDS publications don't "encourage" so much as "document what is measurably in common use".

Look, I get where you're coming from -- having something hand-crafted rather than auto-generated is clearly of high value. If you want to add something like that, called NEWS (or whatever), the standard explicitly allows for it: "The package MAY contain other root-level files for purposes not described in this publication. This publication does not define the structure and contents of the other root-level files."

[gggeek]

That's kind of against the founding principle of the project

Fair enough. Indeed, I did not take into account appropriately the mission charter.

Closing as WONTFIX

[pmjones]

Good form, sir, and thank you!

[samwilson]

I'd just note that CHANGELOG shouldn't really be auto-generated. Some people like the structure of https://keepachangelog.com for instance.

[tuupola]

I tend to agree with @samwilson. CHANGELOG is not the same as git history and autogenerating it usually produces bad results. CHANGELOG should give you quick overview about differences between released versions of code.