Add backwards compatibility policy

[dcmcand]

Closes #595
This pull request:
Creates a Backwards Compatibility Policy for the conda-store project as worked out by @nkaretnikov, @costrouc, and myself.

@costrouc and @nkaretnikov , please ensure that I have accurately captured our discussion.

@trallard I welcome any comments. Also, where in the repo would you like this policy to live? I was unclear on that so put it in the root for the meantime.

[netlify]

✅ Deploy Preview for kaleidoscopic-dango-0cf31d ready!

Name	Link
🔨 Latest commit	a12415c
🔍 Latest deploy log	https://app.netlify.com/sites/kaleidoscopic-dango-0cf31d/deploys/65af96b559691200084d7c2e
😎 Deploy Preview	https://deploy-preview-687--kaleidoscopic-dango-0cf31d.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[pavithraes]

Thanks for putting this together.

Also, where in the repo would you like this policy to live? I was unclear on that so put it in the root for the meantime.

This needs to live at docusaurus-docs/community/policies/backwards-compatibility.md. Note that the policies directory doesn't exist on the main branch, so we'll need to create it in this PR. Alternatively, I'm adding a placeholder for this policy doc in #685, if we merge that first, you can move this doc to the placeholder page directly.

[nkaretnikov]

@dcmcand Good overall! Left some comments, looking forward to the final version!

See what Pavithra wrote regarding where this file should be placed.

[trallard]

Thanks, @dcmcand - I went through and added some comments and suggestions.
I do not know why, but the API sections feel a lot more solid than the ones about Python code - the latter seems like they get too into the weeds (methods, classes, values) and is thin on the more procedural/implementation side.

I like, for example, NumPy's policy https://numpy.org/neps/nep-0023-backwards-compatibility.html#implementing-deprecations-and-removals

1. It makes clear when a deprecation is needed vs being too prescriptive or granular
2. It provides clear steps needed to implement a deprecation (add deprecation warning, add to the notes, add to the docs) for example within this PR

Deprecated classes, methods, and functions should have a comment and a warning (if possible) in the code stating why they are deprecated and what to use instead. This will encourage developers not to use them without breaking existing code.....

Perhaps this should be tightened to add a deprecation warning, include the version number of the release where this was deprecated, provide alternatives (if applicable), add to release notes and document accordingly with visible deprecation status. (you get the gist)

3. It Also includes the process on how to go about deprecations - see: https://numpy.org/neps/nep-0023-backwards-compatibility.html#decision-making - this needs to be included. We should have this process to ensure deprecations do not go unnoticed but are intentional instead and approved/agreed on by the core team. We can think of a process like

   1. Open an RFC issue in the project repository
   2. Follow a consensus-based decision-making approach (ref: https://producingoss.com/en/producingoss.html#consensus-democracy https://www.seedsforchange.org.uk/shortconsensus)
   3. If consensus is reached, move to implementation and follow the rest of the guidelines described in this doc

[trallard]

I cannot put my finger on what it is but from here onwards it feels like this needs some work. Will get back to this tomorrow with a fresh set of eyes.

[dcmcand]

Take a look at what I added and see if you think it is better. If you still thinks it needs work, I am happy to add more or rework what is there.

[trallard]

This looks better, let's merge and if needed iterate on this

[nkaretnikov]

@dcmcand The current version looks great, thanks!

I only have 1 or 2 concrete suggestions, for wording and spelling, the rest of my comments are mostly stylistic nitpicks, which I think will make the source doc easier to read.

I agree with most of Tania's suggestions, too, and clarified where I disagree or have questions.

I'd also prefer we wrap this to 80 chars to match our source code (we use line-length = 88 for Python code), but I don't feel strongly about it if it's too much work.

[nkaretnikov]

Why a change to "backward" here if we use "backwards" everywhere else?

[nkaretnikov]

@dcmcand Thanks for working on this! Unfortunately, I've found some issues caused by a recent commit that wrapped long lines. Also, the lint issues need to be fixed to make the tests pass. Once all these issues are addressed, I'll be happy to accept the PR.

[nkaretnikov]

@dcmcand I've updated my comments using the "suggestions" feature. PTAL

[nkaretnikov]

@dcmcand The linter is still failing, will review once the CI is green.

GitHub also shows that this branch is out-of-date with the base branch, so I suggest updating.

[nkaretnikov]

@dcmcand LGTM, thank you! I've looked at the Docusaurus-rendered version locally to make sure it's displayed properly, too.

@trallard Do you have any additional comments? If not, I think this is ready for merge. We can always address minor details in followups.

[trallard]

Thanks @dcmcand all looks pretty good now.
I left a couple of nits (formatting) that you can or not include, but otherwise this should be ready for merging

[trallard]

Suggested change

	Explanation: This route has breaking changes between `v1` and `v2`. Code
	**Explanation**: This route has breaking changes between `v1` and `v2`. Code

[trallard]

This looks better, let's merge and if needed iterate on this