Docs: add recommendations on how to deprecate code

[jeherve]

Changes proposed in this Pull Request:

• Let's be more clear on code deprecation in the plugin, to avoid breaking things on update, or leave things around forever.

cc'ing @dereksmart on this, since you've often been our champion for removing deprecated code. Previous art on the topic:

• Remove all files that were deprecated in 7.5 #13389
• Manage: Remove file stubs #13374
• Remove deprecated module stubs #13375

Note: I also took the opportunity to update wording in another document, moving from Master issue to Primary issue (see #16099).

Jetpack product discussion

• N/A

Does this pull request change what data or activity we track or use?

• N/A

Testing instructions:

• Check for typos

Proposed changelog entry for your changes:

• N/A

[jetpackbot]

Thank you for the great PR description!

When this PR is ready for review, please apply the [Status] Needs Review label. If you are an a11n, please have someone from your team review the code if possible. The Jetpack team will also review this PR and merge it to be included in the next Jetpack release.

E2E results is available here (for debugging purposes): https://jetpack-e2e-dashboard.herokuapp.com/pr-16433

Scheduled Jetpack release: August 4, 2020.
Scheduled code freeze: July 28, 2020

Generated by 🚫 dangerJS against cd7a0a0

[dereksmart]

Thanks! Nice addition.

Is there some timeline where we are comfortable removing deprecated code? Like after X months? If we have this rule set, we could push for deprecation notices to include a message about when this will be fully removed.

Though we technically only support the last 2 versions of Jetpack, we know in practice that it often takes people longer than that to modify their code. I think a 6 month deprecation would be pretty generous, and reasonable.

Then if we have that rule, we could set up a parser to check for them periodically.

Thoughts?

[dereksmart]

I just noticed the bullet point about the 6 months!

[jeherve]

If we have this rule set, we could push for deprecation notices to include a message about when this will be fully removed.

Took a stab at this in #16444.

[jeherve]

we could set up a parser to check for them periodically.

I like that idea. I am not sure how to best go about it though. I suppose we could make it a habit for the release lead at the beginning of each release cycle?