MySQL Bugs: #115187: Doc do not mention replacement for RESET MASTER.

Bug #115187	Doc do not mention replacement for RESET MASTER.
Submitted:	31 May 16:50	Modified:	16 Jul 13:25
Reporter:	Jean-François Gagné	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	8.4, 8.0	OS:	Any
Assigned to:		CPU Architecture:	Any

Description:
Hi,

RESET MASTER was deprecated in 8.2.0 [1] and removed in 8.4.0 [2].  But when 8.3 was released, I think the 8.2 docs started pointing to 8.3, and they are now pointing to 8.4 [3a] and [3b].

[1]: https://dev.mysql.com/doc/relnotes/mysql/8.2/en/news-8-2-0.html

[2]: https://dev.mysql.com/doc/relnotes/mysql/8.4/en/news-8-4-0.html

[3a]: https://dev.mysql.com/doc/refman/8.2/en/reset-master.html

[3b]: https://dev.mysql.com/doc/refman/8.2/en/

The 8.0 doc does not mention RESET MASTER being deprecated [4], and there are no RESET MASTER doc for 8.4 [5], so the 8.2 and 8.3 RESET MASTER doc links ([3a] and [6]) end-up as "Page Not Found".  This means that easily accessible doc mentions RESET MASTER being deprecated and replaced by RESET BINARY LOGS AND GTIDS.  For me this is a documentation bug as I would expect to find a note in an accessible doc that RESET MASTER is deprecated and replaced by RESET BINARY LOGS AND GTIDS.

[4]: https://dev.mysql.com/doc/refman/8.0/en/reset-master.html

[5]: https://dev.mysql.com/doc/refman/8.4/en/reset-master.html

[6]: https://dev.mysql.com/doc/refman/8.3/en/reset-master.html

I know that the 8.2 [7] and 8.3 [8] docs are available in pdf and mention RESET MASTER, so does the 8.2 [1] and 8.4 [2]  release notes, but I still think that the online HTML docs (not the release notes) should mention that RESET MASTER is deprecated and replaced by RESET BINARY LOGS AND GTIDS.

[7]: https://downloads.mysql.com/docs/refman-8.2-en.pdf

[8]: https://downloads.mysql.com/docs/refman-8.3-en.pdf

See suggested fix for ideas on how to make things better.

I set this as Severity Serious (s2) because even though this is not Critical, the Documentation not mentioning such important change is more than Minor / S3.  For the small story, I did not know the replacement for RESET MASTER, and I had to scratch my head on to where to find it.

I might open another bug / feature request to re-introduce RESET MASTER as deprecated in 8.4.  Removing this makes upgrading from 8.0 to 8.4 way more complicated than what it should be.

Many thanks for looking into this,

Jean-François Gagné

How to repeat:
Check the docs, links in description.

Suggested fix:
The easiest fix I see is to re-introduce the RESET MASTER section in the 8.4 doc, mentioning it is removed and indicating it is replaced by RESET BINARY LOGS AND GTIDS.

Alternatively, mentioning in the 8.0 RESET MASTER doc that the command has been deprecated in 8.2 and replaced by RESET BINARY LOGS AND GTIDS could be another solution.

Also, maybe both above should be done.

Not for specifically for this change, the deprecation cycle might need to be reviewed.  This specific situation shows that deprecating something in an Innovation Release and removing it in the following LTS introduces complexities, both for the vendor (documentation) and the users (complex upgrades).

Re-introducing RESET MASTER as deprecated in 8.4 could also be considered (and other things that have not been deprecated in 8.0 and are removed in 8.4).

Hi,

Thanks for suggestions.

I was similarly surprised by several syntax removals in 8.4 which were only deprecated in 8.2. In addition to RESET MASTER, same story around SHOW MASTER STATUS and other similar replication syntax. And separately, also the SET_USER_ID privilege. These all share the same situation: not deprecated in 8.0 or mentioned as going away in the 8.0 manual, but no longer present in the 8.4 manual since the underlying syntax was removed/changed.

Conceptually the root cause seems to be a conflict between these two concerns:

* Since Innovation releases are quarterly, and each only supported for one quarter, it doesn't make sense to maintain a separate version of the web manual online for each Innovation release beyond the most recent one

* Since future LTS releases will be every ~2 years, sometimes features need to be deprecated/removed more rapidly than that, so there will be situations where a deprecation occurs in an Innovation release and the removal in the next LTS

Those are both completely reasonable on their own. But the interaction of the two results in a gap in the manual. Just commenting on this because if it's tripping up deeply experienced folks like J-F and myself, it's likely causing confusion for many other users too.

Related to the removal of SET_USER_ID in 8.4.0, see Bug#115310, cc Evan Elias.

Bonjour,

We can't address every single issue raised here due to the fact that it is simply no longer possible for us to make changes in the 8.1, 8.2, or 8.3 versions of the Manual (they've been decommissioned).

Nevertheless you have some valid points which should in some way be addressed.

What I have done:

1. Added a prominent note to "RESET MASTER Statement" in the 8.0 Manual.

2. Added a prominent note to "RESET BINARY LOGS AND GTIDS Statement" in the 8.4 Manual.

3. Added a redirect such that any attempt to load the (non-existent) https://dev.mysql.com/doc/refman/8.4/en/reset-master.html will instead bring the user to https://dev.mysql.com/doc/refman/8.4/en/reset-binary-logs-and-gtids.html.

Note that I have just now committed these changes and it may take a day or two for them to appear on dev.mysql.com.

Thanks and regards,

jon.

Fixed in mysqldoc rev 79049.

Closed.