Add @openzeppelin/contracts as alternative package name (#1840)
* Rename package and repository name from docs and scripts * undo root package rename * add @openzeppelin/contracts as subpackage with release automation * synchronize @openzeppelin/contracts version * remove private field from package.json * make file patterns absolute * change wording of a comment * use a saner version script
This commit is contained in:
Santiago Palladino
committed by
Francisco Giordano
Francisco Giordano
parent
e869b37d0b
commit
b8c8308d77
@ -13,7 +13,7 @@ OpenZeppelin provides xref:api:ownership.adoc#Ownable[`Ownable`] for implementin
|
||||
----
|
||||
pragma solidity ^0.5.0;
|
||||
|
||||
import "openzeppelin-solidity/contracts/ownership/Ownable.sol";
|
||||
import "@openzeppelin/contracts/ownership/Ownable.sol";
|
||||
|
||||
contract MyContract is Ownable {
|
||||
function normalThing() public {
|
||||
@ -58,9 +58,9 @@ Here's a simple example of using `Roles` in an xref:tokens.adoc#ERC20[`ERC20` to
|
||||
----
|
||||
pragma solidity ^0.5.0;
|
||||
|
||||
import "openzeppelin-solidity/contracts/access/Roles.sol";
|
||||
import "openzeppelin-solidity/contracts/token/ERC20/ERC20.sol";
|
||||
import "openzeppelin-solidity/contracts/token/ERC20/ERC20Detailed.sol";
|
||||
import "@openzeppelin/contracts/access/Roles.sol";
|
||||
import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
|
||||
import "@openzeppelin/contracts/token/ERC20/ERC20Detailed.sol";
|
||||
|
||||
contract MyToken is ERC20, ERC20Detailed {
|
||||
using Roles for Roles.Role;
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
= API Stability
|
||||
|
||||
On the https://github.com/OpenZeppelin/openzeppelin-solidity/releases/tag/v2.0.0[OpenZeppelin 2.0 release], we committed ourselves to keeping a stable API. We aim to more precisely define what we understand by _stable_ and _API_ here, so users of the library can understand these guarantees and be confident their project won't break unexpectedly.
|
||||
On the https://github.com/OpenZeppelin/openzeppelin-contracts/releases/tag/v2.0.0[OpenZeppelin 2.0 release], we committed ourselves to keeping a stable API. We aim to more precisely define what we understand by _stable_ and _API_ here, so users of the library can understand these guarantees and be confident their project won't break unexpectedly.
|
||||
|
||||
In a nutshell, the API being stable means _if your project is working today, it will continue to do so_. New contracts and features will be added in minor releases, but only in a backwards compatible way.
|
||||
|
||||
@ -14,7 +14,7 @@ We follow https://semver.org/[SemVer], which means API breakage may occur betwee
|
||||
|
||||
While the internal implementation of functions may change, their semantics and signature will remain the same. The domain of their arguments will not be less restrictive (e.g. if transferring a value of 0 is disallowed, it will remain disallowed), nor will general state restrictions be lifted (e.g. `whenPaused` modifiers).
|
||||
|
||||
If new functions are added to a contract, it will be in a backwards-compatible way: their usage won't be mandatory, and they won't extend functionality in ways that may foreseeable break an application (e.g. https://github.com/OpenZeppelin/openzeppelin-solidity/issues/1512[an `internal` method may be added to make it easier to retrieve information that was already available]).
|
||||
If new functions are added to a contract, it will be in a backwards-compatible way: their usage won't be mandatory, and they won't extend functionality in ways that may foreseeable break an application (e.g. https://github.com/OpenZeppelin/openzeppelin-contracts/issues/1512[an `internal` method may be added to make it easier to retrieve information that was already available]).
|
||||
|
||||
[[internal]]
|
||||
=== `internal`
|
||||
@ -33,7 +33,7 @@ Some of our Solidity libraries use `struct`s to handle internal data that should
|
||||
[[events]]
|
||||
== Events
|
||||
|
||||
No events will be removed, and their arguments won't be changed in any way. New events may be added in later versions, and existing events may be emitted under new, reasonable circumstances (e.g. https://github.com/OpenZeppelin/openzeppelin-solidity/issues/707[from 2.1 on, `ERC20` also emits `Approval` on `transferFrom` calls]).
|
||||
No events will be removed, and their arguments won't be changed in any way. New events may be added in later versions, and existing events may be emitted under new, reasonable circumstances (e.g. https://github.com/OpenZeppelin/openzeppelin-contracts/issues/707[from 2.1 on, `ERC20` also emits `Approval` on `transferFrom` calls]).
|
||||
|
||||
[[gas-costs]]
|
||||
== Gas costs
|
||||
@ -43,7 +43,7 @@ While attempts will generally be made to lower the gas costs of working with Ope
|
||||
[[bugfixes]]
|
||||
== Bugfixes
|
||||
|
||||
The API stability guarantees may need to be broken in order to fix a bug, and we will do so. This decision won't be made lightly however, and all options will be explored to make the change as non-disruptive as possible. When sufficient, contracts or functions which may result in unsafe behaviour will be deprecated instead of removed (e.g. https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1543[#1543] and https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1550[#1550]).
|
||||
The API stability guarantees may need to be broken in order to fix a bug, and we will do so. This decision won't be made lightly however, and all options will be explored to make the change as non-disruptive as possible. When sufficient, contracts or functions which may result in unsafe behaviour will be deprecated instead of removed (e.g. https://github.com/OpenZeppelin/openzeppelin-contracts/pull/1543[#1543] and https://github.com/OpenZeppelin/openzeppelin-contracts/pull/1550[#1550]).
|
||||
|
||||
[[solidity-compiler-version]]
|
||||
== Solidity compiler version
|
||||
@ -52,4 +52,4 @@ Starting on version 0.5.0, the Solidity team switched to a faster release cycle,
|
||||
|
||||
Because of this, *the minimum required Solidity compiler version is not part of the stability guarantees*, and users may be required to upgrade their compiler when using newer versions of OpenZeppelin. Bugfixes will still be backported to older library releases so that all versions currently in use receive these updates.
|
||||
|
||||
You can read more about the rationale behind this, the other options we considered and why we went down this path https://github.com/OpenZeppelin/openzeppelin-solidity/issues/1498#issuecomment-449191611[here].
|
||||
You can read more about the rationale behind this, the other options we considered and why we went down this path https://github.com/OpenZeppelin/openzeppelin-contracts/issues/1498#issuecomment-449191611[here].
|
||||
|
||||
@ -4,7 +4,7 @@ In this guide you will learn how to create an ERC20 token with a custom supply m
|
||||
|
||||
'''''
|
||||
|
||||
The standard interface implemented by tokens built on Ethereum is called ERC20, and OpenZeppelin includes a widely used implementation of it: the aptly named https://github.com/OpenZeppelin/openzeppelin-solidity/blob/v2.1.2/contracts/token/ERC20/ERC20.sol[`ERC20`] contract. This contract, like the standard itself, is quite simple and bare-bones. In fact, if you try deploy an instance of `ERC20` as-is it will be quite literally useless... it will have no supply! What use is a token with no supply?
|
||||
The standard interface implemented by tokens built on Ethereum is called ERC20, and OpenZeppelin includes a widely used implementation of it: the aptly named https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v2.1.2/contracts/token/ERC20/ERC20.sol[`ERC20`] contract. This contract, like the standard itself, is quite simple and bare-bones. In fact, if you try deploy an instance of `ERC20` as-is it will be quite literally useless... it will have no supply! What use is a token with no supply?
|
||||
|
||||
The way that supply is created is not defined in the ERC20 document. Every token is free to experiment with their own mechanisms, ranging from the most decentralized to the most centralized, from the most naive to the most researched, and more.
|
||||
|
||||
@ -57,7 +57,7 @@ As we can see, `_mint` makes it super easy to do this correctly.
|
||||
[[modularizing-the-mechanism]]
|
||||
== Modularizing the mechanism
|
||||
|
||||
There is one supply mechanism already included in OpenZeppelin: https://github.com/OpenZeppelin/openzeppelin-solidity/blob/v2.1.2/contracts/token/ERC20/ERC20Mintable.sol[`ERC20Mintable`]. This is a generic mechanism in which a set of accounts is assigned the `minter` role, granting them the permission to call a `mint` function, an external version of `_mint`.
|
||||
There is one supply mechanism already included in OpenZeppelin: https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v2.1.2/contracts/token/ERC20/ERC20Mintable.sol[`ERC20Mintable`]. This is a generic mechanism in which a set of accounts is assigned the `minter` role, granting them the permission to call a `mint` function, an external version of `_mint`.
|
||||
|
||||
This can be used for centralized minting, where an externally owned account (i.e. someone with a pair of cryptographic keys) decides how much supply to create and to whom. There are very legitimate use cases for this mechanism, such as https://medium.com/reserve-currency/why-another-stablecoin-866f774afede#3aea[traditional asset-backed stablecoins].
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@
|
||||
[[install]]
|
||||
== Install
|
||||
|
||||
OpenZeppelin should be installed directly into your existing node.js project with `npm install openzeppelin-solidity`. We will use https://truffleframework.com/truffle[Truffle], an Ethereum development environment, to get started.
|
||||
OpenZeppelin should be installed directly into your existing node.js project with `npm install @openzeppelin/contracts`. We will use https://truffleframework.com/truffle[Truffle], an Ethereum development environment, to get started.
|
||||
|
||||
Please install Truffle and initialize your project:
|
||||
|
||||
@ -22,7 +22,7 @@ To install the OpenZeppelin library, run the following in your Solidity project
|
||||
|
||||
[source,sh]
|
||||
----
|
||||
$ npm install openzeppelin-solidity
|
||||
$ npm install @openzeppelin/contracts
|
||||
----
|
||||
|
||||
NOTE: OpenZeppelin features a stable API, which means your contracts won't break unexpectedly when upgrading to a newer minor version. You can read ṫhe details in our xref:api-stability.adoc[API Stability] document.
|
||||
@ -36,7 +36,7 @@ Once installed, you can start using the contracts in the library by importing th
|
||||
----
|
||||
pragma solidity ^0.5.0;
|
||||
|
||||
import 'openzeppelin-solidity/contracts/ownership/Ownable.sol';
|
||||
import "@openzeppelin/contracts/ownership/Ownable.sol";
|
||||
|
||||
contract MyContract is Ownable {
|
||||
...
|
||||
|
||||
@ -1,17 +1,17 @@
|
||||
= Release Schedule
|
||||
|
||||
OpenZeppelin follows a xref:api-stability.adoc[semantic versioning scheme].
|
||||
OpenZeppelin Contracts follows a xref:api-stability.adoc[semantic versioning scheme].
|
||||
|
||||
[[minor-releases]]
|
||||
== Minor releases
|
||||
|
||||
OpenZeppelin has a *5 week release cycle*. This means that every five weeks a new release is published.
|
||||
OpenZeppelin Contracts has a *5 week release cycle*. This means that every five weeks a new release is published.
|
||||
|
||||
At the beginning of the release cycle we decide which issues we want to prioritize, and assign them to https://github.com/OpenZeppelin/openzeppelin-solidity/milestones[a milestone on GitHub]. During the next five weeks, they are worked on and fixed.
|
||||
At the beginning of the release cycle we decide which issues we want to prioritize, and assign them to https://github.com/OpenZeppelin/openzeppelin-contracts/milestones[a milestone on GitHub]. During the next five weeks, they are worked on and fixed.
|
||||
|
||||
Once the milestone is complete, we publish a feature-frozen release candidate. The purpose of the release candidate is to have a period where the community can review the new code before the actual release. If important problems are discovered, several more release candidates may be required. After a week of no more changes to the release candidate, the new version is published.
|
||||
|
||||
[[major-releases]]
|
||||
== Major releases
|
||||
|
||||
Every several months a new major release may come out. These are not scheduled, but will be based on the need to release breaking changes such as a redesign of a core feature of the library (e.g. https://github.com/OpenZeppelin/openzeppelin-solidity/issues/1146[roles] in 2.0). Since we value stability, we aim for these to happen infrequently (expect no less than six months between majors). However, we may be forced to release one when there are big changes to the Solidity language.
|
||||
Every several months a new major release may come out. These are not scheduled, but will be based on the need to release breaking changes such as a redesign of a core feature of the library (e.g. https://github.com/OpenZeppelin/openzeppelin-contracts/issues/1146[roles] in 2.0). Since we value stability, we aim for these to happen infrequently (expect no less than six months between majors). However, we may be forced to release one when there are big changes to the Solidity language.
|
||||
|
||||
@ -41,8 +41,8 @@ Here's what our GLD token might look like.
|
||||
----
|
||||
pragma solidity ^0.5.0;
|
||||
|
||||
import "openzeppelin-solidity/contracts/token/ERC20/ERC20.sol";
|
||||
import "openzeppelin-solidity/contracts/token/ERC20/ERC20Detailed.sol";
|
||||
import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
|
||||
import "@openzeppelin/contracts/token/ERC20/ERC20Detailed.sol";
|
||||
|
||||
contract GLDToken is ERC20, ERC20Detailed {
|
||||
constructor(uint256 initialSupply) ERC20Detailed("Gold", "GLD", 18) public {
|
||||
@ -104,8 +104,8 @@ Here's what a contract for tokenized items might look like:
|
||||
----
|
||||
pragma solidity ^0.5.0;
|
||||
|
||||
import "openzeppelin-solidity/contracts/token/ERC721/ERC721Full.sol";
|
||||
import "openzeppelin-solidity/contracts/drafts/Counters.sol";
|
||||
import "@openzeppelin/contracts/token/ERC721/ERC721Full.sol";
|
||||
import "@openzeppelin/contracts/drafts/Counters.sol";
|
||||
|
||||
contract GameItem is ERC721Full {
|
||||
using Counters for Counters.Counter;
|
||||
@ -193,7 +193,7 @@ We will replicate the `GLD` example of the <<constructing-an-erc20-token-contrac
|
||||
----
|
||||
pragma solidity ^0.5.0;
|
||||
|
||||
import "openzeppelin-solidity/contracts/token/ERC777/ERC777.sol";
|
||||
import "@openzeppelin/contracts/token/ERC777/ERC777.sol";
|
||||
|
||||
contract GLDToken is ERC777 {
|
||||
constructor(
|
||||
|
||||
Reference in New Issue
Block a user