Closed dcmcand closed 7 months ago
Name | Link |
---|---|
Latest commit | a12415ce8151f47c5667382472c80214cf68a310 |
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.
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.
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
This still needs added @trallard but please feel free to take a look at everything else.
@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.
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.