From 130e45c7f5e62d019c2c297989bfcccd50bac454 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 10:50:00 +0100 Subject: [PATCH 01/33] Add a backward compatibility document --- .../backward-compatibility/README.md | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index bd559617c5b17f..ef6239031a58e6 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -1 +1,57 @@ # Backward Compatibility + +Gutenberg follows the WordPress backwards compatibility principles. This means Backward compatibility for producation public API is guaranteed. In some rare occasions breaking backward compatibility is unavoidable, in that case, the breakage should be as small as possible and the breakage should be documented as clearly as possible to third-party developpers using devnotes. + +## What qualifies as a production public API: + +Gutenberg code base is compased of two different types of packages: + - **production packages**: these are packages that are shipped in WordPress scripts (example: wp-components, wp-editor...). + - **development packages**: these are made of developper tools that can be used by third-party developpers to lint, test, format and build their themes and plugins (example: @wordpress/scrips, @wordpress/env...). Typically, these are consumed as npm dependencies in third-party projects. + + Backward compatibility guarantee only applies to the production packages as updates happen through WordPress upgrades. + + Production packages use the `wp` global variable to provide APIs to third-party developpers. These APIs can be JavaScript functions, variables and React components. + +### How to guarantee backward compatibility for a JavaScript function + +* The name of the function should not change. +* The order of the arguments of the function should not change. +* The function's returned value type should not change. +* Changes to arguments (new arguments, modification of semantics) is possible if we guarantee that all previous calls are still possible. + +### How to guarantee backward compatibility for a React Component + +* The name of the component should not change. +* The props of the components should not be removed. +* Existing prop values should continue to be supported. If a component accept a function as prop, we can update the component to accept a new type for the same prop, but it shouldn't break existing usage. +* Adding new props is allowed. +* React Context dependencies can only be added or removed if we ensure the previous context contract is not breaking. +* Classnames, DOM nodes used inside the tree of the component are not considered part of the public API and can be modified. That said, changes to these should be done with caution as it can affect the styling. When classes need to be renamed, if possible keep the old ones. When possible, document these changes and write a devnote about the changes. + +### How to guarantee backward compatibility for a Block + +* Existing usage of the block should not break or be marked as invalid when the editor is loaded. +* The styling of the existing blocks should be guaranteed. +* Markup changes should be limited to the minimum but If a block need to change its saved markup making previous versions invalid, a **deprecated version** for the block should be added. + +## Deprecations + +As the project evolves, flaws to existing APIs are discovered, or updates are required to support new features. When this happens, we try to guarantee that existing APIs don't break and build new alternative APIs. + +To encourage third-party developpers to adopt the new APIs instead, we can use the **deprecated** helper to show a message explaining the deprecation and proposing the alternativewhenever the old API is used. + +## Dev Notes + +Dev Notes are posts published in the make/core site prior to WordPress releases to inform third-party developpers about important changes to the developper APIs, these changes can include: +* Promote new APIs. +* Explain how some changes to existing APIs might affect existing plugins and themes (Example: classname changes...) +* When breaking backward compatibility is unavoidable, explain the reasons and the migration flow. +* When important deprecations are introduced (even without breakage), explain why and how third-party developpers can update their code base in consequence. + +### Dev Note Workflow + +- When working on Pull-request and the need for a dev-note is noted/discovered, add the **Needs Dev Note** label to the PR. +- If possible, add a comment to the PR explaining why the Dev Note is needed. +- When the first beta of the next WordPress release is shipped, go throught the list of merged PRs included in this release and tagged with the **Needs Dev Note** label. +- For each one of these PRs, write a Dev Note, coordinate with the WordPress release leads to publish the dev note. +- Once the dev note for a PR is published, remove the **Needs Dev Note** label from the PR. From dc107401af26ac65218f74c6dfdb2ccc072cf2f7 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 11:24:39 +0100 Subject: [PATCH 02/33] Fix typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index ef6239031a58e6..404d65b39da07f 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -1,6 +1,6 @@ # Backward Compatibility -Gutenberg follows the WordPress backwards compatibility principles. This means Backward compatibility for producation public API is guaranteed. In some rare occasions breaking backward compatibility is unavoidable, in that case, the breakage should be as small as possible and the breakage should be documented as clearly as possible to third-party developpers using devnotes. +Gutenberg follows the WordPress backward compatibility principles. This means backward compatibility for production public API is guaranteed. In some rare occasions breaking backward compatibility is unavoidable, in that case, the breakage should be as small as possible and be documented as clearly as possible to third-party developers using dev notes. ## What qualifies as a production public API: From 09a7c1d9df31ef84bf27ee4b4246bef12f5f8d58 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 11:24:58 +0100 Subject: [PATCH 03/33] Typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 404d65b39da07f..000d5ce8a92b90 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -4,7 +4,7 @@ Gutenberg follows the WordPress backward compatibility principles. This means ba ## What qualifies as a production public API: -Gutenberg code base is compased of two different types of packages: +The Gutenberg code base is composed of two different types of packages: - **production packages**: these are packages that are shipped in WordPress scripts (example: wp-components, wp-editor...). - **development packages**: these are made of developper tools that can be used by third-party developpers to lint, test, format and build their themes and plugins (example: @wordpress/scrips, @wordpress/env...). Typically, these are consumed as npm dependencies in third-party projects. From 8b681344a9a2dcd1e7a3f66822373495ad91d5ce Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 11:26:07 +0100 Subject: [PATCH 04/33] typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 000d5ce8a92b90..4c4d9f3f31bd3e 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -5,7 +5,7 @@ Gutenberg follows the WordPress backward compatibility principles. This means ba ## What qualifies as a production public API: The Gutenberg code base is composed of two different types of packages: - - **production packages**: these are packages that are shipped in WordPress scripts (example: wp-components, wp-editor...). + - **production packages**: these are packages that are shipped as WordPress scripts (example: wp-components, wp-editor...). - **development packages**: these are made of developper tools that can be used by third-party developpers to lint, test, format and build their themes and plugins (example: @wordpress/scrips, @wordpress/env...). Typically, these are consumed as npm dependencies in third-party projects. Backward compatibility guarantee only applies to the production packages as updates happen through WordPress upgrades. From 589e0d7f1bfdbab9309d9c9dbe2db87b8c9ac29e Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 11:26:32 +0100 Subject: [PATCH 05/33] typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 4c4d9f3f31bd3e..58e80573b821cb 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -6,7 +6,7 @@ Gutenberg follows the WordPress backward compatibility principles. This means ba The Gutenberg code base is composed of two different types of packages: - **production packages**: these are packages that are shipped as WordPress scripts (example: wp-components, wp-editor...). - - **development packages**: these are made of developper tools that can be used by third-party developpers to lint, test, format and build their themes and plugins (example: @wordpress/scrips, @wordpress/env...). Typically, these are consumed as npm dependencies in third-party projects. + - **development packages**: these are made out of developer tools that can be used by third-party developers to lint, test, format and build their themes and plugins (example: @wordpress/scrips, @wordpress/env...). Typically, these are consumed as npm dependencies in third-party projects. Backward compatibility guarantee only applies to the production packages as updates happen through WordPress upgrades. From c6011eaecd06e225555bedcd6cbc8f52fbcff93c Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 11:26:46 +0100 Subject: [PATCH 06/33] typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 58e80573b821cb..d3651b43fe9177 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -8,7 +8,7 @@ The Gutenberg code base is composed of two different types of packages: - **production packages**: these are packages that are shipped as WordPress scripts (example: wp-components, wp-editor...). - **development packages**: these are made out of developer tools that can be used by third-party developers to lint, test, format and build their themes and plugins (example: @wordpress/scrips, @wordpress/env...). Typically, these are consumed as npm dependencies in third-party projects. - Backward compatibility guarantee only applies to the production packages as updates happen through WordPress upgrades. +Backward compatibility guarantee only applies to the production packages as updates happen through WordPress upgrades. Production packages use the `wp` global variable to provide APIs to third-party developpers. These APIs can be JavaScript functions, variables and React components. From 35ef68b7b9d829ac679d80428a02bf504dcc497c Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 11:27:06 +0100 Subject: [PATCH 07/33] typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index d3651b43fe9177..27c5ee15e22fc7 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -10,7 +10,7 @@ The Gutenberg code base is composed of two different types of packages: Backward compatibility guarantee only applies to the production packages as updates happen through WordPress upgrades. - Production packages use the `wp` global variable to provide APIs to third-party developpers. These APIs can be JavaScript functions, variables and React components. +Production packages use the `wp` global variable to provide APIs to third-party developers. These APIs can be JavaScript functions, variables and React components. ### How to guarantee backward compatibility for a JavaScript function From 06989abba7541c7b34021b4750731917281866e3 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 11:28:11 +0100 Subject: [PATCH 08/33] clarification MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 27c5ee15e22fc7..5a187d144bd718 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -26,7 +26,7 @@ Production packages use the `wp` global variable to provide APIs to third-party * Existing prop values should continue to be supported. If a component accept a function as prop, we can update the component to accept a new type for the same prop, but it shouldn't break existing usage. * Adding new props is allowed. * React Context dependencies can only be added or removed if we ensure the previous context contract is not breaking. -* Classnames, DOM nodes used inside the tree of the component are not considered part of the public API and can be modified. That said, changes to these should be done with caution as it can affect the styling. When classes need to be renamed, if possible keep the old ones. When possible, document these changes and write a devnote about the changes. +* Class names and DOM nodes used inside the tree of the component are not considered part of the public API and can be modified. That said, changes to these should be done with caution as it can affect the styling. Keep the old ones if possible. If not, document these changes and write a dev note about the changes. ### How to guarantee backward compatibility for a Block From d42b3b89cef3c2fe0e9d4893625210676f99cbc8 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 11:28:28 +0100 Subject: [PATCH 09/33] typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 5a187d144bd718..4e4f26c7a69a1d 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -23,7 +23,7 @@ Production packages use the `wp` global variable to provide APIs to third-party * The name of the component should not change. * The props of the components should not be removed. -* Existing prop values should continue to be supported. If a component accept a function as prop, we can update the component to accept a new type for the same prop, but it shouldn't break existing usage. +* Existing prop values should continue to be supported. If a component accepts a function as prop, we can update the component to accept a new type for the same prop, but it shouldn't break existing usage. * Adding new props is allowed. * React Context dependencies can only be added or removed if we ensure the previous context contract is not breaking. * Class names and DOM nodes used inside the tree of the component are not considered part of the public API and can be modified. That said, changes to these should be done with caution as it can affect the styling. Keep the old ones if possible. If not, document these changes and write a dev note about the changes. From cddbc4bd19b53641b12bb4ac4841430653179fa0 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 11:29:01 +0100 Subject: [PATCH 10/33] add link MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 4e4f26c7a69a1d..3e6ca72f0601f5 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -42,7 +42,7 @@ To encourage third-party developpers to adopt the new APIs instead, we can use t ## Dev Notes -Dev Notes are posts published in the make/core site prior to WordPress releases to inform third-party developpers about important changes to the developper APIs, these changes can include: +Dev notes are [posts published on the make/core site](https://make.wordpress.org/core/tag/dev-notes/) prior to WordPress releases to inform third-party developers about important changes to the developer APIs, these changes can include: * Promote new APIs. * Explain how some changes to existing APIs might affect existing plugins and themes (Example: classname changes...) * When breaking backward compatibility is unavoidable, explain the reasons and the migration flow. From 65e0ad6b57190097cb612a9304b314da0b04577b Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 11:29:21 +0100 Subject: [PATCH 11/33] typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 3e6ca72f0601f5..b735876570b126 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -38,7 +38,7 @@ Production packages use the `wp` global variable to provide APIs to third-party As the project evolves, flaws to existing APIs are discovered, or updates are required to support new features. When this happens, we try to guarantee that existing APIs don't break and build new alternative APIs. -To encourage third-party developpers to adopt the new APIs instead, we can use the **deprecated** helper to show a message explaining the deprecation and proposing the alternativewhenever the old API is used. +To encourage third-party developers to adopt the new APIs instead, we can use the **deprecated** helper to show a message explaining the deprecation and proposing the alternative whenever the old API is used. ## Dev Notes From f578b7e86d2e22aa5e17f8625b06f24edd55f03a Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 11:30:41 +0100 Subject: [PATCH 12/33] typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index b735876570b126..4238e01efc275a 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -46,7 +46,7 @@ Dev notes are [posts published on the make/core site](https://make.wordpress.org * Promote new APIs. * Explain how some changes to existing APIs might affect existing plugins and themes (Example: classname changes...) * When breaking backward compatibility is unavoidable, explain the reasons and the migration flow. -* When important deprecations are introduced (even without breakage), explain why and how third-party developpers can update their code base in consequence. +* When important deprecations are introduced (even without breakage), explain why and how third-party developers can update their code base in consequence. ### Dev Note Workflow From 0956c1910f4796742a267ee51052610037052b27 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 11:32:25 +0100 Subject: [PATCH 13/33] typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 4238e01efc275a..7e82837b026c3c 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -50,7 +50,7 @@ Dev notes are [posts published on the make/core site](https://make.wordpress.org ### Dev Note Workflow -- When working on Pull-request and the need for a dev-note is noted/discovered, add the **Needs Dev Note** label to the PR. +- When working on a pull request and the need for a dev note is discovered, add the **Needs Dev Note** label to the PR. - If possible, add a comment to the PR explaining why the Dev Note is needed. - When the first beta of the next WordPress release is shipped, go throught the list of merged PRs included in this release and tagged with the **Needs Dev Note** label. - For each one of these PRs, write a Dev Note, coordinate with the WordPress release leads to publish the dev note. From a266043a1025c331de69b7130fea7c0a6b1506ac Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 11:32:48 +0100 Subject: [PATCH 14/33] dev note decap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 7e82837b026c3c..09b0dd8a52126e 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -51,7 +51,7 @@ Dev notes are [posts published on the make/core site](https://make.wordpress.org ### Dev Note Workflow - When working on a pull request and the need for a dev note is discovered, add the **Needs Dev Note** label to the PR. -- If possible, add a comment to the PR explaining why the Dev Note is needed. +- If possible, add a comment to the PR explaining why the dev note is needed. - When the first beta of the next WordPress release is shipped, go throught the list of merged PRs included in this release and tagged with the **Needs Dev Note** label. - For each one of these PRs, write a Dev Note, coordinate with the WordPress release leads to publish the dev note. - Once the dev note for a PR is published, remove the **Needs Dev Note** label from the PR. From b4fffc47b30eda8f8be2be87ffdd3b91f98a14cb Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 11:34:19 +0100 Subject: [PATCH 15/33] typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 09b0dd8a52126e..e909ca1b4e038d 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -52,6 +52,6 @@ Dev notes are [posts published on the make/core site](https://make.wordpress.org - When working on a pull request and the need for a dev note is discovered, add the **Needs Dev Note** label to the PR. - If possible, add a comment to the PR explaining why the dev note is needed. -- When the first beta of the next WordPress release is shipped, go throught the list of merged PRs included in this release and tagged with the **Needs Dev Note** label. +- When the first beta of the upcoming WordPress release is shipped, go through the list of merged PRs included in the release and tagged with the **Needs Dev Note** label. - For each one of these PRs, write a Dev Note, coordinate with the WordPress release leads to publish the dev note. - Once the dev note for a PR is published, remove the **Needs Dev Note** label from the PR. From 2c2edbb3553dd86212c13140e475016e32ef8854 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 12:14:01 +0100 Subject: [PATCH 16/33] typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Ella van Durpe --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index e909ca1b4e038d..b28630b1e8db9b 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -53,5 +53,5 @@ Dev notes are [posts published on the make/core site](https://make.wordpress.org - When working on a pull request and the need for a dev note is discovered, add the **Needs Dev Note** label to the PR. - If possible, add a comment to the PR explaining why the dev note is needed. - When the first beta of the upcoming WordPress release is shipped, go through the list of merged PRs included in the release and tagged with the **Needs Dev Note** label. -- For each one of these PRs, write a Dev Note, coordinate with the WordPress release leads to publish the dev note. +- For each one of these PRs, write a dev note and coordinate with the WordPress release leads to publish the dev note. - Once the dev note for a PR is published, remove the **Needs Dev Note** label from the PR. From ffbeebbd1f9188b8818babe149677d256ea5cb35 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 14:30:37 +0100 Subject: [PATCH 17/33] Changes per review --- .../backward-compatibility/README.md | 34 ++++++++++++------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index b28630b1e8db9b..18f1dcef1785d8 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -1,8 +1,11 @@ # Backward Compatibility -Gutenberg follows the WordPress backward compatibility principles. This means backward compatibility for production public API is guaranteed. In some rare occasions breaking backward compatibility is unavoidable, in that case, the breakage should be as small as possible and be documented as clearly as possible to third-party developers using dev notes. +Historically WordPress has been known for preserving backward compatibility across versions. Gutenberg follows this example wherever possible in its production public APIs. There are rare occasions where breaking backward compatibility is unavoidable and in those cases the breakage: -## What qualifies as a production public API: +* should be constrained as much as possible to a small surface area of the API. +* should be documented as clearly as possible to third-party developers using dev notes. + +## What qualifies as a production public API The Gutenberg code base is composed of two different types of packages: - **production packages**: these are packages that are shipped as WordPress scripts (example: wp-components, wp-editor...). @@ -12,33 +15,38 @@ Backward compatibility guarantee only applies to the production packages as upda Production packages use the `wp` global variable to provide APIs to third-party developers. These APIs can be JavaScript functions, variables and React components. -### How to guarantee backward compatibility for a JavaScript function +### How to preserve backward compatibility for a JavaScript function * The name of the function should not change. * The order of the arguments of the function should not change. * The function's returned value type should not change. * Changes to arguments (new arguments, modification of semantics) is possible if we guarantee that all previous calls are still possible. -### How to guarantee backward compatibility for a React Component +### How to preserve backward compatibility for a React Component * The name of the component should not change. * The props of the components should not be removed. * Existing prop values should continue to be supported. If a component accepts a function as prop, we can update the component to accept a new type for the same prop, but it shouldn't break existing usage. * Adding new props is allowed. * React Context dependencies can only be added or removed if we ensure the previous context contract is not breaking. -* Class names and DOM nodes used inside the tree of the component are not considered part of the public API and can be modified. That said, changes to these should be done with caution as it can affect the styling. Keep the old ones if possible. If not, document these changes and write a dev note about the changes. -### How to guarantee backward compatibility for a Block +### How to preserve backward compatibility for a Block * Existing usage of the block should not break or be marked as invalid when the editor is loaded. * The styling of the existing blocks should be guaranteed. -* Markup changes should be limited to the minimum but If a block need to change its saved markup making previous versions invalid, a **deprecated version** for the block should be added. +* Markup changes should be limited to the minimum but If a block need to change its saved markup making previous versions invalid, a [**deprecated version**](/docs/designers-developers/developers/block-api/block-deprecation.md) for the block should be added. + +## Class names and DOM updates + +Class names and DOM nodes used inside the tree of React components are not considered part of the public API and can be modified. + +Changes to these should be done with caution as it can affect the styling and behavior of third-party code (Even if they should not rely use these in first place). Keep the old ones if possible. If not, document these changes and write a dev note about the changes. ## Deprecations As the project evolves, flaws to existing APIs are discovered, or updates are required to support new features. When this happens, we try to guarantee that existing APIs don't break and build new alternative APIs. -To encourage third-party developers to adopt the new APIs instead, we can use the **deprecated** helper to show a message explaining the deprecation and proposing the alternative whenever the old API is used. +To encourage third-party developers to adopt the new APIs instead, we can use the [**deprecated**](/packages/deprecated/README.md) helper to show a message explaining the deprecation and proposing the alternative whenever the old API is used. ## Dev Notes @@ -50,8 +58,8 @@ Dev notes are [posts published on the make/core site](https://make.wordpress.org ### Dev Note Workflow -- When working on a pull request and the need for a dev note is discovered, add the **Needs Dev Note** label to the PR. -- If possible, add a comment to the PR explaining why the dev note is needed. -- When the first beta of the upcoming WordPress release is shipped, go through the list of merged PRs included in the release and tagged with the **Needs Dev Note** label. -- For each one of these PRs, write a dev note and coordinate with the WordPress release leads to publish the dev note. -- Once the dev note for a PR is published, remove the **Needs Dev Note** label from the PR. +* When working on a pull request and the need for a dev note is discovered, add the **Needs Dev Note** label to the PR. +* If possible, add a comment to the PR explaining why the dev note is needed. +* When the first beta of the upcoming WordPress release is shipped, go through the list of merged PRs included in the release and tagged with the **Needs Dev Note** label. +* For each one of these PRs, write a dev note and coordinate with the WordPress release leads to publish the dev note. +* Once the dev note for a PR is published, remove the **Needs Dev Note** label from the PR. From 902c23b189f83bfdde659e3d3e737cbe57ca8ab0 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 17:55:04 +0100 Subject: [PATCH 18/33] typo Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 18f1dcef1785d8..446b7b0a351bea 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -1,6 +1,6 @@ # Backward Compatibility -Historically WordPress has been known for preserving backward compatibility across versions. Gutenberg follows this example wherever possible in its production public APIs. There are rare occasions where breaking backward compatibility is unavoidable and in those cases the breakage: +Historically, WordPress has been known for preserving backward compatibility across versions. Gutenberg follows this example wherever possible in its production public APIs. There are rare occasions where breaking backward compatibility is unavoidable and in those cases the breakage: * should be constrained as much as possible to a small surface area of the API. * should be documented as clearly as possible to third-party developers using dev notes. From bd4b12d929c4a12fe522e18875db0e148beaab66 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 17:55:16 +0100 Subject: [PATCH 19/33] capitalize Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 446b7b0a351bea..551eb7589a28d7 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -3,7 +3,7 @@ Historically, WordPress has been known for preserving backward compatibility across versions. Gutenberg follows this example wherever possible in its production public APIs. There are rare occasions where breaking backward compatibility is unavoidable and in those cases the breakage: * should be constrained as much as possible to a small surface area of the API. -* should be documented as clearly as possible to third-party developers using dev notes. +* Should be documented as clearly as possible to third-party developers using Dev Notes. ## What qualifies as a production public API From bd01b83f1b19f04e5298d9e7e77b1480e3a7a276 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 17:55:26 +0100 Subject: [PATCH 20/33] capitalize Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 551eb7589a28d7..ff92a0a2249708 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -2,7 +2,7 @@ Historically, WordPress has been known for preserving backward compatibility across versions. Gutenberg follows this example wherever possible in its production public APIs. There are rare occasions where breaking backward compatibility is unavoidable and in those cases the breakage: -* should be constrained as much as possible to a small surface area of the API. +* Should be constrained as much as possible to a small surface area of the API. * Should be documented as clearly as possible to third-party developers using Dev Notes. ## What qualifies as a production public API From a3d2cd06d0ed593601e9612166ce7ba161623ed7 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 17:56:47 +0100 Subject: [PATCH 21/33] typo Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index ff92a0a2249708..63ce918c2afd62 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -11,7 +11,7 @@ The Gutenberg code base is composed of two different types of packages: - **production packages**: these are packages that are shipped as WordPress scripts (example: wp-components, wp-editor...). - **development packages**: these are made out of developer tools that can be used by third-party developers to lint, test, format and build their themes and plugins (example: @wordpress/scrips, @wordpress/env...). Typically, these are consumed as npm dependencies in third-party projects. -Backward compatibility guarantee only applies to the production packages as updates happen through WordPress upgrades. +Backward compatibility guarantees only apply to the production packages, as updates happen through WordPress upgrades. Production packages use the `wp` global variable to provide APIs to third-party developers. These APIs can be JavaScript functions, variables and React components. From 8ea94984537961eee4fe15bd29b6b19c921fb15c Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 17:58:03 +0100 Subject: [PATCH 22/33] typo Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 63ce918c2afd62..f3f9acd4136ae5 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -60,6 +60,6 @@ Dev notes are [posts published on the make/core site](https://make.wordpress.org * When working on a pull request and the need for a dev note is discovered, add the **Needs Dev Note** label to the PR. * If possible, add a comment to the PR explaining why the dev note is needed. -* When the first beta of the upcoming WordPress release is shipped, go through the list of merged PRs included in the release and tagged with the **Needs Dev Note** label. +* When the first beta of the upcoming WordPress release is shipped, go through the list of merged PRs included in the release that are tagged with the **Needs Dev Note** label. * For each one of these PRs, write a dev note and coordinate with the WordPress release leads to publish the dev note. * Once the dev note for a PR is published, remove the **Needs Dev Note** label from the PR. From 604d664c81c5a4c745d67b2631f9ff2806eb8df3 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 17:58:34 +0100 Subject: [PATCH 23/33] typo Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index f3f9acd4136ae5..3b4dde5ac966a1 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -25,7 +25,7 @@ Production packages use the `wp` global variable to provide APIs to third-party ### How to preserve backward compatibility for a React Component * The name of the component should not change. -* The props of the components should not be removed. +* The props of the component should not be removed. * Existing prop values should continue to be supported. If a component accepts a function as prop, we can update the component to accept a new type for the same prop, but it shouldn't break existing usage. * Adding new props is allowed. * React Context dependencies can only be added or removed if we ensure the previous context contract is not breaking. From b6c34430f9bd08feb9e57920c78f3c365b9546e1 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 17:59:07 +0100 Subject: [PATCH 24/33] typo Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 3b4dde5ac966a1..df612fd79af75b 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -26,7 +26,7 @@ Production packages use the `wp` global variable to provide APIs to third-party * The name of the component should not change. * The props of the component should not be removed. -* Existing prop values should continue to be supported. If a component accepts a function as prop, we can update the component to accept a new type for the same prop, but it shouldn't break existing usage. +* Existing prop values should continue to be supported. If a component accepts a function as a prop, we can update the component to accept a new type for the same prop, but it shouldn't break existing usage. * Adding new props is allowed. * React Context dependencies can only be added or removed if we ensure the previous context contract is not breaking. From 5c84ff071b3ae163fbe7adc1e659323de0b891d0 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 17:59:47 +0100 Subject: [PATCH 25/33] typo Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index df612fd79af75b..050b86d00cdfd1 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -34,7 +34,7 @@ Production packages use the `wp` global variable to provide APIs to third-party * Existing usage of the block should not break or be marked as invalid when the editor is loaded. * The styling of the existing blocks should be guaranteed. -* Markup changes should be limited to the minimum but If a block need to change its saved markup making previous versions invalid, a [**deprecated version**](/docs/designers-developers/developers/block-api/block-deprecation.md) for the block should be added. +* Markup changes should be limited to the minimum possible, but if a block needs to change its saved markup, making previous versions invalid, a [**deprecated version**](/docs/designers-developers/developers/block-api/block-deprecation.md) of the block should be added. ## Class names and DOM updates From 040329ae07fb5dce745854bc4ef89e3eef9411c2 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 18:00:39 +0100 Subject: [PATCH 26/33] typo Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 050b86d00cdfd1..aa08beaa6c43e1 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -44,7 +44,7 @@ Changes to these should be done with caution as it can affect the styling and be ## Deprecations -As the project evolves, flaws to existing APIs are discovered, or updates are required to support new features. When this happens, we try to guarantee that existing APIs don't break and build new alternative APIs. +As the project evolves, flaws of existing APIs are discovered, or updates are required to support new features. When this happens, we try to guarantee that existing APIs don't break and build new alternative APIs. To encourage third-party developers to adopt the new APIs instead, we can use the [**deprecated**](/packages/deprecated/README.md) helper to show a message explaining the deprecation and proposing the alternative whenever the old API is used. From 5b1659b48b806f4b43ee3f636e62e1f6b73735b9 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 18:01:17 +0100 Subject: [PATCH 27/33] typo Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index aa08beaa6c43e1..eb6818359d9471 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -46,7 +46,7 @@ Changes to these should be done with caution as it can affect the styling and be As the project evolves, flaws of existing APIs are discovered, or updates are required to support new features. When this happens, we try to guarantee that existing APIs don't break and build new alternative APIs. -To encourage third-party developers to adopt the new APIs instead, we can use the [**deprecated**](/packages/deprecated/README.md) helper to show a message explaining the deprecation and proposing the alternative whenever the old API is used. +To encourage third-party developers to adopt the new APIs instead, we can use the [**deprecated**](/packages/deprecated/README.md) helper to show a message explaining the deprecation and propose the alternative whenever the old API is used. ## Dev Notes From dd77784a4cfe811678eb498e183ff008bc5d49f8 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 18:01:57 +0100 Subject: [PATCH 28/33] clarification Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index eb6818359d9471..cbd52fb3ca5efb 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -51,7 +51,7 @@ To encourage third-party developers to adopt the new APIs instead, we can use th ## Dev Notes Dev notes are [posts published on the make/core site](https://make.wordpress.org/core/tag/dev-notes/) prior to WordPress releases to inform third-party developers about important changes to the developer APIs, these changes can include: -* Promote new APIs. +* New APIs. * Explain how some changes to existing APIs might affect existing plugins and themes (Example: classname changes...) * When breaking backward compatibility is unavoidable, explain the reasons and the migration flow. * When important deprecations are introduced (even without breakage), explain why and how third-party developers can update their code base in consequence. From 1b6da5095f705a87652c4ef3b571a3bdab350619 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 18:02:21 +0100 Subject: [PATCH 29/33] typo Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index cbd52fb3ca5efb..00eed5d4cff4d2 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -52,7 +52,7 @@ To encourage third-party developers to adopt the new APIs instead, we can use th Dev notes are [posts published on the make/core site](https://make.wordpress.org/core/tag/dev-notes/) prior to WordPress releases to inform third-party developers about important changes to the developer APIs, these changes can include: * New APIs. -* Explain how some changes to existing APIs might affect existing plugins and themes (Example: classname changes...) +* Changes to existing APIs that might affect existing plugins and themes. (Example: classname changes...) * When breaking backward compatibility is unavoidable, explain the reasons and the migration flow. * When important deprecations are introduced (even without breakage), explain why and how third-party developers can update their code base in consequence. From e4634716025b84f25c99b3ee6fee8ae37dfc0bb0 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 18:03:02 +0100 Subject: [PATCH 30/33] typo Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 00eed5d4cff4d2..e3289b057335f1 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -53,7 +53,7 @@ To encourage third-party developers to adopt the new APIs instead, we can use th Dev notes are [posts published on the make/core site](https://make.wordpress.org/core/tag/dev-notes/) prior to WordPress releases to inform third-party developers about important changes to the developer APIs, these changes can include: * New APIs. * Changes to existing APIs that might affect existing plugins and themes. (Example: classname changes...) -* When breaking backward compatibility is unavoidable, explain the reasons and the migration flow. +* Unavoidable backward compatibility breakage, with reasoning and migration flows. * When important deprecations are introduced (even without breakage), explain why and how third-party developers can update their code base in consequence. ### Dev Note Workflow From ffbb2aac01aa83bb004906560bde8198332d3d9f Mon Sep 17 00:00:00 2001 From: Enrique Piqueras Date: Thu, 14 Nov 2019 09:03:12 -0800 Subject: [PATCH 31/33] Update docs/designers-developers/developers/backward-compatibility/README.md --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index e3289b057335f1..87f0aea0b20610 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -40,7 +40,7 @@ Production packages use the `wp` global variable to provide APIs to third-party Class names and DOM nodes used inside the tree of React components are not considered part of the public API and can be modified. -Changes to these should be done with caution as it can affect the styling and behavior of third-party code (Even if they should not rely use these in first place). Keep the old ones if possible. If not, document these changes and write a dev note about the changes. +Changes to these should be done with caution as it can affect the styling and behavior of third-party code (Even if they should not rely on these in the first place). Keep the old ones if possible. If not, document the changes and write a dev note. ## Deprecations From d67aab3211e0eed24259ba2fc7c290e5e673bdf0 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 18:04:09 +0100 Subject: [PATCH 32/33] typo Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 87f0aea0b20610..8588f1cc99a593 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -54,7 +54,7 @@ Dev notes are [posts published on the make/core site](https://make.wordpress.org * New APIs. * Changes to existing APIs that might affect existing plugins and themes. (Example: classname changes...) * Unavoidable backward compatibility breakage, with reasoning and migration flows. -* When important deprecations are introduced (even without breakage), explain why and how third-party developers can update their code base in consequence. +* Important deprecations (even without breakage), with reasoning and migration flows. ### Dev Note Workflow From 09c4bae982c4aba7cd7deb41a28a90c4ca088b4e Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Thu, 14 Nov 2019 18:04:53 +0100 Subject: [PATCH 33/33] typo Co-Authored-By: Enrique Piqueras --- .../developers/backward-compatibility/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md index 8588f1cc99a593..da58849dec3223 100644 --- a/docs/designers-developers/developers/backward-compatibility/README.md +++ b/docs/designers-developers/developers/backward-compatibility/README.md @@ -9,7 +9,7 @@ Historically, WordPress has been known for preserving backward compatibility acr The Gutenberg code base is composed of two different types of packages: - **production packages**: these are packages that are shipped as WordPress scripts (example: wp-components, wp-editor...). - - **development packages**: these are made out of developer tools that can be used by third-party developers to lint, test, format and build their themes and plugins (example: @wordpress/scrips, @wordpress/env...). Typically, these are consumed as npm dependencies in third-party projects. + - **development packages**: these are made up of developer tools that can be used by third-party developers to lint, test, format and build their themes and plugins (example: @wordpress/scrips, @wordpress/env...). Typically, these are consumed as npm dependencies in third-party projects. Backward compatibility guarantees only apply to the production packages, as updates happen through WordPress upgrades.