diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92d71578fb..de5768148f 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) @@ -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?) @@ -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. @@ -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