Skip to content

Commit 64719c9

Browse files
ntollntoll
committed
Initial draft for change / deprecation processes in the docs.
1 parent 176e933 commit 64719c9

File tree

2 files changed

+169
-0
lines changed

2 files changed

+169
-0
lines changed

‎docs/change.md

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# Change Management and Deprecation Cycles
2+
3+
> ποταμοῖσι τοῖσιν αὐτοῖσιν ἐμβαίνουσιν ἕτερα καὶ ἕτερα ὕδατα ἐπιρρεῖ
4+
> (Upon those who step into the same stream ever different waters flow)
5+
>
6+
> ~ Heraclitus
7+
8+
!!! info
9+
10+
**TL;DR: Change happens.**
11+
12+
Sometimes such change is a breaking change. Sometimes such change means
13+
retiring capabilities.
14+
15+
**This document explains how we're going to manage change carefully,
16+
collaboratively and compassionately.**
17+
18+
All code changes.
19+
20+
To ensure PyScript changes are smooth, dependable and well advertised within
21+
our community of users, this document outlines our approach in two areas:
22+
23+
1. Changes and additions to our codebase.
24+
2. Deprecation of existing features as they are replaced or become redundant.
25+
26+
Ultimately, and out of necessity as a web-based project, our aim is for a
27+
small, neat, and comprehensible code base, created through engagement with our
28+
community.
29+
30+
Each release of PyScript is given a [calver](https://calver.org/) release
31+
number so folks using PyScript can immediately see how up-to-date their
32+
referenced PyScript is. For example, release number `2024-10-2` is the second
33+
release made in October, 2024.
34+
35+
Furthermore, **calver allows users to pin the version of PyScript used in their
36+
project to a specific version**. Since a release never changes once released,
37+
users can be confident PyScript won't shift from under them.
38+
39+
**We recommend developers using PyScript keep the version of PyScript they are
40+
using up to date**. To ensure this process is smooth, this document was
41+
created to describe what you can expect from us.
42+
43+
## Change
44+
45+
The source of change in PyScript comes from three places:
46+
47+
1. The community - who need change in order to work more effectively.
48+
2. The core developers - who know the code, and want it to be well maintained.
49+
3. The tech world - who update web standards, grow WASM and bring new features.
50+
51+
Taking each in turn, here's how such changes ought to take place (although we
52+
want to acknowledge this may not always be possible due to context).
53+
54+
### The Community
55+
56+
The community of coders who create with PyScript are our primary concern. We
57+
are a diverse community who include folks with many different, and sometimes
58+
conflicting, technical needs. So PyScript best reflects these needs, we invite
59+
our community to engage with us as we shape PyScript's future.
60+
61+
* Informal technical discussion happens over on our
62+
[discord server](https://discord.gg/HxvBtukrg2).
63+
* We have
64+
[weekly technical community calls](https://discord.gg/CxkMkSa3Zk?event=1303877626154323968)
65+
on our discord server, and you can find recordings of these calls over on
66+
[our YouTube channel](https://www.youtube.com/@PyScriptTV).
67+
* If you have a proposal for a change,
68+
[start a discussion over on GitHub](https://github.com/pyscript/pyscript/discussions)
69+
or [submit an issue/bug report](https://github.com/pyscript/pyscript/issues).
70+
* If, after discussion and consensus has been agreed with the core developers,
71+
you find yourself creating code, please submit a pull request by following
72+
the information in our [developer guide](../developers).
73+
* Finally, we expect everyone to act in the spirit of our
74+
[code of conduct](../conduct/).
75+
76+
Sometimes there will be conflicting needs or opinions. We welcome constructive
77+
criticism, compassionate argument and pragmatic analysis. However, our core aim
78+
is to find a consensus, and this will inevitably require compromise,
79+
humbleness, and patience. Often such consensus will not please anyone since
80+
nobody gets exactly what they want. But in such a situation, by ensuring our
81+
debate and community engagement is done in public, we will (at least) have a
82+
record of how we arrived at such a consensus.
83+
84+
### The Developers
85+
86+
The core developers of PyScript often need to refactor or change code to ensure
87+
PyScript remains a high quality open source project. To this end, our changes
88+
will be:
89+
90+
* Proposed via a discussion on GitHub, or debated in the community call,
91+
or described on discord (or a mixture of all three). Our intention is to do
92+
all our work in the open and with the full engagement of the community.
93+
* Delivered via a pull request, reviewed in public. The community is invited to
94+
be a part of this review process (subscribe to these updates
95+
via your GitHub account).
96+
* Described in our docs and release notes.
97+
98+
We, as core maintainers, welcome constructive feedback about our processes.
99+
100+
### External Tech
101+
102+
The universe is always changing and PyScript needs to change with it. These
103+
changes happen in three ways:
104+
105+
* **Dependencies**. The Python interpreters, upon which we depend, are active
106+
open source projects who also make new releases. The core maintainers of
107+
PyScript have excellent relationships with these upstream projects and we
108+
will endeavour to ensure the latest changes appear in PyScript as soon as
109+
possible,
110+
* **Security**. Inevitably some code we depend upon, or perhaps even
111+
in PyScript itself, will encounter a security related problem. **PyScript
112+
takes such problems very seriously** and will take all the necessary steps to
113+
ensure security related changes are timely, well documented and taken with
114+
the greatest of care and attention.
115+
* **Standards**. PyScript's parents are Python and the web. PyScript is itself
116+
facilitated by web-assembly (WASM). All of these technical worlds rely on
117+
standards to ensure compatibility. Such standards are evolving and changing
118+
all the time and we (PyScript core developers) are actively involved in such
119+
developments and will endeavour to ensure PyScript, when appropriate, is
120+
updated to the latest versions of these standards.
121+
122+
## Deprecation
123+
124+
Sometimes we need to make breaking changes:
125+
126+
* A new feature supercedes an old one.
127+
* An initial implementation of an API requires improvement.
128+
* A feature is no longer used and requires removal to save space / complexity.
129+
130+
Breaking changes can cause disruption. Therefore we will be very careful when
131+
making such changes. Of primary importance are communication and
132+
predictability.
133+
134+
### Communication
135+
136+
Any breaking changes will be arrived at via the processes described in the
137+
[Change](#change) section.
138+
139+
Since these will be done in public and with community engagement we hope the
140+
initial decision for a breaking change will come as no surprise. Furthermore,
141+
as the change is implemented there will be further opportunities for the change
142+
to be broadcast: via updates in our community call, via our upcoming PyScript
143+
newsletter, and in the formal technical discussions that take place on GitHub.
144+
145+
### Predictability
146+
147+
The release of a breaking change follows this process:
148+
149+
* After the initial communication of the change, the release of PyScript that
150+
immediately follows the decision will ensure the affected API reports the
151+
upcoming changes via a warning in the browser console.
152+
* The documentation will also be updated to reflect the upcoming changes to the
153+
API.
154+
* The release notes immediately following the implementation of the
155+
breaking change will include a clear indication that the breaking change has
156+
landed.
157+
* The documentation, immediately following the implementation of the breaking
158+
change, will include a warning to indicate how the new update is different
159+
from the old, and will remove the references to the old API.
160+
* In the following releases the warning about the arrival of the new breaking
161+
change will be removed.
162+
163+
## Feedback
164+
165+
This document is a work in progress. Please feel free to offer feedback via
166+
[the GitHub project for our documentation](https://github.com/pyscript/docs).
167+
168+
Thank you!

‎mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@ nav:
7878
- Use Offline: user-guide/offline.md
7979
- Built-in APIs: api.md
8080
- FAQ: faq.md
81+
- Change management: change.md
8182
- Contributing: contributing.md
8283
- Developer Guide: developers.md
8384
- Code of Conduct: conduct.md

0 commit comments

Comments
 (0)