DOCS: Explain ppreview/oldpreview changes

[tlimoncelli]

Fixes #3133

[tlimoncelli]

@cafferata Thoughts?

[cafferata]

I wonder, why not, in accordance with Semantic Versioning, introduce a v5 where the old preview/push commands are removed? 🤔 This saves us the hassle of drawing up overviews. Of course we will include this in the next release notes as a noticeably ('breaking'?) change.

[tlimoncelli]

What do you mean by "drawing up overviews".

[cafferata]

The (Markdown) tables as included in this GitHub pull request.

[tlimoncelli]

Ah, I see.

Here's what I'm trying to achieve:

1. I want to encourage people to use the new code; and discourage people from using the old code.
2. I want to remove the old code as soon as possible (maybe 2-3 months max).

What do you recommend?

[cafferata]

I would recommend:

1. Release v4.14 (<1 week)

   • With a deprecation message within the preview and push commands.
     • Context: 'in de next release (v4.15) the parallel function (ppreview and ppush) will be the default and so enabled for all providers. We encourage you to test the new ppreview and ppush commands for your own DNSControl set-up/configured providers.'
   • Add a (similar) deprecation message to the v4.14 release notes.
   • Send a mailing to the mailinglist with the release notes (deprecation message included).

2. Release v4.15 (1 month)

   • In release v4.15 change the default behavior of the preview and push commands to the 'parallel version' (ppreview and ppush) and while keeping the older serially version of preview and push functionalities as fallback. Just like GitHub pull request FEATURE: parallel preview/push is now default #3132 does.

3. Release v5.0 (~3 months)

   • In release v5.00 remove the serially preview and push commands.
   • Another nice removal for v5:

     dnscontrol/commands/ppreviewPush.go

     Line 178 in d6d50fc

     printer.Println("WARNING: Please remove obsolete --diff2 flag. This will be an error in v5 or later. See https://github.com/StackExchange/dnscontrol/issues/2262")

I hope this helps you further in creating a release plan. If you have any questions, please let me know.

[tlimoncelli]

Excellent! Yes, that sounds good.

Should oldpreview/oldpush appear earlier i.e. in v4.14?

[jauderho]

Sequence looks good but I would think you can pull in the timelines if you want since v5 signals a major change and folks can decide when they want to roll it out internally,

[cafferata]

Should oldpreview/oldpush appear earlier i.e. in v4.14?

No, I would roll back this change #3132 in the main branch and (re)apply it in a later release v4.15. This gives the users another chance to prevent ignorance. After all, there will be (to be realised) a deprecation/log entry in the old preview and push commands.

Sequence looks good but I would think you can pull in the timelines if you want since v5 signals a major change and folks can decide when they want to roll it out internally,

That would certainly be possible. I would let the timeline depend mainly on the available time. @tlimoncelli himself spoke about 2/3 months where I assumed to prepare the various activities. In theory you could release v4.15 and v5.00 at the same time because it applies Semantic Versioning.

[tlimoncelli]

1. I propose we add oldpreview/oldpush as aliases for preview/push in v4.14. It dosn't hurt to make these commands available early.

2. The docs for oldpreview/oldpush should warn that these aliases are not subject to SemVer and should only be used with the understanding that they'll go away.

3. I disagree that we need to remove the old code in a major release (v5). Feature-wise, there's no breaking change between oldpreview and ppreview. The only breakage would be if someone uses oldpreview/oldpush in a script; my solution for that is in the previous paragraph.

[tlimoncelli]

Let's move this to here: #3142