Initial draft for change / deprecation processes in the docs. #152
Conversation
|
|
||
| **We recommend developers using PyScript keep the version of PyScript they are | ||
| using up to date**. To ensure this process is smooth, this document was | ||
| created to describe what you can expect from us. |
There was a problem hiding this comment.
We know that this is not necessarily enough though ... pinned dependencies are the key to make both this statement and the desired outcome future proof.
There was a problem hiding this comment.
+100 here. We should advise pinning the PyScript version AND dependencies as a first step and then the PyScript version can float as suggested
| takes such problems very seriously** and will take all the necessary steps to | ||
| ensure security related changes are timely, well documented and taken with | ||
| the greatest of care and attention. | ||
| * **Standards**. PyScript's parents are Python and the web. PyScript is itself |
There was a problem hiding this comment.
"the Web" (capitalized) ?
| Any breaking changes will be arrived at via the processes described in the | ||
| [Change](#change) section. |
There was a problem hiding this comment.
As of now, the Change section doesn't really have any process description and only has "the source of change" and how we interact with these
| Since these will be done in public and with community engagement we hope the | ||
| initial decision for a breaking change will come as no surprise. Furthermore, | ||
| as the change is implemented there will be further opportunities for the change | ||
| to be broadcast: via updates in our community call, via our upcoming PyScript | ||
| newsletter, and in the formal technical discussions that take place on GitHub. |
There was a problem hiding this comment.
I think these should be more explicitly described as part of the Deprecation process.
| to be broadcast: via updates in our community call, via our upcoming PyScript | ||
| newsletter, and in the formal technical discussions that take place on GitHub. | ||
|
|
||
| ### Predictability |
There was a problem hiding this comment.
Not sure if the title is a good fit. I feel like it doesn't really talks to the problem we are trying to solve here. I find something more explicit more helpful. For instance something like "Managing Breaking Changes and Deprecation Process" or something along these lines...
| * After the initial communication of the change, the release of PyScript that | ||
| immediately follows the decision will ensure the affected API reports the | ||
| upcoming changes via a warning in the browser console. |
There was a problem hiding this comment.
I think there's a time component and best intentions here. There may be times when we can't wait a full deprecation cycle but we should ALWAYS try to ensure that there's a deprecation cycle (== we introduce a warning and socialize the breaking change as much as possible with a message that sounds somehow like "Hey! As of release XXXXXXX this feature has marked as deprecated and will be removed in YYYYY future release(s). To avoid breaking your application, to do and see how you can update to the new interface." Or something like that..
This is a first draft. Feedback most welcome.
I have endeavoured to: