-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* remove old guide to releasing packages that has been superceeded by releasing.md (cherry picked from commit 7f3bf5b) * remove old info from readme and setup docs (cherry picked from commit 57c6518) * where appropriate replace celo-monorepo with developer-tooling (cherry picked from commit db9699e) * regenerate docs from new repo --------- Co-authored-by: Aaron <[email protected]>
- Loading branch information
Showing
45 changed files
with
202 additions
and
322 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,69 +1,15 @@ | ||
| # README GUIDE FOR CELO DEVELOPERS | ||
|
|
||
| ## How to run a local testnet | ||
|
|
||
| Often when developing, it is useful to create a test network localy using the full celo-blockchain binary to go beyond what can be done with other options such as [Ganache](https://www.trufflesuite.com/ganache) | ||
|
|
||
| The quickest way to get started with a local testnet is by running `yarn celotool local-testnet` from the `monorepo` root. | ||
|
|
||
| This command will create a local testnet with a single validator node and deploy all smart contract migrations to it. | ||
| Once the network is initialized a NodeJS REPL is provided to help interact with the running nodes. | ||
| For more options, consult `yarn celotool local-testnet --help`, which provides an overview of the tool and its options. | ||
|
|
||
| ## Monorepo inter-package dependencies | ||
|
|
||
| Many packages depend on other packages within the monorepo. When this happens, follow these rules: | ||
|
|
||
| 1. All packages must use **master version** of sibling packages. | ||
| 2. Exception to (1) are packages that represent a GAE/firebase app which must use the last published version. | ||
| 3. To differentiate published vs unpublished version. Master version (in package.json) must end with suffix `-dev` and should not be published. | ||
| 4. If a developer wants to publish a version; then after publishing it needs to set master version to next `-dev` version and change all package.json that require on it. | ||
|
|
||
| To check which packages need amending, you can run (in the root pkg): | ||
|
|
||
| yarn check:packages | ||
|
|
||
| A practical example: | ||
|
|
||
| - In any given moment, `contractkit/package.json#version` field **must** of the form `x.y.z-dev` | ||
| - If current version of contractkit is: `0.1.6-dev` and we want to publish a new version, we should: | ||
| - publish version `0.1.6` | ||
| - change `package.json#version` to `0.1.7-dev` | ||
| - change in other packages within monorepo that were using `0.1.6-dev` to `0.1.7-dev` | ||
|
|
||
| ## How to publish a new npm package | ||
|
|
||
| > Note: Packages with mainline versions (i.e. without a `-foo` suffix) should be published from the `master` branch. | ||
| > Note: All packages are prefixed with "@celo/" and only members of the [Celo NPM organization](https://www.npmjs.com/settings/celo/members) can publish new packages or update the existing ones. | ||
| ### Update the version numbers to an unpublished version | ||
|
|
||
| It is important to ensure that the `master` branch is ahead of the published package on NPM, otherwise `yarn` may use the published version of the package rather than the local development version. | ||
|
|
||
| In order to maintain this, create and merge a PR to the `master` branch bumping the package version to the next number that will be published. (i.e. If you are about to publish `x.y.z`, set the package version to `x.y.z+1`) | ||
| Update all references to that package in the monorepo to the new version (i.e. `x.y.z+1`) | ||
| Prefer appending a `-dev` suffix to the version number to ensure an internal dependency will never be mistaken for a published one. | ||
|
|
||
| > Note: Publishing breaking changes requires an increment to the minor version number for `0.` releases. Once `1.0.0` is pusblished breaking changes are generally prohibited outside the rare major version release. Read the [semver specification](https://semver.org/) for more information. | ||
| > Note: Services deployed to App Engine must only depend on published NPM packages. These packages are `blockchain-api` and `notification-service`. | ||
| ### Checkout the commit to be published and verify version numbers | ||
|
|
||
| Checkout the commit that will become the new published version (i.e. `git checkout HEAD~1` assuming that the commit for bumping the version number is `HEAD`) | ||
|
|
||
| Check the `package.json` file and remove the `-dev` suffix if present. Additionally remove the `-dev` suffix from any internal dependencies and use ensure they are published (e.g. `@celo/utils`) | ||
|
|
||
| ### Verify installation in Docker | ||
|
|
||
| Test installation in isolation using Docker. | ||
| This confirms that it is locally installable and does not have implicit dependency on rest of the `celo-monorepo` or have an implicit dependency which is an explicit dependency of another `celo-monorepo` package. | ||
| This confirms that it is locally installable and does not have implicit dependency on rest of the `developer-tooling` or have an implicit dependency which is an explicit dependency of another `developer-tooling` package. | ||
|
|
||
| ``` | ||
| # Specify the package to test. e.g. celocli, contractkit, utils | ||
| celo-monorepo $ PACKAGE=cli | ||
| celo-monorepo $ docker run --rm -v $PWD/packages/${PACKAGE}:/tmp/npm_package -it --entrypoint bash gcr.io/celo-testnet/circleci-node18:1.0.0 | ||
| developer-tooling $ PACKAGE=cli | ||
| developer-tooling $ docker run --rm -v $PWD/packages/${PACKAGE}:/tmp/npm_package -it --entrypoint bash gcr.io/celo-testnet/circleci-node18:1.0.0 | ||
| circleci@e0d56700584f:/# mkdir /tmp/tmp1 && cd /tmp/tmp1 | ||
| circleci@e0d56700584f:/tmp/tmp1# npm install /tmp/npm_package/ | ||
| ``` | ||
|
|
@@ -72,7 +18,7 @@ circleci@e0d56700584f:/tmp/tmp1# npm install /tmp/npm_package/ | |
|
|
||
| ``` | ||
| # Publish the package publicly | ||
| celo-monorepo/packages/cli $ yarn publish --access=public | ||
| developer-tooling/packages/cli $ yarn publish --access=public | ||
| ``` | ||
|
|
||
| Let's say the published package version number 0.0.20, verify that it is installable | ||
|
|
@@ -97,7 +43,7 @@ Once you publish do some manual tests, for example, after publishing `celocli` | |
|
|
||
| ``` | ||
| # Docker for an isolated environment again | ||
| celo-monorepo $ docker run --rm -it --entrypoint bash gcr.io/celo-testnet/circleci-node18:1.0.0 | ||
| developer-tooling $ docker run --rm -it --entrypoint bash gcr.io/celo-testnet/circleci-node18:1.0.0 | ||
| circleci@7040a7660754:/$ mkdir /tmp/tmp1 && cd /tmp/tmp1 | ||
| circleci@7040a7660754:/tmp/tmp1$ npm install @celo/[email protected] | ||
| ... | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.