From 64719c9d91235116d96a3b342aa0622eb16b51f1 Mon Sep 17 00:00:00 2001 From: "Nicholas H.Tollervey" Date: Fri, 8 Nov 2024 14:58:47 +0000 Subject: [PATCH 1/2] Initial draft for change / deprecation processes in the docs. --- docs/change.md | 168 +++++++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 169 insertions(+) create mode 100644 docs/change.md diff --git a/docs/change.md b/docs/change.md new file mode 100644 index 0000000..bc75cfc --- /dev/null +++ b/docs/change.md @@ -0,0 +1,168 @@ +# Change Management and Deprecation Cycles + +> ποταμοῖσι τοῖσιν αὐτοῖσιν ἐμβαίνουσιν ἕτερα καὶ ἕτερα ὕδατα ἐπιρρεῖ +> (Upon those who step into the same stream ever different waters flow) +> +> ~ Heraclitus + +!!! info + + **TL;DR: Change happens.** + + Sometimes such change is a breaking change. Sometimes such change means + retiring capabilities. + + **This document explains how we're going to manage change carefully, + collaboratively and compassionately.** + +All code changes. + +To ensure PyScript changes are smooth, dependable and well advertised within +our community of users, this document outlines our approach in two areas: + +1. Changes and additions to our codebase. +2. Deprecation of existing features as they are replaced or become redundant. + +Ultimately, and out of necessity as a web-based project, our aim is for a +small, neat, and comprehensible code base, created through engagement with our +community. + +Each release of PyScript is given a [calver](https://calver.org/) release +number so folks using PyScript can immediately see how up-to-date their +referenced PyScript is. For example, release number `2024-10-2` is the second +release made in October, 2024. + +Furthermore, **calver allows users to pin the version of PyScript used in their +project to a specific version**. Since a release never changes once released, +users can be confident PyScript won't shift from under them. + +**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. + +## Change + +The source of change in PyScript comes from three places: + +1. The community - who need change in order to work more effectively. +2. The core developers - who know the code, and want it to be well maintained. +3. The tech world - who update web standards, grow WASM and bring new features. + +Taking each in turn, here's how such changes ought to take place (although we +want to acknowledge this may not always be possible due to context). + +### The Community + +The community of coders who create with PyScript are our primary concern. We +are a diverse community who include folks with many different, and sometimes +conflicting, technical needs. So PyScript best reflects these needs, we invite +our community to engage with us as we shape PyScript's future. + +* Informal technical discussion happens over on our + [discord server](https://discord.gg/HxvBtukrg2). +* We have + [weekly technical community calls](https://discord.gg/CxkMkSa3Zk?event=1303877626154323968) + on our discord server, and you can find recordings of these calls over on + [our YouTube channel](https://www.youtube.com/@PyScriptTV). +* If you have a proposal for a change, + [start a discussion over on GitHub](https://github.com/pyscript/pyscript/discussions) + or [submit an issue/bug report](https://github.com/pyscript/pyscript/issues). +* If, after discussion and consensus has been agreed with the core developers, + you find yourself creating code, please submit a pull request by following + the information in our [developer guide](../developers). +* Finally, we expect everyone to act in the spirit of our + [code of conduct](../conduct/). + +Sometimes there will be conflicting needs or opinions. We welcome constructive +criticism, compassionate argument and pragmatic analysis. However, our core aim +is to find a consensus, and this will inevitably require compromise, +humbleness, and patience. Often such consensus will not please anyone since +nobody gets exactly what they want. But in such a situation, by ensuring our +debate and community engagement is done in public, we will (at least) have a +record of how we arrived at such a consensus. + +### The Developers + +The core developers of PyScript often need to refactor or change code to ensure +PyScript remains a high quality open source project. To this end, our changes +will be: + +* Proposed via a discussion on GitHub, or debated in the community call, + or described on discord (or a mixture of all three). Our intention is to do + all our work in the open and with the full engagement of the community. +* Delivered via a pull request, reviewed in public. The community is invited to + be a part of this review process (subscribe to these updates + via your GitHub account). +* Described in our docs and release notes. + +We, as core maintainers, welcome constructive feedback about our processes. + +### External Tech + +The universe is always changing and PyScript needs to change with it. These +changes happen in three ways: + +* **Dependencies**. The Python interpreters, upon which we depend, are active + open source projects who also make new releases. The core maintainers of + PyScript have excellent relationships with these upstream projects and we + will endeavour to ensure the latest changes appear in PyScript as soon as + possible, +* **Security**. Inevitably some code we depend upon, or perhaps even + in PyScript itself, will encounter a security related problem. **PyScript + 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 + facilitated by web-assembly (WASM). All of these technical worlds rely on + standards to ensure compatibility. Such standards are evolving and changing + all the time and we (PyScript core developers) are actively involved in such + developments and will endeavour to ensure PyScript, when appropriate, is + updated to the latest versions of these standards. + +## Deprecation + +Sometimes we need to make breaking changes: + +* A new feature supercedes an old one. +* An initial implementation of an API requires improvement. +* A feature is no longer used and requires removal to save space / complexity. + +Breaking changes can cause disruption. Therefore we will be very careful when +making such changes. Of primary importance are communication and +predictability. + +### Communication + +Any breaking changes will be arrived at via the processes described in the +[Change](#change) section. + +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. + +### Predictability + +The release of a breaking change follows this process: + +* 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. +* The documentation will also be updated to reflect the upcoming changes to the + API. +* The release notes immediately following the implementation of the + breaking change will include a clear indication that the breaking change has + landed. +* The documentation, immediately following the implementation of the breaking + change, will include a warning to indicate how the new update is different + from the old, and will remove the references to the old API. +* In the following releases the warning about the arrival of the new breaking + change will be removed. + +## Feedback + +This document is a work in progress. Please feel free to offer feedback via +[the GitHub project for our documentation](https://github.com/pyscript/docs). + +Thank you! diff --git a/mkdocs.yml b/mkdocs.yml index 8733bc3..cfeca15 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -78,6 +78,7 @@ nav: - Use Offline: user-guide/offline.md - Built-in APIs: api.md - FAQ: faq.md + - Change management: change.md - Contributing: contributing.md - Developer Guide: developers.md - Code of Conduct: conduct.md From 60c32f7c83eeb41110bfae34cfa8759f1b99b786 Mon Sep 17 00:00:00 2001 From: "Nicholas H.Tollervey" Date: Fri, 8 Nov 2024 15:10:16 +0000 Subject: [PATCH 2/2] Clarification about doc updates. --- docs/change.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/change.md b/docs/change.md index bc75cfc..2e3fdc0 100644 --- a/docs/change.md +++ b/docs/change.md @@ -150,7 +150,7 @@ The release of a breaking change follows this process: immediately follows the decision will ensure the affected API reports the upcoming changes via a warning in the browser console. * The documentation will also be updated to reflect the upcoming changes to the - API. + API: the old API will be clearly flagged as about to change. * The release notes immediately following the implementation of the breaking change will include a clear indication that the breaking change has landed.