From ffd5b960964e2e5d59da982d54e88feb3f83f86b Mon Sep 17 00:00:00 2001 From: Alexander Gryaznov Date: Mon, 27 Jun 2022 16:45:18 +0300 Subject: [PATCH 1/7] Add Backwards Compatibility guide to CONTRIBUTING.md --- CONTRIBUTING.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92d71578fb8..188bf19ac17 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,6 +9,7 @@ First of all, thank you for taking your time to contribute to ink! * [During Development](#during-development) * [Commits](#commits) * [Checklist](#checklist) + * [Backwards Compatibility](#backwards-compatibility) * [Continuous Integraton](#continuous-integration) * [Issues and Pull Requests](#issues-and-pull-requests) * [Issues](#issues) @@ -64,6 +65,22 @@ Following these will ensure that your pull request is going to be accepted. This might seem pedantic but we believe that in essence this is going to improve overall comment and documentation quality. 1. If possible try to sign your commits, e.g. using GPG keys. For more information about this go [here](https://help.github.com/en/articles/signing-commits). +### Backwards Compatibility + +ink! and pallet_contracts are the projects under active development. As contracts API functions evolve to their newer versions, we need to introduce them in ink! in a way that still keeps current *MAJOR* ink! version compatible with elder substrate nodes built with the pallet_contracts version having not this new functionality. + +In order to achieve this, please stick to the following workflow. + +Imagine there is a `[seal0] function()` in pallet\_contracts API and our `ink_env::function()` uses its import under the hood. +Then some time later we may decide to add a new `[seal1] function()` version to the pallet. In order to introduce it into ink! and still be able to run contracts (which don't use this particular function) on elder nodes, please do the following: + +1. Mark the old `ink_env::function()` (which depends on the imported `[seal0]` function) with the `#[deprecated]` attribute. + Please, specify the `since` field with the ink! version since which this function is deprecated in favor of the newest one, and is left there only for the backwards compatibility purposes. Specifing some additional helpful info in the `note` field could also be a good idea. +2. Name the new function (which depends on the `[seal1] function()`) somehow descriptive like `ink_env::function_whats_special()`. +3. Always add the `# Compatibility` section to the docs comment of the new function. + +You can have a look at the [PR#1284](https://github.com/paritytech/ink/pull/1284/files#diff-e7cc1cdb3856da1293c785de863703d5961c324aa2018decb0166ea1eb0631e8R191) for a reference of how the described way could be implemented. + ## Continuous Integration Our [continuous integration (CI)](https://github.com/paritytech/ink/blob/master/.gitlab-ci.yml) will check for the following properties of all changes. From 553285a6e8cb1c0e4d445c3f79469172986a7dde Mon Sep 17 00:00:00 2001 From: Alexander Gryaznov Date: Mon, 27 Jun 2022 16:50:25 +0300 Subject: [PATCH 2/7] important addition --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 188bf19ac17..fe5d89d34e5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -78,6 +78,7 @@ Then some time later we may decide to add a new `[seal1] function()` version to Please, specify the `since` field with the ink! version since which this function is deprecated in favor of the newest one, and is left there only for the backwards compatibility purposes. Specifing some additional helpful info in the `note` field could also be a good idea. 2. Name the new function (which depends on the `[seal1] function()`) somehow descriptive like `ink_env::function_whats_special()`. 3. Always add the `# Compatibility` section to the docs comment of the new function. +4. Never use the new function with existing language features. Only with newly added ones. You can have a look at the [PR#1284](https://github.com/paritytech/ink/pull/1284/files#diff-e7cc1cdb3856da1293c785de863703d5961c324aa2018decb0166ea1eb0631e8R191) for a reference of how the described way could be implemented. From 4429495edcc91a0ea6976f2a43a9631e979f82bd Mon Sep 17 00:00:00 2001 From: Alexander Gryaznov Date: Mon, 27 Jun 2022 17:36:02 +0300 Subject: [PATCH 3/7] update the suggested questions channels --- CONTRIBUTING.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe5d89d34e5..3519e5a5192 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -140,10 +140,9 @@ For a nice list of hints visit this [link][GitHub Perfect Pull Reqest]. ## I don't want to contribute, I just have some questions -For questions about the ink! project, about Parity Technologies or general technical -related questions you are welcome to contact us via [Element][Riot-Smart-Contracts-ink]. For -technical questions specifically about the ink! and its sub-projects you may also file an issue. -For more information about filing issues go [here](#issues-and-pull-requests). +For technical questions about the ink! and all other Polkadot projects, please post your questions to our [Stack Exchange community][Stack-Exchange-Link]. You can also stay tuned by joining our [Element channel][Riot-Smart-Contracts-ink] to be among first ones who gets our announcements. + +[Stack-Exchange-Link]: https://substrate.stackexchange.com [Riot-Smart-Contracts-ink]: https://riot.im/app/#/room/#ink:matrix.parity.io From b3e381dae92a05fe9ddccf2c80eb542ba0592861 Mon Sep 17 00:00:00 2001 From: Alexander Gryaznov Date: Tue, 28 Jun 2022 12:33:47 +0300 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Andrew Jones Co-authored-by: Hernando Castano --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3519e5a5192..9ddb542b8f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,18 +67,18 @@ Following these will ensure that your pull request is going to be accepted. ### Backwards Compatibility -ink! and pallet_contracts are the projects under active development. As contracts API functions evolve to their newer versions, we need to introduce them in ink! in a way that still keeps current *MAJOR* ink! version compatible with elder substrate nodes built with the pallet_contracts version having not this new functionality. +ink! and pallet_contracts are the projects under active development. As contracts API functions evolve to their newer versions, we need to introduce them in ink! in a way that still keeps current *MAJOR* ink! version compatible with older substrate nodes built with the pallet_contracts version without this new functionality. In order to achieve this, please stick to the following workflow. Imagine there is a `[seal0] function()` in pallet\_contracts API and our `ink_env::function()` uses its import under the hood. -Then some time later we may decide to add a new `[seal1] function()` version to the pallet. In order to introduce it into ink! and still be able to run contracts (which don't use this particular function) on elder nodes, please do the following: +Then some time later we may decide to add a new `[seal1] function()` version to the pallet. In order to introduce it into ink! and still be able to run contracts (which don't use this particular function) on older nodes, please do the following: 1. Mark the old `ink_env::function()` (which depends on the imported `[seal0]` function) with the `#[deprecated]` attribute. Please, specify the `since` field with the ink! version since which this function is deprecated in favor of the newest one, and is left there only for the backwards compatibility purposes. Specifing some additional helpful info in the `note` field could also be a good idea. 2. Name the new function (which depends on the `[seal1] function()`) somehow descriptive like `ink_env::function_whats_special()`. 3. Always add the `# Compatibility` section to the docs comment of the new function. -4. Never use the new function with existing language features. Only with newly added ones. +4. Never use the new function with existing language features. Only use it with newly added functions. You can have a look at the [PR#1284](https://github.com/paritytech/ink/pull/1284/files#diff-e7cc1cdb3856da1293c785de863703d5961c324aa2018decb0166ea1eb0631e8R191) for a reference of how the described way could be implemented. From 1c57c9bf8bca729741dd7c3dc3991b2ac7ce0407 Mon Sep 17 00:00:00 2001 From: Alexander Gryaznov Date: Tue, 28 Jun 2022 12:36:40 +0300 Subject: [PATCH 5/7] some more (tiny) corrections --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9ddb542b8f2..32ca9dd6f53 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,11 +67,11 @@ Following these will ensure that your pull request is going to be accepted. ### Backwards Compatibility -ink! and pallet_contracts are the projects under active development. As contracts API functions evolve to their newer versions, we need to introduce them in ink! in a way that still keeps current *MAJOR* ink! version compatible with older substrate nodes built with the pallet_contracts version without this new functionality. +ink! and pallet_contracts are the projects under active development. As Contracts API functions evolve to their newer versions, we need to introduce them in ink! in a way that still keeps current *MAJOR* ink! version compatible with older Substrate nodes built with the pallet_contracts version without this new functionality. In order to achieve this, please stick to the following workflow. -Imagine there is a `[seal0] function()` in pallet\_contracts API and our `ink_env::function()` uses its import under the hood. +Imagine there is a `[seal0] function()` in the Contracts pallet API and our `ink_env::function()` uses its import under the hood. Then some time later we may decide to add a new `[seal1] function()` version to the pallet. In order to introduce it into ink! and still be able to run contracts (which don't use this particular function) on older nodes, please do the following: 1. Mark the old `ink_env::function()` (which depends on the imported `[seal0]` function) with the `#[deprecated]` attribute. From 728d8795b3ac89f99aa864d264eab01a2950ae45 Mon Sep 17 00:00:00 2001 From: Hernando Castano Date: Thu, 14 Jul 2022 13:37:57 -0400 Subject: [PATCH 6/7] Wrap "Backwards Compatibility" section to 90 characters --- CONTRIBUTING.md | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 32ca9dd6f53..6fe87e965ad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,7 +28,7 @@ You can find our code of conduct [here](CODE_OF_CONDUCT.md). Don't be afraid to have a bunch of commits while working on a pull-request. We end up squashing all of them before merging to the `master` branch anyways. -But please keep your commits small and descriptive. A good rule of thumb is to +But please keep your commits small and descriptive. A good rule of thumb is to bundle semantic changes together in one commit. It makes the review process easier - which means you get a 🟩 from Github sooner (that's why you're contributing in the first place anyways, right?) @@ -67,18 +67,29 @@ Following these will ensure that your pull request is going to be accepted. ### Backwards Compatibility -ink! and pallet_contracts are the projects under active development. As Contracts API functions evolve to their newer versions, we need to introduce them in ink! in a way that still keeps current *MAJOR* ink! version compatible with older Substrate nodes built with the pallet_contracts version without this new functionality. +ink! and pallet_contracts are the projects under active development. As Contracts API +functions evolve to their newer versions, we need to introduce them in ink! in a way that +still keeps current *MAJOR* ink! version compatible with older Substrate nodes built with +the pallet_contracts version without this new functionality. In order to achieve this, please stick to the following workflow. -Imagine there is a `[seal0] function()` in the Contracts pallet API and our `ink_env::function()` uses its import under the hood. -Then some time later we may decide to add a new `[seal1] function()` version to the pallet. In order to introduce it into ink! and still be able to run contracts (which don't use this particular function) on older nodes, please do the following: - -1. Mark the old `ink_env::function()` (which depends on the imported `[seal0]` function) with the `#[deprecated]` attribute. - Please, specify the `since` field with the ink! version since which this function is deprecated in favor of the newest one, and is left there only for the backwards compatibility purposes. Specifing some additional helpful info in the `note` field could also be a good idea. -2. Name the new function (which depends on the `[seal1] function()`) somehow descriptive like `ink_env::function_whats_special()`. +Imagine there is a `[seal0] function()` in the Contracts pallet API and our +`ink_env::function()` uses its import under the hood. Then some time later we may decide +to add a new `[seal1] function()` version to the pallet. In order to introduce it into +ink! and still be able to run contracts (which don't use this particular function) on +older nodes, please do the following: + +1. Mark the old `ink_env::function()` (which depends on the imported `[seal0]` function) + with the `#[deprecated]` attribute. Please, specify the `since` field with the ink! + version since which this function is deprecated in favor of the newest one, and is + left there only for the backwards compatibility purposes. Specifing some additional + helpful info in the `note` field could also be a good idea. +2. Name the new function (which depends on the `[seal1] function()`) somehow descriptive + like `ink_env::function_whats_special()`. 3. Always add the `# Compatibility` section to the docs comment of the new function. -4. Never use the new function with existing language features. Only use it with newly added functions. +4. Never use the new function with existing language features. Only use it with newly + added functions. You can have a look at the [PR#1284](https://github.com/paritytech/ink/pull/1284/files#diff-e7cc1cdb3856da1293c785de863703d5961c324aa2018decb0166ea1eb0631e8R191) for a reference of how the described way could be implemented. From a32251c812c30f5203d150512c06db0a70052ba6 Mon Sep 17 00:00:00 2001 From: Hernando Castano Date: Thu, 14 Jul 2022 13:44:08 -0400 Subject: [PATCH 7/7] Tighten up wording a bit --- CONTRIBUTING.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6fe87e965ad..de5768148fb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,27 +67,27 @@ Following these will ensure that your pull request is going to be accepted. ### Backwards Compatibility -ink! and pallet_contracts are the projects under active development. As Contracts API -functions evolve to their newer versions, we need to introduce them in ink! in a way that -still keeps current *MAJOR* ink! version compatible with older Substrate nodes built with -the pallet_contracts version without this new functionality. +ink! and `pallet-contracts` are projects under active development. As the Contracts API +functions evolve to their newer versions we need to introduce them in ink! in a way that +keeps the current *MAJOR* ink! versions compatible with older Substrate nodes which +may not have these new API function. In order to achieve this, please stick to the following workflow. Imagine there is a `[seal0] function()` in the Contracts pallet API and our -`ink_env::function()` uses its import under the hood. Then some time later we may decide +`ink_env::function()` uses its import under the hood. Then some time later we decide to add a new `[seal1] function()` version to the pallet. In order to introduce it into ink! and still be able to run contracts (which don't use this particular function) on older nodes, please do the following: 1. Mark the old `ink_env::function()` (which depends on the imported `[seal0]` function) - with the `#[deprecated]` attribute. Please, specify the `since` field with the ink! - version since which this function is deprecated in favor of the newest one, and is - left there only for the backwards compatibility purposes. Specifing some additional - helpful info in the `note` field could also be a good idea. -2. Name the new function (which depends on the `[seal1] function()`) somehow descriptive - like `ink_env::function_whats_special()`. -3. Always add the `# Compatibility` section to the docs comment of the new function. + with the `#[deprecated]` attribute. Please, specify the `since` field with the ink! + version which will introduce the new API. We will leave this function in for backwards + compatibility purposes. Specifing some additional helpful info in the `note` field + could also be a good idea. +2. Name the new function (which depends on the `[seal1] function()`) in a descriptive + way, like `ink_env::function_whats_special()`. +3. Add the `# Compatibility` section to the docs comment of the new function. 4. Never use the new function with existing language features. Only use it with newly added functions.