Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update CONTRIBUTING.md: add Backwards Compatibility guide and update questions channels #1304

Merged
merged 7 commits into from
Jul 14, 2022
Merged

Update CONTRIBUTING.md: add Backwards Compatibility guide and update questions channels #1304

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ffd5b96
Add Backwards Compatibility guide to CONTRIBUTING.md
agryaznov Jun 27, 2022
553285a
important addition
agryaznov Jun 27, 2022
4429495
update the suggested questions channels
agryaznov Jun 27, 2022
b3e381d
Apply suggestions from code review
agryaznov Jun 28, 2022
1c57c9b
some more (tiny) corrections
agryaznov Jun 28, 2022
728d879
Wrap "Backwards Compatibility" section to 90 characters
HCastano Jul 14, 2022
a32251c
Tighten up wording a bit
HCastano Jul 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 33 additions & 5 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -27,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?)
Expand Down Expand Up @@ -64,6 +65,34 @@ 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 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 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 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.

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.
Expand Down Expand Up @@ -122,10 +151,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

Expand Down