From c306ec15808817a33886c117e04b9e2e5528c8ac Mon Sep 17 00:00:00 2001 From: telamonian Date: Wed, 13 May 2020 01:51:11 -0400 Subject: [PATCH 1/4] started provisional_features rfc --- .gitignore | 8 ++++++++ rfc/provisional_features.md | 27 +++++++++++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 .gitignore create mode 100644 rfc/provisional_features.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f387d4e --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +# jetbrains ide stuff +*.iml +.idea/ + +# vscode ide stuff +*.code-workspace +.history +.vscode diff --git a/rfc/provisional_features.md b/rfc/provisional_features.md new file mode 100644 index 0000000..f0ffd77 --- /dev/null +++ b/rfc/provisional_features.md @@ -0,0 +1,27 @@ +- Abstract + + Currently, the api for all new features in JupyterLab has to be frozen within the span of a single PR. This is due to the fact that we follow semver; breaking changes may only occur on the occasion of a major version bump. + + This is fine for most features. However, this dev process is causing problems when used for complex features. In particular, features that are expected to be adopted community-wide (eg LabIcon, the extension system, anything to do with user settings) have issues: + - These features (including their API) benefit from wide community feedback, and suffer in the vacumn of 1000+ line single PRs + - The more complex a feature, the more likely it is for its first draft to have at least some poorly formed or ill-considered API + + To fix this, I propose that we should adopt a formal process for allowing provisional features in the master branch of JuptyerLab core. + +- Goals + - a better experience for core devs, extension devs, and power users around versioning and compatibility + - easier version migration for core and extensions packages + +- Terminology + - community: JupyterLab core devs, extension devs, and end users + - API: public interface, including externally visible package structure, function signatures, CLI, and, in the broadest sense, user interface + +- Creating a new provisional feature (Python/Typescript sources) + - Create new feature in PR, as per normal + - Add a `_PROVISONAL` suffix to all public API + - Declare the provisional API in the PR issue thread + - Include an outline of future work, including a rough schedule describing the process by which this feature will graduate by the time of the next major release + +- Graduating a feature from provisional to mature + - A provisional feature may graduate on any minor release + - A provisional feature must graduate by the next major release (wrt when it was initally pulled into core) or be removed From a21b474eb2d7846764dcd6f76539ff518e9ffeff Mon Sep 17 00:00:00 2001 From: telamonian Date: Wed, 13 May 2020 02:20:12 -0400 Subject: [PATCH 2/4] added "How to treat a provisional feature" section --- rfc/provisional_features.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/rfc/provisional_features.md b/rfc/provisional_features.md index f0ffd77..4ebdb42 100644 --- a/rfc/provisional_features.md +++ b/rfc/provisional_features.md @@ -25,3 +25,13 @@ - Graduating a feature from provisional to mature - A provisional feature may graduate on any minor release - A provisional feature must graduate by the next major release (wrt when it was initally pulled into core) or be removed + +- How to treat a provisional feature + - In JupyterLab core code: + - May be called (and in general treated) the same as any other feature + - Ping the original feature dev on any related PR + - If a dev makes changes to a provisional feature, it is their responsibiliy to fix any knock-on effects in core + - In a 3rd party extension: + - May be experimented with + - Should not be used in production code + - Under no circumstances should a provisional feature be used in released code From 9e25d4f652ccdd7b51fe8861830314acda8393cb Mon Sep 17 00:00:00 2001 From: telamonian Date: Wed, 13 May 2020 03:19:53 -0400 Subject: [PATCH 3/4] finished abstract; added "What this proposal is not" section --- rfc/provisional_features.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/rfc/provisional_features.md b/rfc/provisional_features.md index 4ebdb42..86c26b3 100644 --- a/rfc/provisional_features.md +++ b/rfc/provisional_features.md @@ -6,12 +6,18 @@ - These features (including their API) benefit from wide community feedback, and suffer in the vacumn of 1000+ line single PRs - The more complex a feature, the more likely it is for its first draft to have at least some poorly formed or ill-considered API - To fix this, I propose that we should adopt a formal process for allowing provisional features in the master branch of JuptyerLab core. + To fix this, I propose that we should adopt a formal process for allowing provisional features in the master branch of JuptyerLab core. This will give the core dev team the opportunity to dogfood and improve complex features before declaring them fit for wider consumption in production code. + + Our process should aim for an ideal whereby once a feature is declared mature, it will require no further changes to its API. This in turn would mean fewer breaking changes and less overall maintainence for 3rd party devs. - Goals - a better experience for core devs, extension devs, and power users around versioning and compatibility - easier version migration for core and extensions packages +- What this proposal is not + - a general call to relax semver discipline + - saying that we should hold a community-wide referendum every time someone proposes a new provisional feature + - Terminology - community: JupyterLab core devs, extension devs, and end users - API: public interface, including externally visible package structure, function signatures, CLI, and, in the broadest sense, user interface @@ -23,8 +29,7 @@ - Include an outline of future work, including a rough schedule describing the process by which this feature will graduate by the time of the next major release - Graduating a feature from provisional to mature - - A provisional feature may graduate on any minor release - - A provisional feature must graduate by the next major release (wrt when it was initally pulled into core) or be removed + - A provisional feature must graduate on the next major release (wrt when it was initally pulled into core) or be removed - How to treat a provisional feature - In JupyterLab core code: From 2d353e953d2be0a3d54e2c93a4824205d5605987 Mon Sep 17 00:00:00 2001 From: telamonian Date: Wed, 13 May 2020 03:26:24 -0400 Subject: [PATCH 4/4] added "Alternative names" section --- rfc/provisional_features.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/rfc/provisional_features.md b/rfc/provisional_features.md index 86c26b3..7cb542c 100644 --- a/rfc/provisional_features.md +++ b/rfc/provisional_features.md @@ -1,3 +1,8 @@ +- Alternative names + - Experimental features + - Unstable features + - Preview features + - Abstract Currently, the api for all new features in JupyterLab has to be frozen within the span of a single PR. This is due to the fact that we follow semver; breaking changes may only occur on the occasion of a major version bump.