From @neilb

This is a small doc patch for permodstyle relating to changelogs.
It basically suggests that if you've no specific alternative, then call it Changes and follow CPAN​::Changes​::Spec.
And added CPAN​::Changes​::Spec to the list of modules not to whine about when mentioned in L<...>

Cheers,
Neil

From @neilb

From 821176ddd17eb8387c5a695125b66ff40c316e68 Mon Sep 17 00:00:00 2001
From: Neil Bowers <neil@bowers.com>
Date: Sun, 21 Jul 2013 20:59:20 +0100
Subject: [PATCH] For changelogs suggest name it Changes and follow
 CPAN::Changes::Spec
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="------------1.7.6"

This is a multi-part message in MIME format.
--------------1.7.6
Content-Type: text/plain; charset=UTF-8; format=fixed
Content-Transfer-Encoding: 8bit

---
 pod/perlmodstyle.pod           |    5 +++++
 t/porting/known_pod_issues.dat |    1 +
 2 files changed, 6 insertions(+), 0 deletions(-)


--------------1.7.6
Content-Type: text/x-patch; name="0001-For-changelogs-suggest-name-it-Changes-and-follow-CP.patch"
Content-Transfer-Encoding: 8bit
Content-Disposition: attachment; filename="0001-For-changelogs-suggest-name-it-Changes-and-follow-CP.patch"

diff --git a/pod/perlmodstyle.pod b/pod/perlmodstyle.pod
index 558642c..5622d32 100644
--- a/pod/perlmodstyle.pod
+++ b/pod/perlmodstyle.pod
@@ -598,6 +598,11 @@ Release notes or changelogs should be produced for each release of your
 software describing user-visible changes to your module, in terms
 relevant to the user.
 
+Unless you have good reasons for using some other format
+(for example, a format used within your company),
+the convention is to name your changelog file C<Changes>,
+and to follow the simple format described in L<CPAN::Changes::Spec>.
+
 =head1 RELEASE CONSIDERATIONS
 
 =head2 Version numbering
diff --git a/t/porting/known_pod_issues.dat b/t/porting/known_pod_issues.dat
index cdd5971..2f9e7d0 100644
--- a/t/porting/known_pod_issues.dat
+++ b/t/porting/known_pod_issues.dat
@@ -36,6 +36,7 @@ Classic::Perl
 Clone
 cpan2dist(1)
 cpanp(1)
+CPAN::Changes::Spec
 CPANPLUS
 Crypt::Random
 curl(1)

--------------1.7.6--

From @jkeenan

On Sun Jul 21 13​:30​:19 2013, neil.bowers@​cogendo.com wrote​:

This is a small doc patch for permodstyle relating to changelogs.
It basically suggests that if you've no specific alternative, then
call it Changes and follow CPAN​::Changes​::Spec.
And added CPAN​::Changes​::Spec to the list of modules not to whine
about when mentioned in L<...>

Cheers,
Neil

I hesitate to +1 this because CPAN​::Changes​::Spec is not distributed
with core.

$ corelist CPAN​::Changes​::Spec
Data for 2013-05-18
CPAN​::Changes​::Spec was not in CORE (or so I think)

The RT System itself - Status changed from 'new' to 'open'

From @rurban

On Sun, Jul 21, 2013 at 7​:10 PM, James E Keenan via RT
<perlbug-followup@​perl.org> wrote​:

On Sun Jul 21 13​:30​:19 2013, neil.bowers@​cogendo.com wrote​:

This is a small doc patch for permodstyle relating to changelogs.
It basically suggests that if you've no specific alternative, then
call it Changes and follow CPAN​::Changes​::Spec.
And added CPAN​::Changes​::Spec to the list of modules not to whine
about when mentioned in L<...>

LGTM
+1

I hesitate to +1 this because CPAN​::Changes​::Spec is not distributed
with core.

$ corelist CPAN​::Changes​::Spec
Data for 2013-05-18
CPAN​::Changes​::Spec was not in CORE (or so I think)

He explained why he added this name to the list above. It has nothing
to do if it's in core or not. It is not.

via perlbug​: queue​: perl5 status​: new
https://rt-archive.perl.org/perl5/Ticket/Display.html?id=118959

--
Reini Urban
http​://cpanel.net/ http​://www.perl-compiler.org/

From @karenetheridge

On Mon, Jul 22, 2013 at 10​:33​:17AM -0500, Reini Urban wrote​:

On Sun, Jul 21, 2013 at 7​:10 PM, James E Keenan via RT

I hesitate to +1 this because CPAN​::Changes​::Spec is not distributed
with core.

He explained why he added this name to the list above. It has nothing
to do if it's in core or not. It is not.

If the concern is "we shouldn't point to specs that we haven't officially
canonized into core", then is it too much to next ask "why shouldn't we
core this"? or is the answer simply "meh, not necessary"?

From @rurban

On Mon, Jul 22, 2013 at 2​:24 PM, Karen Etheridge <perl@​froods.org> wrote​:

On Mon, Jul 22, 2013 at 10​:33​:17AM -0500, Reini Urban wrote​:

On Sun, Jul 21, 2013 at 7​:10 PM, James E Keenan via RT

I hesitate to +1 this because CPAN​::Changes​::Spec is not distributed
with core.

He explained why he added this name to the list above. It has nothing
to do if it's in core or not. It is not.

If the concern is "we shouldn't point to specs that we haven't officially
canonized into core", then is it too much to next ask "why shouldn't we
core this"? or is the answer simply "meh, not necessary"?

meh, not necessary

None of the JSON, YAML or CPAN spec suites are in core, and don't need to be.

--
Reini Urban
http​://cpanel.net/ http​://www.perl-compiler.org/

From @neilb

I hesitate to +1 this because CPAN​::Changes​::Spec is not distributed
with core.

He explained why he added this name to the list above. It has nothing
to do if it's in core or not. It is not.

If the concern is "we shouldn't point to specs that we haven't officially
canonized into core", then is it too much to next ask "why shouldn't we
core this"? or is the answer simply "meh, not necessary"?

perlmodstyle starts with the line​:

  This document attempts to describe the Perl Community's "best practice"
  for writing Perl modules.

I think CPAN​::Changes​::Spec is the community's best practice, given 40% of dists follow it, and there isn't a competing spec, that I'm aware of.

I don't think modules should have to be included in core for them to be mentioned in core doc.

Neil

From @rjbs

* Neil Bowers <neil.bowers@​cogendo.com> [2013-07-22T16​:53​:41]

I think CPAN​::Changes​::Spec is the community's best practice, given 40% of
dists follow it, and there isn't a competing spec, that I'm aware of.

Thanks, I was hoping to find out that number.

I think appyling this is reasonable.

--
rjbs

From @tonycoz

On Sun Jul 21 13​:30​:19 2013, neil.bowers@​cogendo.com wrote​:

This is a small doc patch for permodstyle relating to changelogs.
It basically suggests that if you've no specific alternative, then
call it Changes and follow CPAN​::Changes​::Spec.
And added CPAN​::Changes​::Spec to the list of modules not to whine
about when mentioned in L<...>

Thanks, applied as 4a8dd74.

Tony

@tonycoz - Status changed from 'open' to 'resolved'