add compatibility notice (#861)

* add compatibility notice

* add changelog

* remove unused alias

* Update docs/modules/ROOT/pages/backwards-compatibility.adoc

Co-authored-by: Andrew Fleming <fleming-andrew@protonmail.com>

* apply review comments

* Update docs/modules/ROOT/pages/upgrades.adoc

Co-authored-by: Andrew Fleming <fleming-andrew@protonmail.com>

---------

Co-authored-by: Andrew Fleming <fleming-andrew@protonmail.com>

CHANGELOG.md

@@ -13,10 +13,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Usage docs (#823)
 - Utilities documentation (#825)
 - Documentation for presets (#832)
+- Backwards compatibility notice (#861)
 
 ### Changed
 
 - Use ComponentState in tests (#836)
 - Docsite navbar (#838)
 - Support higher tx versions in Account (#858)
 - Bump scarb to v2.4.1 (#858)
+- Add security section to Upgrades docs (#861)

docs/modules/ROOT/nav.adoc

@@ -6,7 +6,7 @@
 ** xref:components.adoc[Components]
 ** xref:presets.adoc[Presets]
 ** xref:interfaces.adoc[Interfaces and Dispatchers]
-** xref:guides/deployment.adoc[Counterfactual deployments]
+** xref:guides/deployment.adoc[Counterfactual Deployments]
 // ** xref:udc.adoc[Universal Deployer Contract]
 
 * Modules
@@ -37,4 +37,5 @@
 
 ** xref:utilities.adoc[Utilities]
 
+* xref:backwards-compatibility.adoc[Backwards Compatibility]
 * xref:contracts::index.adoc[Contracts for Solidity]

docs/modules/ROOT/pages/backwards-compatibility.adoc

@@ -0,0 +1,31 @@
+= Backwards Compatibility
+
+OpenZeppelin Contracts uses semantic versioning to communicate backwards compatibility of its API and storage layout. Patch and minor updates will generally be backwards compatible, with rare exceptions as detailed below. Major updates should be assumed incompatible with previous releases. On this page, we provide details about these guarantees.
+
+Bear in mind that while releasing versions under `v1.0.0`, we treat minors as majors and patches as minors, in accordance with semantic versioning. This means that `v0.7.1` could be adding features to `v0.7.0`, while `v0.8.0` would be considered a breaking release.
+
+== API
+
+In backwards compatible releases, all changes should be either additions or modifications to internal implementation details. Most code should continue to compile and behave as expected. The exceptions to this rule are listed below.
+
+=== Security
+
+Infrequently, a patch or minor update will remove or change an API in a breaking way but only if the previous API is considered insecure. These breaking changes will be noted in the changelog and release notes, and published along with a security advisory.
+
+=== Errors
+
+The specific error format and data that is included with reverts should not be assumed stable unless otherwise specified.
+
+=== Major releases
+
+Major releases should be assumed incompatible. Nevertheless, the external interfaces of contracts will remain compatible if they are standardized, or if the maintainers judge that changing them would cause significant strain on the ecosystem.
+
+An important aspect that major releases may break is "upgrade compatibility", in particular storage layout compatibility. It will never be safe for a live contract to upgrade from one major release to another.
+
+== Storage layout
+
+Patch updates will always preserve storage layout compatibility, and after `v1.0.0` minors will too. This means that a live contract can be upgraded from one minor to another without corrupting the storage layout. In some cases it may be necessary to initialize new state variables when upgrading, although we expect this to be infrequent.
+
+== Cairo version
+
+The minimum Cairo version required to compile the contracts will remain unchanged for patch updates, but it may change for minors.

docs/modules/ROOT/pages/upgrades.adoc

@@ -10,7 +10,9 @@
 
 In different blockchains, multiple patterns have been developed for making a contract upgradeable including the widely adopted proxy patterns.
 
-Starknet has native upgradeability through a syscall that updates the contract source code, removing the need for proxies.
+Starknet has native upgradeability through a syscall that updates the contract source code, removing xref:#proxies_in_starknet[the need for proxies].
+
+WARNING: Make sure you follow xref:#security[our security recommendations] before upgrading.
 
 == Replacing contract classes
 
@@ -101,7 +103,16 @@ mod UpgradeableContract {
 }
 ----
 
-== Proxies and Starknet
+== Security
+
+Upgrades can be very sensitive operations, and security should always be top of mind while performing one. Please make sure you thoroughly review the changes and their consequences before upgrading. Some aspects to consider are:
+
+- API changes that might affect integration. For example, changing an external function's arguments might break existing contracts or offchain systems calling your contract.
+- Storage changes that might result in lost data (e.g. changing a storage slot name, making existing storage inaccessible).
+- Collisions (e.g. mistakenly reusing the same storage slot from another component) are also possible, although less likely if best practices are followed, for example prepending storage variables with the component's name (e.g. `ERC20_balances`).
+- Always check for xref:backwards-compatibility.adoc[backwards compatibility] before upgrading between versions of OpenZeppelin Contracts.
+
+== Proxies in Starknet
 
 Proxies enable different patterns such as upgrades and clones. But since Starknet achieves the same in different ways is that there's no support to implement them.
 

docs/modules/ROOT/pages/wizard.adoc

@@ -2,7 +2,7 @@
 :page-notoc:
 
 Not sure where to start? Use the interactive generator below to bootstrap your
-contract and learn about the components offered in OpenZeppelin Cairo Contracts.
+contract and learn about the components offered in OpenZeppelin Contracts for Cairo.
 
 
 NOTE: We strongly recommend checking the xref:components.adoc[Components] section to understand how to extend from our library.