Fix 0.12 release notes on block relaying

[KrzysiekJ]

The previous information about block relaying in pruned mode suggested that blocks in pruned mode are relayed only to nodes that support BIP 130, which is not true. Block relaying should have little to do with the sendheaders command and apparently it is indeed that way, at least when looking at pull requests #6148 and #7129.

[laanwj]

Hm, thanks for trying to help, but isn't it a bit too late to change 0.12.0 release notes? The release notes in doc/release-notes are an historical archive. People read the release notes before they download a release, 0.12.0 has been out for more than half a year, taking into account rcs, and is subsumed by 0.12.1.

[KrzysiekJ]

Well, I’ve been reading the 0.12.0 release notes to learn whether the newest Bitcoin release (0.12.1) supports block relaying in pruned mode. If someone wants to upgrade from, let’s say, 0.10.0 to 0.12.1, then he needs to check all intermediate release notes to know what features have been added. 0.12.0 release notes even explicitly reference earlier notes (on block relaying). Release notes are therefore a technical documentation, not only a historical document. My peer which connects to Bitcoin Core doesn’t currently support sendheaders, so if I adhered to what is currently written, I would have to run the node in non-pruning mode, using much more disk space.

Besides that, even if we assume that release notes are only documenting past changes (not “being a historical document in itself”), then reflecting those changes accurately has some historical value.

[laanwj]

Yes, ok, note that I'm not against this change, just afraid it's a bit of a waste of effort.
E.g. the release notes have been pushed to various places such as bitcoin.org, posted with release e-mails, etc, it'd be a lot of work (some even impossible) to update all of them.

Release notes are therefore a technical documentation, not only a historical document.

That's a common misconception - the release notes are not meant as technical documentation, just a summary of changes. Documentation where you have to browse back release notes to find why something is the case is the worst kind of documentation, apart from having to check git history (though arguably better than no documentatoin at all).

I do think we need proper, up to date documentation about how block relaying works. E.g. having it documented in the developer documentation: https://bitcoin.org/en/developer-documentation would be nice.

[KrzysiekJ]

I’ve assumed implicitly that merging that change should also somehow mean changing the document on bitcoin.org. Another version being already sent by email would indeed constitute some discrepancy…

Well-written release notes may be very useful when upgrading and reference documentation may be useful in other cases — they are complementary. To summon a reference, Django’s patch review checklist states that both new features and backwards incompatible changes must have a note in release notes; the former must also have ordinary documentation and tests. Bitcoin apparently has no such policy, as pull request #6148 has neither documentation nor tests, but it may be a pattern worth heading to.

On the other hand, if release notes are generally not amendable and tied to a particular tag, then there is a question why after making a release they are still keeped under version control and moved to the doc/release-notes directory. They could be trashed as well.

[maflcko]

bitcoin.org, posted with release e-mails, etc, it'd be a lot of work (some even impossible) to update all of them.

Instead of duplicating the data, what about having a "single truth" somewhere lying around? E.g. the master branch of the repo?

[laanwj]

Instead of duplicating the data, what about having a "single truth" somewhere lying around? E.g. the master branch of the repo?

But release notes aren't supposed to change post-facto. No project does that AFAIK.
(for one they are packaged with the release itself, which cannot change)

[KrzysiekJ]

[…] release notes aren't supposed to change post-facto. No project does that AFAIK.

Django has been doing that. Some examples:

• django/django@abf5ccc29c45d53ec175411
• django/django@da22079c21a02c65
• django/django@2404d209a5e8
• django/django@d52b0c5b38cce633a75420a

(Not judging here whether it is good or not).