search

cockroachdb / docs

CockroachDB user documentation
https://cockroachlabs.com/docs
Creative Commons Attribution 4.0 International
190 stars 459 forks source link

User-facing changes in 19.2 that were not picked up in release notes #5819

Closed knz closed 3 years ago

knz commented 5 years ago

Pursuant to https://github.com/cockroachdb/cockroach/pull/42345 I have scanned the entire 19.2 commit history (automatically) to pick up PRs where the author blindly used 'Release note: None' while there were user-facing changes. These are the changes that likely did not show up in release notes, and the doc team likely could not pick up the change to be documented.

If some of your changes are listed here, please review the PR(s) and suggest missing release notes + doc changes as a comment below.

Also don't forget the category!

Then click the checkbox on the left to indicate you've handled the change.

Note: I did a manual filtering on the automatic scan to remove false positives (no release note actually needed) but I may have left some. Mark the checkbox after you've confirmed that the PR indeed contains no user-facing change.

Changes without release note annotation

PRs merged by contributors

Hall of fame: all user-facing changes are properly documented

Honorable mentions: just a few release note omissions

Missing release notes (rest)

RaduBerinde commented 5 years ago

Thanks for doing this @knz!

dt commented 5 years ago

I have a slight dislike the framing of this and the implication that use of ‘none’ can just be assumed to be mistaken.

There seems to be an assumption here that one commit = one user-facing-change, but one big monster commit is not how we usually want to go about building big new features. Many cases above include many commits working towards implementing one new user-visible feature — there is no reason for those to each have individual release notes as they are not changing an existing user-visible feature. In other cases, they are fixing bugs, but in similarly unreleased functionality and thus again, are not user-visible changes.

RaduBerinde commented 5 years ago

The release notes in the PRs are meant to be accurate between alpha releases, so it is reasonable to document small changes that are part of a bigger new feature (though I agree it's not terribly useful to provide a lot of detail). How these get massaged into the release notes for a major release is not trivial - the improvements related to a bigger change do need to be coalesced into one item.

knz commented 5 years ago

There seems to be an assumption here that one commit = one user-facing-change, but one big monster commit is not how we usually want to go about building big new features. Many cases above include many commits working towards implementing one new user-visible feature — there is no reason for those to each have individual release notes as they are not changing an existing user-visible feature.

David, I stand behind your view here. I have been careful to de-duplicate entries and collapse multiple PRs that are part of a larger whole under a single entry (for example, I removed all the "opt: implement X or Y" entries because they all fall under "remove the heuristic planner", which was documented eventually). I did the same with various IMPORT FROM PRs.

Unfortunately it is hard for me to be 100% accurate so I apologize if I forgot to collapse some groups.

jseldess commented 5 years ago

Thank you for driving this, @knz. Since our Eng team has grown so much, I had a nagging worry that many user-facing changes weren't getting flagged for announcement and documentation. At the end of this exercise, we'll have a clear sense of that.

knz commented 5 years ago
knz commented 5 years ago
petermattis commented 5 years ago
rohany commented 5 years ago

* #40880 (telemetry change) Telemetry is collected when ALTER ALL PARTITIONS is used.

andreimatei commented 5 years ago
andreimatei commented 5 years ago

Done, but I think we should have a conversation about what changes are worthy to be included in release notes. For one, I enjoy reading release notes for software, but not if they're endless. I'm afraid that activism like this, coupled with more and more monkeys banging on this, will lead to a million bullets of very varying degrees of importance.

irfansharif commented 5 years ago
danhhz commented 5 years ago

Thanks for picking this off! Most of these are of very marginal use to the user, but the changefeed one is a great find. The rest of mine were correctly omitted.

arulajmani commented 5 years ago

40948: Release note (bug fix): Fix the outdated message if AOST is used by a query inside a transaction block. Prompts the user to use the "SET TRANSACTION AS OF SYSTEM TIME" syntax.

asubiotto commented 5 years ago

On Mon, Nov 11, 2019 at 10:48 AM irfan sharif notifications@github.com wrote:

  • 41764: Release note (bug fix): Previously a disk stall could allow

    a node to continue heartbeating its liveness record and prevent other nodes from taking over its leases, despite being completely unresponsive.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/cockroachdb/docs/issues/5819?email_source=notifications&email_token=ACQSGZ7AXGRGIKBUZ2XGSMTQTF5FTA5CNFSM4JLMNMWKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEDXHLPY#issuecomment-552498623, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACQSGZ4EXRRJXSGT26KTAWLQTF5FTANCNFSM4JLMNMWA .

-- Alfonso

spaskob commented 5 years ago

Spas Bojanov:

On Tue, Nov 12, 2019 at 12:22 AM Alfonso Subiotto Marqués < notifications@github.com> wrote:

On Mon, Nov 11, 2019 at 10:48 AM irfan sharif notifications@github.com wrote:

  • 41764: Release note (bug fix): Previously a disk stall could allow

    a node to continue heartbeating its liveness record and prevent other nodes from taking over its leases, despite being completely unresponsive.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub < https://github.com/cockroachdb/docs/issues/5819?email_source=notifications&email_token=ACQSGZ7AXGRGIKBUZ2XGSMTQTF5FTA5CNFSM4JLMNMWKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEDXHLPY#issuecomment-552498623 , or unsubscribe < https://github.com/notifications/unsubscribe-auth/ACQSGZ4EXRRJXSGT26KTAWLQTF5FTANCNFSM4JLMNMWA

.

-- Alfonso

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/cockroachdb/docs/issues/5819?email_source=notifications&email_token=AANL635GCJRAF2GECKWGYBDQTGBF7A5CNFSM4JLMNMWKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEDXKWQQ#issuecomment-552512322, or unsubscribe https://github.com/notifications/unsubscribe-auth/AANL637KSPBTOLESRUX35EDQTGBF7ANCNFSM4JLMNMWA .

rytaft commented 5 years ago
andy-kimball commented 5 years ago
bdarnell commented 5 years ago

Done, but I think we should have a conversation about what changes are worthy to be included in release notes. For one, I enjoy reading release notes for software, but not if they're endless. I'm afraid that activism like this, coupled with more and more monkeys banging on this, will lead to a million bullets of very varying degrees of importance.

I generally think release notes should be as comprehensive as possible. They're not necessarily read, but it's important that they be searchable. If the notes are too large (as they are for a full release), this should be addressed with a separate summary document instead of dropping details. (I like python's what's new/changelog split)

nvanbenschoten commented 5 years ago
darinpp commented 5 years ago

On Mon, Nov 11, 2019 at 9:36 AM Ben Darnell notifications@github.com wrote:

Done, but I think we should have a conversation about what changes are worthy to be included in release notes. For one, I enjoy reading release notes for software, but not if they're endless. I'm afraid that activism like this, coupled with more and more monkeys banging on this, will lead to a million bullets of very varying degrees of importance.

I generally think release notes should be as comprehensive as possible. They're not necessarily read, but it's important that they be searchable. If the notes are too large (as they are for a full release), this should be addressed with a separate summary document instead of dropping details. (I like python's what's new https://docs.python.org/3/whatsnew/3.8.html/changelog https://docs.python.org/3/whatsnew/changelog.html#changelog split)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/cockroachdb/docs/issues/5819?email_source=notifications&email_token=ABVZ3FKE7L2UF2YSKRPO3B3QTGJYLA5CNFSM4JLMNMWKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEDXRPYA#issuecomment-552540128, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABVZ3FNXQSZKAJOFI554DHTQTGJYLANCNFSM4JLMNMWA .

thoszhang commented 5 years ago

N/A: #39383 (no user-facing changes)

FWIW, with the exception of #36032 and #35742, all of these were bug fixes for bugs introduced in earlier alpha/beta releases, and therefore don't represent differences from 19.1. It's not clear to me what the plan is for incorporating these release notes into the 19.2.0 release notes, but I worry that adding release notes that were bug fixes from earlier alphas/betas indiscriminately to all the other release notes will be misleading.

solongordon commented 5 years ago

39154 (cli change): In the CLI, creating a non-partitioned index on a partitioned table returns an error unless sql_safe_updates = false.

39404 (sql change): Replication zone names are now displayed differently in the result of queries like SHOW ZONE CONFIGURATION. The name now matches how the target would be specified in a CONFIGURE ZONE statement. For instance, ".meta" is now displayed as "RANGE meta", and "movr.users.asia" is now "PARTITION asia OF TABLE movr.public.users".

I omitted PRs which didn't represent a user-visible change from 19.1 or weren't really of interest to users, like adding a HINT to an error message.

rafiss commented 5 years ago

Not adding notes for #40757, since that was a fix for a PR/feature that was added in this release, and that feature already has release notes.

Also, I noticed that the telemetry change category is being used a lot here, but that category is not documented in Confluence nor in the commit message template. Should we add it?

pbardea commented 5 years ago
dt commented 5 years ago
yuzefovich commented 5 years ago
jseldess commented 5 years ago

@knz, @bdarnell, should we retroactively add these notes to their relevant release note pages? If so, I'll need authors to identify the releases. I suspect that's too much work, but I'm open to your guidance. More importantly, once all authors have completed their reviews here, I'll open docs issues, where relevant.

knz commented 5 years ago

If ben and you decide that retroactive addition is the way to go, then we can automate the classification. That is not too much work.

However I am not sure this is the way to go? Or perhaps, not the only place where this should be reported: all the users that have already read the past release notes will not come across this new content. Maybe we should instead publish an "erratum" page specific to 19.2, even communicate it on the forum and perhaps other channels, and then link to that page from the other release note pages for reference.

knz commented 5 years ago

I meant "addendum" not "erratum".

bdarnell commented 5 years ago

Whatever we do here should be fairly quiet. https://www.cockroachlabs.com/docs/releases/v19.2.0.html is already a summary of the release, and if we were going to have a more detailed "addendum" it would primarily include the union of all the alpha/beta/rc release notes before it would include these things barely got mentioned. It doesn't make sense to make a new page for these. Fitting these into their corresponding alpha/etc release notes is the only place we have to put these notes today and I'm not sure it's worth the effort.

Going forward, perhaps we should consider going to a model where minor releases are lumped together on one page, so we'd have three pages per branch: one for all the pre-releases of a branch (which would also serve as the detailed changelog for the release and would be a reasonable place to drop in unsorted "forgotten" changes like these), one for the release summary itself, and one for the post-release patches.

lopezator commented 4 years ago

It would be nice to have a link to this issue/s from somewhere in docs.

I faced:

https://github.com/cockroachdb/cockroach/pull/39202

Looked into release notes and didn't found anything related.

Took me a while to land here.

jseldess commented 3 years ago

I'm closing this issue in favor of discrete issues, which I will create soon.