apply upgradeable patches

commit 03602a7eb71f4304fac032a7079c45b456bd3d5c
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Thu Nov 12 13:00:50 2020 -0300

    rename to upgradeable

    (cherry picked from commit 5f4bef56)

commit 371ac8fe938e081ecc802021ee930338c8db4b31
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 21:25:19 2020 -0300

    improve changelog upgrade from ethereum-package instructions

    (cherry picked from commit c8fe2efb)

commit 93ab44794ea508c2a590db62fa0cdd0e536051e4
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 17:47:15 2020 -0300

    Clean Buidler cache before publishing

    (cherry picked from commit 679b7d14)

commit 39d68d6baf6ac4b45dea9752a03c44c4886d3a0d
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 16:56:51 2020 -0300

    update package.json urls

    (cherry picked from commit a34f1983)

commit 39f850e3a5f7bede8ccf62a0ae2e6896f4cee100
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 16:43:23 2020 -0300

    fix transpile-onto.sh

    (cherry picked from commit 1b6b9f00)

commit 2828e1f7c33cc5808cb10dd66a2196c886bfc9d5
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 16:22:16 2020 -0300

    add changelog section for upgrade-safe variant

    (cherry picked from commit 5ca793d6)

commit 00a3ca9984e940feca09150d6f4a9ae0aca43541
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 15:06:02 2020 -0300

    improve transpile-branch.sh script

    (cherry picked from commit d4315671)

commit 08aa9dc8fe31a243ce43ee0c5597aa1244eb7b4c
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 12:49:23 2020 -0300

    Run tests on release branches

    (cherry picked from commit cb19930b)

commit 15ed7c10b8719b60ffa6d3665e437e4737d52d01
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 14:28:55 2020 -0300

    rename npm package

commit 00db82ca9000ade3ca3b7490b309f0cb7dbfeffe
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 14:22:02 2020 -0300

    refactor github actions that use git

commit e61eedb2b473b1fb7ba24f8effa54bae8ad454ae
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 14:18:44 2020 -0300

    transpile in CI only for pull requests

commit 866b276262c0c7a7cabd9f2537c4a1ce0191cd4a
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 11:43:26 2020 -0300

    repurpose transpile-push script to transpile-branch

commit 2f8c130bad6f883ac271258c9d52a658f1615ed9
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 11:26:54 2020 -0300

    refactor git user config in scripts

commit 80b5df89140076a31e262153d24f4a68ee07b82b
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 11:25:34 2020 -0300

    move scripts to subdirectory

commit c72ba203b8337abed8d85527a0690d2895c39bff
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 00:23:54 2020 -0300

    edit readme with upgrade safe specific content

commit 84bf744dc76ca6a0d42a1627b928a4c4695336eb
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Nov 11 00:20:51 2020 -0300

    configure transpiler to emit public initializers for presets

commit efdc7fdc030582239f04103c64c5e38352af5247
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue Nov 10 23:43:25 2020 -0300

    allow artifacts.require to return unmodified contracts

commit 550092e33b3008c26352418fe44bd4eb9663daf7
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue Nov 10 23:40:10 2020 -0300

    configure transpiler to use built in Initializable and exclude all proxies

commit cf8341ded444b1d3dc0b4ffb2519db4fbb9e57a0
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue Nov 10 21:42:08 2020 -0300

    enable running tests in PRs

commit c91b8dcfff6fed73ebf035a4c02d6b1278dc39b3
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Mon Nov 9 17:32:47 2020 -0300

    add description of custom buidler get-files task

commit 744dde9364409a1e1b12778034b753e3b5c1c082
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Mon Nov 9 17:32:01 2020 -0300

    add storageLayout to solc output selection

commit 6724d527f948f15cbfd7bbb7a074f56c711316a4
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Mon Nov 9 17:28:13 2020 -0300

    update transpile task to print message when there is nothing to push

commit 4affd44d261b15c4cd8a5646308ef84285749207
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Mon Nov 9 17:02:52 2020 -0300

    define ref for transpile workflow explicitly

commit 483169a545adc9838f0f48f9b8b2380eb89a4f07
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Mon Nov 9 16:57:13 2020 -0300

    enable manual dispatch of transpile task

commit 1dff4b025780f000491233aab946cc07d5facb54
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Mon Nov 9 16:56:19 2020 -0300

    eddit merge-upstream commit message

commit c7b6813584f1047e7215d0166078eb86358ff3b7
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 23:48:17 2020 -0300

    do not fail if there are no changes to commit

commit abd34b0a188bb0507135b5b4969fa4ba9262532e
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 23:37:47 2020 -0300

    change upstream url

commit 748690c4452d51f75548136d26c7614484fe2d8c
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 23:24:51 2020 -0300

    skip npm ci if cache hit

commit 160c1023a23b8e88b51c1ebdee27d1a955fa6b1b
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 23:20:42 2020 -0300

    disable coverage

commit fd409e7094284d03470ef6279ae219771a144577
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 23:10:06 2020 -0300

    clean up actions before running merge upstream

commit 8753e7e80a54f20f3561c3ad409e6a955092adb4
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 23:08:39 2020 -0300

    cache node_modules in github actions

commit 9f53c76a338b5ec90c27a6a273ef490d60949dbb
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 22:53:00 2020 -0300

    use ssh key for git checkout in transpile worfklow

commit c857dcf2c95522e2b930a3e89c4993e78039a0c0
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 22:50:09 2020 -0300

    disable linter

commit dd1a5c75488a61786585657249a19a2185d79b36
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 22:48:39 2020 -0300

    rename patch-upstream workflow to merge-upstream

commit 578c28d2e0b51cc35da5fd933ff6fc941b563184
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 22:47:34 2020 -0300

    use ssh deploy key for git checkout

commit 7c6169e8098765181deb9569aaf040cdea1bd910
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 21:16:43 2020 -0300

    fix transpile-push.sh script

commit f4028afc467abc8adebec52dcf71d4bcf11cea0a
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 21:13:56 2020 -0300

    improve transpile-push.sh script

commit a85984ed93ba08e0113210dc4ab3c0c8dc4ccb58
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 20:22:00 2020 -0300

    Refactor transpile scripts

commit b00286f578508d457636be36b425ad80f37cb98c
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 19:46:44 2020 -0300

    Remove proxy-related contracts from package

commit 796f2410950017f32e4036c6ffa3441484d32dd4
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 15:27:16 2020 -0300

    Add initial transpiler setup

commit def46e3684a5bb60d13db09f802ef3faebe43eef
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Fri Nov 6 18:52:00 2020 -0300

    Add patch-upstream GitHub Actions Workflow

.github/workflows/merge-upstream.yml

+name: Merge upstream
+
+on:
+  workflow_dispatch: {}
+  schedule:
+    - cron: '0 10 * * *'
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: rokroskar/workflow-run-cleanup-action@v0.2.2
+        env:
+          GITHUB_TOKEN: ${{github.token}}
+      - uses: actions/checkout@v2
+        with:
+          ref: upstream-patched
+          fetch-depth: 0
+          ssh-key: ${{secrets.DEPLOY_KEY}}
+      - run: bash scripts/upgradeable/git-user-config.sh
+      - run: bash scripts/upgradeable/merge-upstream.sh
+      - run: git push

.github/workflows/test.yml

@@ -2,7 +2,9 @@ name: Test
 
 on:
   push:
-    branches: [master]
+    branches:
+      - master
+      - release-v*
   pull_request: {}
 
 jobs:
@@ -21,23 +23,6 @@ jobs:
           restore-keys: npm-v2-
       - run: npm ci
         if: steps.cache.outputs.cache-hit != 'true'
-      - run: npm run lint
+      - run: bash scripts/upgradeable/transpile.sh
+        if: github.event_name == 'pull_request'
       - run: npm run test
-
-  coverage:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v1
-        with:
-          node-version: 10.x
-      - uses: actions/cache@v2
-        id: cache
-        with:
-          path: '**/node_modules'
-          key: npm-v2-${{ hashFiles('**/package-lock.json') }}
-          restore-keys: npm-v2-
-      - run: npm ci
-        if: steps.cache.outputs.cache-hit != 'true'
-      - run: npm run coverage
-      - uses: codecov/codecov-action@v1

.github/workflows/transpile.yml

+name: Transpile
+
+on:
+  workflow_dispatch: {}
+  push:
+    branches: [upstream-patched]
+
+jobs:
+  transpile:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: rokroskar/workflow-run-cleanup-action@v0.2.2
+        env:
+          GITHUB_TOKEN: ${{github.token}}
+      - uses: actions/checkout@v2
+        with:
+          ref: upstream-patched
+          fetch-depth: 0
+          ssh-key: ${{secrets.DEPLOY_KEY}}
+      - uses: actions/setup-node@v1
+        with:
+          node-version: 10.x
+      - uses: actions/cache@v2
+        id: cache
+        with:
+          path: '**/node_modules'
+          key: npm-v2-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: npm-v2-
+      - run: npm ci
+        if: steps.cache.outputs.cache-hit != 'true'
+      - run: bash scripts/upgradeable/git-user-config.sh
+      - run: bash scripts/upgradeable/transpile-onto.sh master origin/master
+      - run: git push origin master

CHANGELOG.md

+# Changelog for Upgradeable variant
+
+## 3.2.0 (2020-11-11)
+
+ * First release of Upgradeable variant, replacing Ethereum Package variant which is now deprecated.
+
+### Upgrading from OpenZeppelin Contracts Ethereum Package
+
+ * The dependency on `@openzeppelin/contracts-ethereum-package` should be replaced by `@openzeppelin/contracts-upgradeable`.
+ * All contracts, interfaces, and libraries now have an `Upgradeable` suffix, instead of the `UpgradeSafe` suffix that only contracts used to have. The only exception is the `Initializable` contract which retains its original name.
+   * `Address` → `AddressUpgradeable`
+   * `ERC20UpgradeSafe` → `ERC20Upgradeable`
+   * This change improves compatibility with the main OpenZeppelin Contracts package, allowing both to be used side by side.
+ * Solidity files are now also suffixed, to keep the Solidity convention of equal file and contract name.
+   * `access/Ownable.sol` → `access/OwnableUpgradeable.sol`
+ * Import paths no longer include `/contracts/`.
+   * `@openzeppelin/contracts-ethereum-package/contracts/access/Ownable.sol` → `@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol`
+
 # Changelog
 
 ## 3.2.2-solc-0.7 (2020-10-28)

README.md

-# <img src="logo.svg" alt="OpenZeppelin" height="40px">
+# <img src="icon.svg" alt="OpenZeppelin" height="40px" align="left"> OpenZeppelin Contracts Upgradeable
 
-[![Docs](https://img.shields.io/badge/docs-%F0%9F%93%84-blue)](https://docs.openzeppelin.com/contracts)
-[![NPM Package](https://img.shields.io/npm/v/@openzeppelin/contracts.svg)](https://www.npmjs.org/package/@openzeppelin/contracts)
-[![Coverage Status](https://codecov.io/gh/OpenZeppelin/openzeppelin-contracts/graph/badge.svg)](https://codecov.io/gh/OpenZeppelin/openzeppelin-contracts)
+[![Docs](https://img.shields.io/badge/docs-%F0%9F%93%84-blue)](https://docs.openzeppelin.com/contracts/upgradeable)
+[![NPM Package](https://img.shields.io/npm/v/@openzeppelin/contracts-upgradeable.svg)](https://www.npmjs.org/package/@openzeppelin/contracts-upgradeable)
 
-**A library for secure smart contract development.** Build on a solid foundation of community-vetted code.
+This repository hosts the Upgradeable variant of [OpenZeppelin Contracts], meant for use in upgradeable contracts. This variant is available as separate package called `@openzeppelin/contracts-upgradeable`.
 
- * Implementations of standards like [ERC20](https://docs.openzeppelin.com/contracts/erc20) and [ERC721](https://docs.openzeppelin.com/contracts/erc721).
- * Flexible [role-based permissioning](https://docs.openzeppelin.com/contracts/access-control) scheme.
- * Reusable [Solidity components](https://docs.openzeppelin.com/contracts/utilities) to build custom contracts and complex decentralized systems.
- * First-class integration with the [Gas Station Network](https://docs.openzeppelin.com/contracts/gsn) for systems with no gas fees!
- * Audited by leading security firms (_last full audit on v2.0.0_).
+[OpenZeppelin Contracts]: https://github.com/OpenZeppelin/openzeppelin-contracts
+
+It follows all of the rules for xref:upgrades-plugins::writing-upgradeable.adoc[Writing Upgradeable Contracts]: constructors are replaced by initializer functions, state variables are initialized in initializer functions, and we additionally check for storage incompatibilities across minor versions.
+
+[Writing Upgradeable Contracts]: https://docs.openzeppelin.com/upgrades-plugins/writing-upgradeable
 
 ## Overview
 
 ### Installation
 
 ```console
-$ npm install @openzeppelin/contracts
+$ npm install @openzeppelin/contracts-upgradeable
 ```
 
-OpenZeppelin Contracts features a [stable API](https://docs.openzeppelin.com/contracts/releases-stability#api-stability), which means your contracts won't break unexpectedly when upgrading to a newer minor version.
-
 ### Usage
 
-Once installed, you can use the contracts in the library by importing them:
+The package replicates the structure of the main OpenZeppelin Contracts package, but every file and contract has the suffix `Upgradeable`.
 
-```solidity
-pragma solidity ^0.7.0;
+```diff
+-import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
++import "@openzeppelin/contracts-upgradeable/token/ERC721/ERC721Upgradeable.sol";
+ 
+-contract MyCollectible is ERC721 {
++contract MyCollectible is ERC721Upgradeable {
+```
 
-import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
+Constructors are replaced by internal initializer functions following the naming convention `__{ContractName}_init`. Since these are internal, you must always define your own public initializer function and call the parent initializer of the contract you extend.
 
-contract MyCollectible is ERC721 {
-    constructor() ERC721("MyCollectible", "MCO") {
-    }
-}
+```diff
+-    constructor() ERC721("MyCollectible", "MCO") {
++    function initialize() initializer public {
++        __ERC721_init("MyCollectible", "MCO");
+     }
 ```
 
+> **Caution**
+>
+> Use with multiple inheritance requires special care. Initializer functions are not linearized by the compiler like constructors. Because of this, each `__{ContractName}_init` function embeds the linearized calls to all parent initializers. As a consequence, calling two of these `init` functions can potentially initialize the same contract twice.
+>
+> The function `__{ContractName}_init_unchained` found in every contract is the initializer function minus the calls to parent initializers, and can be used to avoid the double initialization problem, but doing this manually is not recommended. We hope to be able to implement safety checks for this in future versions of the Upgrades Plugins.
+
 _If you're new to smart contract development, head to [Developing Smart Contracts](https://docs.openzeppelin.com/learn/developing-smart-contracts) to learn about creating a new project and compiling your contracts._
 
 To keep your system secure, you should **always** use the installed code as-is, and neither copy-paste it from online sources, nor modify it yourself. The library is designed so that only the contracts and functions you use are deployed, so you don't need to worry about it needlessly increasing gas costs.

buidler/env-artifacts.js

+const { BuidlerError } = require('@nomiclabs/buidler/internal/core/errors');
+
+extendEnvironment(env => {
+  const { artifacts } = env;
+
+  env.artifacts = {
+    ...artifacts,
+    require (name) {
+      for (const suffix of ['UpgradeableWithInit', 'Upgradeable', '']) {
+        try {
+          return artifacts.require(name + suffix);
+        } catch (e) {
+          if (BuidlerError.isBuidlerError(e) && e.number === 700 && suffix !== '') {
+            continue;
+          } else {
+            throw e;
+          }
+        }
+      }
+      throw new Error('Unreachable');
+    },
+  };
+});

buidler/task-get-compiler-input.js

+// adds storageLayout to solc outputSelection, necessary for storage gaps
+
+const { internalTask } = require('@nomiclabs/buidler/config');
+const { TASK_COMPILE_GET_COMPILER_INPUT } = require('@nomiclabs/buidler/builtin-tasks/task-names');
+
+internalTask(TASK_COMPILE_GET_COMPILER_INPUT, async (args, bre, runSuper) => {
+  const input = await runSuper();
+  input.settings.outputSelection['*']['*'].push('storageLayout');
+  return input;
+});

buidler/task-test-get-files.js

+// ignores the proxy tests
+
+const { internalTask } = require('@nomiclabs/buidler/config');
+
+const { TASK_TEST_GET_TEST_FILES } = require('@nomiclabs/buidler/builtin-tasks/task-names');
+const glob = require('glob');
+const path = require('path');
+const { promisify } = require('util');
+
+internalTask(TASK_TEST_GET_TEST_FILES)
+  .setAction(async ({ testFiles }, { config }) => {
+    if (testFiles.length !== 0) {
+      return testFiles;
+    }
+    return await promisify(glob)(
+      path.join(config.paths.tests, '**/*.js'),
+      { ignore: [path.join(config.paths.tests, 'proxy/**/*')] },
+    );
+  });

contracts/package.json

 {
-  "name": "@openzeppelin/contracts",
+  "name": "@openzeppelin/contracts-upgradeable",
   "description": "Secure Smart Contract library for Solidity",
   "version": "3.2.2-solc-0.7",
   "files": [
@@ -14,7 +14,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/OpenZeppelin/openzeppelin-contracts.git"
+    "url": "https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable.git"
   },
   "keywords": [
     "solidity",
@@ -27,7 +27,7 @@
   "author": "OpenZeppelin Community <maintainers@openzeppelin.org>",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/OpenZeppelin/openzeppelin-contracts/issues"
+    "url": "https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable/issues"
   },
   "homepage": "https://openzeppelin.com/contracts/"
 }

docs/modules/ROOT/nav.adoc

 * xref:index.adoc[Overview]
 * xref:extending-contracts.adoc[Extending Contracts]
-* xref:upgrade-safe.adoc[Using with Upgrades]
+* xref:upgradeable.adoc[Using with Upgrades]
 
 * xref:releases-stability.adoc[Releases & Stability]
 

docs/modules/ROOT/pages/upgrade-safe.adoc → docs/modules/ROOT/pages/upgradeable.adoc

 = Using with Upgrades
 
-If your contract is going to be deployed with upgradeability, such as using the xref:upgrades-plugins::index.adoc[OpenZeppelin Upgrades Plugins], you will need to use the Upgrade Safe variant of OpenZeppelin Contracts.
+If your contract is going to be deployed with upgradeability, such as using the xref:upgrades-plugins::index.adoc[OpenZeppelin Upgrades Plugins], you will need to use the Upgradeable variant of OpenZeppelin Contracts.
 
-This variant is available as a separate package called `@openzeppelin/contracts-upgrade-safe`, which is hosted in the repository https://github.com/OpenZeppelin/openzeppelin-contracts-upgrade-safe[OpenZeppelin/openzeppelin-contracts-upgrade-safe].
+This variant is available as a separate package called `@openzeppelin/contracts-upgradeable`, which is hosted in the repository https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable[OpenZeppelin/openzeppelin-contracts-upgradeable].
 
 It follows all of the rules for xref:upgrades-plugins::writing-upgradeable.adoc[Writing Upgradeable Contracts]: constructors are replaced by initializer functions, state variables are initialized in initializer functions, and we additionally check for storage incompatibilities across minor versions.
 
@@ -11,19 +11,19 @@ It follows all of the rules for xref:upgrades-plugins::writing-upgradeable.adoc[
 === Installation
 
 ```console
-$ npm install @openzeppelin/contracts-upgrade-safe
+$ npm install @openzeppelin/contracts-upgradeable
 ```
 
 === Usage
 
-The package replicates the structure of the main OpenZeppelin Contracts package, but every file and contract has the suffix `UpgradeSafe`.
+The package replicates the structure of the main OpenZeppelin Contracts package, but every file and contract has the suffix `Upgradeable`.
 
 ```diff
 -import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
-+import "@openzeppelin/contracts-upgrade-safe/token/ERC721/ERC721UpgradeSafe.sol";
++import "@openzeppelin/contracts-upgradeable/token/ERC721/ERC721Upgradeable.sol";
  
 -contract MyCollectible is ERC721 {
-+contract MyCollectible is ERC721UpgradeSafe {
++contract MyCollectible is ERC721Upgradeable {
 ```
 
 Constructors are replaced by internal initializer functions following the naming convention `+__{ContractName}_init+`. Since these are internal, you must always define your own public initializer function and call the parent initializer of the contract you extend.
@@ -66,6 +66,6 @@ The function `+__{ContractName}_init_unchained+` found in every contract is the
 
 === Storage Gaps
 
-You may notice that every contract includes a state variable named `+__gap+`. This is empty reserved space in storage that is put in place in Upgrade Safe contracts. It allows us to freely add new state variables in the future without compromising the storage compatibility with existing deployments.
+You may notice that every contract includes a state variable named `+__gap+`. This is empty reserved space in storage that is put in place in Upgradeable contracts. It allows us to freely add new state variables in the future without compromising the storage compatibility with existing deployments.
 
 It isn't safe to simply add a state variable because it "shifts down" all of the state variables below in the inheritance chain. This makes the storage layouts incompatible, as explained in xref:upgrades-plugins::writing-upgradeable.adoc#modifying-your-contracts[Writing Upgradeable Contracts]. The size of the `+__gap+` array is calculated so that the amount of storage used by a contract always adds up to the same number (in this case 50 storage slots).

icon.svg

+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="180px" height="200px" viewBox="0 0 180 200" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <!-- Generator: Sketch 53.2 (72643) - https://sketchapp.com -->
+    <title>OZ_icon_color</title>
+    <desc>Created with Sketch.</desc>
+    <g id="presentación" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="OZ_icon_color">
+            <path d="M179.670444,199.932333 L179.670444,147.932333 L123.270887,147.932333 C107.93329,147.932333 93.7259335,156.016333 85.8704806,169.214333 L67.5860074,199.932333 L179.670444,199.932333 Z" id="Stroke-1" fill="#63D2F9"></path>
+            <polygon id="Stroke-3" fill="#4E5EE4" points="0.166292052 0.1667 0.166292052 52.1667 148.717863 52.1667 179.670543 0.1667"></polygon>
+            <path d="M71.2615009,81.4347667 L0.329855823,199.932433 L60.7619445,199.932433 L145.583534,58.1667667 L112.212665,58.1667667 C95.4274159,58.1667667 79.8768799,67.0024333 71.2615009,81.4347667 Z" id="Stroke-5" fill="#63B0F9"></path>
+        </g>
+    </g>
+</svg>
\ No newline at end of file

package.json

 {
+  "private": true,
   "name": "openzeppelin-solidity",
   "description": "Secure Smart Contract library for Solidity",
   "version": "3.2.2-solc-0.7",
@@ -6,6 +7,7 @@
     "/contracts/**/*.sol",
     "/build/contracts/*.json",
     "!/contracts/mocks",
+    "!/contracts/proxy",
     "/test/behaviors"
   ],
   "scripts": {
@@ -19,7 +21,7 @@
     "lint:js": "eslint --ignore-path .gitignore .",
     "lint:js:fix": "eslint --ignore-path .gitignore . --fix",
     "lint:sol": "solhint --max-warnings 0 \"contracts/**/*.sol\"",
-    "prepublish": "rimraf build contracts/build artifacts",
+    "prepublish": "rimraf build contracts/build artifacts cache",
     "prepare": "npm run compile",
     "prepack": "scripts/prepack.sh",
     "release": "scripts/release/release.sh",

scripts/upgradeable/git-user-config.sh

+#!/usr/bin/env bash
+
+set -euo pipefail -x
+
+git config user.name 'github-actions'
+git config user.email '41898282+github-actions[bot]@users.noreply.github.com'

scripts/upgradeable/merge-upstream.sh

+#!/usr/bin/env bash
+
+set -euo pipefail -x
+
+git fetch 'https://github.com/OpenZeppelin/openzeppelin-contracts.git'
+git merge FETCH_HEAD -m 'Merge upstream openzeppelin-contracts into upstream-patched'

scripts/upgradeable/transpile-onto.sh

+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo "usage: bash $0 <target> [base]" >&2
+  exit 1
+fi
+
+set -x
+
+target="$1"
+base="${2-}"
+
+bash scripts/upgradeable/transpile.sh
+
+commit="$(git rev-parse --short HEAD)"
+branch="$(git rev-parse --abbrev-ref HEAD)"
+
+git add contracts
+
+git checkout --quiet --detach
+
+if git rev-parse --quiet --verify "$target"; then
+  git reset --soft "$target"
+  git checkout "$target"
+else
+  git checkout --orphan "$target"
+  if [ -n "$base" ]; then
+    git reset --soft "$base"
+  fi
+fi
+
+if ! git diff --quiet --cached; then
+  git commit -m "Transpile $commit"
+fi
+
+git checkout "$branch"

scripts/upgradeable/transpile.sh

+#!/usr/bin/env bash
+
+set -euo pipefail -x
+
+npm run compile
+
+# -D: delete original and excluded files
+# -i: use included Initializable
+# -x: exclude all proxy contracts
+# -p: emit public initializer
+npx @openzeppelin/upgrade-safe-transpiler -D \
+  -i contracts/proxy/Initializable.sol \
+  -x 'contracts/proxy/**/*' \
+  -p 'contracts/presets/**/*'

test/setup.js

+// a different comment!
 const { deployRelayHub } = require('@openzeppelin/gsn-helpers');
 
 before('deploy GSN RelayHub', async function () {