Update CONTRIBUTING.md: add Backwards Compatibility guide and update questions channels #1304
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
agryaznov
requested review from
Robbepop,
cmichi,
ascjones and
HCastano
as code owners
🦑 📈 ink! Example Contracts ‒ Changes Report 📉 🦑These are the results when building the
Link to the run | Last update: Tue Jun 28 12:16:47 CEST 2022 |
Codecov Report
@@ Coverage Diff @@
## master #1304 +/- ##
===========================================
- Coverage 71.94% 47.11% -24.84%
===========================================
Files 177 176 -1
Lines 5950 5920 -30
===========================================
- Hits 4281 2789 -1492
- Misses 1669 3131 +1462
Continue to review full report at Codecov.
|
agryaznov
changed the title
ascjones
reviewed
Jun 27, 2022
HCastano
reviewed
Jun 27, 2022
CONTRIBUTING.md
Outdated
| @@ -64,6 +65,23 @@ 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. | |||
There was a problem hiding this comment.
Suggested change
| 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 (denoted by the `seal_*` prefix) 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. These older nodes may have a version of the Contracts pallet which does not support new seal APIs. |
There was a problem hiding this comment.
left it to be Andrew's variant for the sake of concise
CONTRIBUTING.md
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
Suggested change
| 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 Contract pallet API and our `ink_env::function()` imports it under the hood. |
There was a problem hiding this comment.
well function does not import, it uses an imported one
CONTRIBUTING.md
Outdated
|
|
||
| 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()`. |
There was a problem hiding this comment.
Mark all of these as 1, the markdown render will handle the numbering
There was a problem hiding this comment.
well, this is an optional feature, btw it will work so even if you mark it with a randomly assigned set of integer numbers as well. However, I think it's good to have it numbered properly in the source itself.
CONTRIBUTING.md
Outdated
| 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. |
There was a problem hiding this comment.
Suggested change
| 3. Always add the `# Compatibility` section to the docs comment of the new function. | |
| 3. Add a `# Compatibility` section to the docs comment of the new function. |
|
Oh btw, can you wrap everything to 90 characters? |
Co-authored-by: Andrew Jones <ascjones@gmail.com> Co-authored-by: Hernando Castano <HCastano@users.noreply.github.com>
HCastano
approved these changes
Jul 14, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
follow up to #1284