From a83b6400b1893d385d52f7b8f31fa59e3ad2ee22 Mon Sep 17 00:00:00 2001 From: arthurgousset <46296830+arthurgousset@users.noreply.github.com> Date: Wed, 24 Jan 2024 15:13:45 +0000 Subject: [PATCH 1/7] docs(CONTRIBUTING): replaces summary and basic instructions --- .github/CONTRIBUTING.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 51d0f2851..1ddd5c1f6 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,13 +1,23 @@ # Contributing -Thank you for considering making a contribution to the Celo community! -Everyone is encouraged to contribute, even the smallest fixes are welcome. +Thank you for your interest in improving Celo SDK(s) and CLI(s). -If you'd like to contribute to Celo, please fork, fix, commit and send a -pull request for the maintainers to review. +If you want to contribute, but aren't sure where to start, you can create a +[new discussion](https://github.com/celo-org/developer-tooling/discussions). -If you wish to submit more complex changes, please sync with a core developer first. -This will help ensure those changes are in line with the general philosophy of the project -and enable you to get some early feedback. +There are multiple opportunities to contribute. It doesn't matter if you are just +getting started or are an expert. We appreciate your interest in contributing. + +> **IMPORTANT** +> Please ask before starting work on any significant new features. +> +> It's never a fun experience to have your pull request declined after investing time and effort +> into a new feature. To avoid this from happening, we invite contributors to create a +> [new discussion](https://github.com/wevm/viem/discussions) to discuss API changes or +> significant new ideas. + +## Basic guide + +This guide is intended to help you get started with contributing. By following these steps, +you will understand the development process and workflow. -See the [contributing guide](https://docs.celo.org/community/contributing) for details on how to participate. From 0879bde8c72e1ba660637b782d5fad3a45334e8d Mon Sep 17 00:00:00 2001 From: arthurgousset <46296830+arthurgousset@users.noreply.github.com> Date: Wed, 24 Jan 2024 16:45:23 +0000 Subject: [PATCH 2/7] docs(CONTRIBUTING): adds detailed instructions and steps --- .github/CONTRIBUTING.md | 113 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 107 insertions(+), 6 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 1ddd5c1f6..6fe41a431 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,7 +2,7 @@ Thank you for your interest in improving Celo SDK(s) and CLI(s). -If you want to contribute, but aren't sure where to start, you can create a +If you want to contribute, but aren't sure where to start, you can create a [new discussion](https://github.com/celo-org/developer-tooling/discussions). There are multiple opportunities to contribute. It doesn't matter if you are just @@ -10,14 +10,115 @@ getting started or are an expert. We appreciate your interest in contributing. > **IMPORTANT** > Please ask before starting work on any significant new features. -> -> It's never a fun experience to have your pull request declined after investing time and effort -> into a new feature. To avoid this from happening, we invite contributors to create a -> [new discussion](https://github.com/wevm/viem/discussions) to discuss API changes or +> +> It's never a fun experience to have your pull request declined after investing time and effort +> into a new feature. To avoid this from happening, we invite contributors to create a +> [new discussion](https://github.com/wevm/viem/discussions) to discuss API changes or > significant new ideas. ## Basic guide -This guide is intended to help you get started with contributing. By following these steps, +This guide is intended to help you get started with contributing. By following these steps, you will understand the development process and workflow. +### Cloning the repository + +To start contributing to the project, clone it to your local machine using git: + +```sh +$ git clone https://github.com/celo-org/developer-tooling.git +``` + +Navigate to the project's root directory: + +```sh +$ cd developer-tooling +``` + +### Installing Node.js + +We use [Node.js](https://nodejs.org/en/) to run the project locally. +You need to install the **Node.js version** specified in [.nvmrc](../.nvmrc). To do so, run: + +```sh +$ nvm install +$ nvm use +``` + +### Installing dependencies + +Once in the project's root directory, run the following command to install the project's +dependencies: + +```sh +$ yarn install +``` + +After installing the dependencies, the project is ready to be run. + +### Navigating the repository + +The project is structured into multiple packages. Each package is located in the +[`packages/`](../packages/) directory. Each package has its own `package.json` file and is +published independently. + +For example: + +- the [`@celo/celocli`](https://www.npmjs.com/package/@celo/celocli) NPM package is + located in the [`packages/cli/`](../packages/cli/) directory. +- the [`@celo/contractkit`](https://www.npmjs.com/package/@celo/contractkit) NPM package is + located in the [`packages/sdk/contractkit/`](../packages/sdk/contractkit/) directory. + +### Running packages + +Once you navigated to the package directory you want to run, inspect the `package.json` file +and look for the `scripts` section. It contains the list of available scripts that can be run. + +### Versioning + +When adding new features or fixing bugs, we'll need to bump the package versions. +We use [Changesets](https://github.com/changesets/changesets) to do this. + +> **INFO** +> Only changes to the codebase that affect the public API or existing behavior (e.g. bugs) +> need changesets. + +Each changeset defines which package(s) should be published and whether the change should be a +major/minor/patch release, as well as providing release notes that will be added to the changelog +upon release. + +To create a new changeset, run: + +```sh +$ yarn run changeset +``` + +This will run the Changesets CLI, prompting you for details about the change. +You’ll be able to edit the file after it’s created — don’t worry about getting everything perfect +up front. + +Even though you can technically use any markdown formatting you like, headings should be avoided +since each changeset will ultimately be nested within a bullet list. Instead, bold text should be +used as section headings. + +If your PR is making changes to an area that already has a changeset (e.g. there’s an existing +changeset covering theme API changes but you’re making further changes to the same API), you +should update the existing changeset in your PR rather than creating a new one. + +### Running the test suite + +Unfortunately, we don't have a consistent way of running the test suite across all packages yet. +Some packages have their own test suites, while others don't have any tests at all. +This is something we are working on improving. + +When you open a Pull Request, the GitHub CI will run the available test suites for you, but +you can also run them locally. + +> **INFO** +> Some tests are run automatically when you open a Pull Request, while others are run when a +> maintainer approves the Pull Request. This is for security reasons, as some tests require access +> to secrets. + +### Open a Pull Request + +✅ Now you're ready to contribute to Celo SDK(s) and CLI(s)! From de7f27afcec4622208ed9e2df6119a5009ab7ae9 Mon Sep 17 00:00:00 2001 From: arthurgousset <46296830+arthurgousset@users.noreply.github.com> Date: Wed, 24 Jan 2024 16:47:45 +0000 Subject: [PATCH 3/7] docs(README-DEV): deletes `README-DEV.md` file Doesn't seem relevant for our current workflows anymore. --- README-dev.md | 87 --------------------------------------------------- 1 file changed, 87 deletions(-) delete mode 100644 README-dev.md diff --git a/README-dev.md b/README-dev.md deleted file mode 100644 index ee046e372..000000000 --- a/README-dev.md +++ /dev/null @@ -1,87 +0,0 @@ -# README GUIDE FOR CELO DEVELOPERS - - -### 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 `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 -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/ -``` - -### Publish the package - -``` -# Publish the package publicly -developer-tooling/packages/cli $ yarn publish --access=public -``` - -Let's say the published package version number 0.0.20, verify that it is installable - -``` -/tmp/tmp1 $ npm install @celo/cli@0.0.20 -``` - -Add a tag with the most recent git commit of the published branch. Note that this commit comes before package.json is updated with the new package version. - -``` -$ npm dist-tag add @ -``` - -Additionally, if this version is intended to be used on a deployed network (e.g. `baklava` or `alfajores`), tag the version with all appropriate network names. - -``` -$ npm dist-tag add @ -``` - -Once you publish do some manual tests, for example, after publishing `celocli` - -``` -# Docker for an isolated environment again -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/celocli@0.0.48 -... -circleci@7040a7660754:/tmp/tmp1$ ./node_modules/.bin/celocli -CLI Tool for transacting with the Celo protocol - -VERSION - @celo/celocli/1.6.3 linux-x64 node-v18.14.2 - -USAGE - $ celocli [COMMAND] - -COMMANDS - account Manage your account, keys, and metadata - config Configure CLI options which persist across commands - election Participate in and view the state of Validator Elections - exchange Exchange Celo Dollars and Celo Gold via the stability mechanism - governance Interact with on-chain governance proposals and hotfixes - help display help for celocli - identity Outputs the set of validators currently participating in BFT and which ones are participating in Celo's lightweight identity protocol - lockedgold View and manage locked Celo Gold - multisig Shows information about multi-sig contract - network Prints Celo contract addesses. - node Manage your Celo node - oracle Remove expired oracle reports for a specified token (currently just Celo Dollar, aka: "StableToken") - releasegold View and manage Release Gold contracts - reserve Shows information about reserve - rewards Show rewards information about a voter, registered Validator, or Validator Group - transfer Transfer Celo Gold and Celo Dollars - validator View and manage Validators - validatorgroup View and manage Validator Groups - -circleci@7040a7660754:/tmp/tmp1$ ./node_modules/.bin/celocli account:new -Failed to initialize libusb. -This is not being stored anywhere. Save the mnemonic somewhere to use this account at a later point. - -mnemonic: fury puzzle field laptop evidence stuff rescue display home museum ritual message million cave stadium carbon clinic dutch robust vehicle control lizard brass dinosaur -accountAddress: 0x328e0394Dbb468FE4eD1fF73bD508442fBD305CF -privateKey: 7adb0c1a98b00b98a180cbfcc44666f1aab7d315669190fbac30bbdc4989a2ec -publicKey: 039f938bb038962080c9269b195b63999cf90b149921250c2b8a8db92f711d5c81 -``` From d1c920d1d14c331569bc8ed800bded044a17194b Mon Sep 17 00:00:00 2001 From: arthurgousset <46296830+arthurgousset@users.noreply.github.com> Date: Wed, 31 Jan 2024 18:27:31 +0000 Subject: [PATCH 4/7] nit(RELEASE): fix typos --- RELEASE.md | 115 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 72 insertions(+), 43 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index c29a4f974..4cad9b13c 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,76 +1,105 @@ # Release Process -This repo uses changesets to determine what packages need a version bump. +This repo uses [changesets](https://github.com/changesets/changesets) to determine what +packages need a version bump. -Each PR MUST be accompanied by a changeset unless it has zero affect on package consumers (ie changing github action workflows). +Each PR MUST be accompanied by a changeset unless it has zero impact on package consumers (i.e. +changing GitHub Action workflows). -To create a changeset run `changeset add` (or `yarn cs`) +To create a changeset run: -This will bring up an interactive console which asks which packages are affect and if they require minor or major update. +```sh +$ changeset add +# or +$ yarn cs +``` -## Auto Releasing +This will bring up an interactive console that asks which packages are affected and if they +require a patch, minor, or major update. -The Release.yaml workflow will create a PR called "Version Packages", each time a PR is merged to master with changeset files this PR will be rebased and updated to show what the versions would be of published then. Merging this PR in will lead to packages being built and published to npm and github release notes being published. +## Package Versioning -## Manual Releasing (discouraged) +Based on [semantic versioning best practices](semver.org),g iven a version number +`MAJOR.MINOR.PATCH`, increment the: -when time to release new versions of npm package run `changeset version` this will look thru the changeset files that have been generated since last release to bump the versions for package automatically to major if any changesets specify major change minor if only minor and patch if a the package had no changesets of its own but depends on one which will be updated. +- `MAJOR` version when you make incompatible API changes +- `MINOR` version when you add functionality in a backward compatible manner +- `PATCH` version when you make backward compatible bug fixes -finally `changeset publish` will go thru and publish to npm the packages that need publishing. +Additional labels for pre-release and build metadata are available as extensions to the +`MAJOR.MINOR.PATCH` format. -after go ahead and run `git push --follow-tags` to push git tags up to github. +## Production releases -## Auto Pre-releasing (Recommended) +### Automatic (recommended) -For Detailed Steps read (scripts/beta-mode.sh)[] +The [`release.yaml`](./.github/workflows/release.yaml) workflow will create a PR called +"Version Packages", each time a PR is merged to master with changeset files this PR will be rebased and updated to show what the published versions would be. Merging this PR will build and publish packages to NPM, +and publish GitHub release notes. -1. Run `yarn beta-enter` -This will enter into the pre mode of changesets and create a prerelease/beta branch and push it up to origin(github) +### Manual (discouraged) -Any time a commit is pushed to prerelease/** github will go and open a specially Version Packages (Beta) PR. You can merge this and packages will be published as specified in the branch (should be beta) +When it's time to release NPM packages run: -2. If you need to release another beta make a changeset and commit it up. +```sh +$ changeset version +``` -3. When done run `yarn beta-exit` -This will exit changeset pre mode. Push up. +This will look through the changeset files that have been generated since the last release and +bump package versions automatically. -4. Now you can Open a Pr with your prerelease/? branch against main. +To publish the relevant NPM packages run: +```sh +$ changeset publish +``` -## Manual Pre Releasing (discouraged) +Afterwards, push git tags to GitHub: -changesets has 2 strategies for pre release versions. +```sh +$ git push --follow-tags +``` -The first is to enter `pre` mode on changesets. [docs here](https://github.com/changesets/changesets/blob/main/docs/prereleases.md) +## Pre-releases -``` -yarn changeset pre enter beta -yarn changeset version -git add . -git commit -m "Enter prerelease mode and version packages" -yarn changeset publish -git push --follow-tags -``` +### Automatic (recommended) -The other is to append --snapshot. which is great for daily releases. +> [!TIP] +> For detailed steps read [`beta-mode.sh`](./scripts/beta-mode.sh). -``` -yarn changeset version --snapshot canary +1. Run `yarn beta-enter` -yarn changeset publish --no-git-tag --snapshot + This will enter the "pre mode" of changesets, create a `prerelease/beta` branch, and push + it to `origin` (GitHub). -``` + Anytime a commit is pushed to `prerelease/..` GitHub will open a "Version Packages (Beta)" PR. + You can merge this PR and packages will be published as specified in the branch (should be beta). - +2. If you need to release another beta make a changeset and commit it up. -## Package Versioning +3. When done run `yarn beta-exit` + This will exit changeset pre mode. Push up. -Based on semantic versioning best practices [semver.org](semver.org) +4. Now you can open a PR with your `prerelease/..` branch against `main`. -Given a version number MAJOR.MINOR.PATCH, increment the: +### Manual (discouraged) -- MAJOR version when you make incompatible API changes -- MINOR version when you add functionality in a backward compatible manner -- PATCH version when you make backward compatible bug fixes +Changesets has two strategies for pre release versions. -Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. +The first is to [enter `pre` mode on changesets](https://github.com/changesets/changesets/blob/main/docs/prereleases.md). + +```sh +$ yarn changeset pre enter beta +$ yarn changeset version +$ git add . +$ git commit -m "Enter prerelease mode and version packages" +$ yarn changeset publish +$ git push --follow-tags +``` + +The other is to [append `--snapshot`](https://github.com/changesets/changesets/blob/main/docs/snapshot-releases.md), which is great for daily releases. + +```sh +$ yarn changeset version --snapshot canary +$ yarn changeset publish --no-git-tag --snapshot +``` From ca928d9d89996ede9db4f2d50c37067296d7330d Mon Sep 17 00:00:00 2001 From: arthurgousset <46296830+arthurgousset@users.noreply.github.com> Date: Wed, 31 Jan 2024 18:29:37 +0000 Subject: [PATCH 5/7] nit(CONTRIBUTING): moves file to top-level So it's easier for first-time contributors to find it when visiting the GitHub repo on the browser. --- .github/CONTRIBUTING.md => CONTRIBUTING.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/CONTRIBUTING.md => CONTRIBUTING.md (100%) diff --git a/.github/CONTRIBUTING.md b/CONTRIBUTING.md similarity index 100% rename from .github/CONTRIBUTING.md rename to CONTRIBUTING.md From 90d40b501dd2d771c2d3ab5187767c135b5ff757 Mon Sep 17 00:00:00 2001 From: arthurgousset <46296830+arthurgousset@users.noreply.github.com> Date: Wed, 31 Jan 2024 18:32:22 +0000 Subject: [PATCH 6/7] docs(SETUP): deletes file This file was brought from the monorepo and does not seem entirely relevant for @celo-org/developer-tooling. Instead the `CONTRIBUTING.md` file should be expanded if necessary. At this moment, I don't think this is necessary. --- SETUP.md | 103 ------------------------------------------------------- 1 file changed, 103 deletions(-) delete mode 100644 SETUP.md diff --git a/SETUP.md b/SETUP.md deleted file mode 100644 index 1b926b42d..000000000 --- a/SETUP.md +++ /dev/null @@ -1,103 +0,0 @@ -# Celo Engineering Setup - -- [Celo Engineering Setup](#celo-engineering-setup) - - [Reading](#reading) - - [Getting everything installed](#getting-everything-installed) - - [Common stuff](#common-stuff) - - [Install Node](#install-node) - - [MacOS](#macos) - - [Xcode CLI](#xcode-cli) - - [Install Yarn](#install-yarn) - - [Linux](#linux) - - [Install Yarn](#install-yarn-1) - - [Building developer-tooling](#building-developer-tooling) - -This is a living document! Please edit and update it as part of your onboarding process :-) - -## Reading - -Review the README from each directory in [packages](packages/). - -## Getting everything installed - -Follow these steps to get everything that you need installed to build the developer-tooling codebase on your computer. - -### Common stuff - -#### Install Node - -Currently Node.js v18.14.2 is required in order to work with this repo. - -Install `nvm` (allows you to manage multiple versions of Node) by following the [instructions here](https://github.com/nvm-sh/nvm). - -Once `nvm` is successfully installed, restart the terminal and run the following commands to install the `npm` versions that [developer-tooling](https://github.com/celo-org/developer-tooling) will need: - -```bash -# restart the terminal after installing nvm -nvm install 18.14.2 -nvm alias default 18.14.2 -``` - -### MacOS - -#### Xcode CLI - -Install the Xcode command line tools: - -```bash -xcode-select --install -``` - -#### Install Yarn - -We use Yarn to build all of the [developer-tooling] repo. Install it using [Homebrew](#homebrew): - -```bash -brew install yarn -``` - -### Linux - -#### Install Yarn - -We use Yarn to build all of the [developer-tooling](https://github.com/celo-org/developer-tooling) repo. Install it by running the following: - -```bash -# for documentation on yarn visit https://yarnpkg.com/en/docs/install#debian-stable -curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update && sudo apt-get install yarn -``` - - -## Building - -Clone the [developer-tooling](https://github.com/celo-org/developer-tooling) repo: - -```bash -mkdir ~/celo -cd celo -git clone https://github.com/celo-org/developer-tooling.git -``` - -Then install the packages: - -```bash -cd developer-tooling -# install dependencies and run post-install script -yarn -# build all packages -yarn build --ignore docs -``` - -> Note that if you do your checkouts with a different method, Yarn will fail if -> you haven’t used git with ssh at least once previously to confirm the -> github.com host key. Clone a repo or add the github host key to -> `~/.ssh/known_hosts` and then try again. - -> When removing a dependency via `yarn remove some-package`, be sure to also run `yarn postinstall` so -> you aren't left with freshly unpackaged modules. This is because we use `patch-package` -> and the `postinstall` step which uses it is not automatically run after using `yarn remove`. - -> The docs package relies on gitbook which has problems off of a fresh install. Running -> `yarn build --ignore docs` is a known workaround. \ No newline at end of file From c174d9a1e2f7b72ed56410c0cae8c14524eea5f9 Mon Sep 17 00:00:00 2001 From: arthurgousset <46296830+arthurgousset@users.noreply.github.com> Date: Thu, 1 Feb 2024 12:41:57 +0000 Subject: [PATCH 7/7] docs(README): adds links and context for first-time visitors Took inspiration from viem's README: https://github.com/wevm/viem/blob/main/src/README.md --- README.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1e3d56b8b..e37e827ee 100644 --- a/README.md +++ b/README.md @@ -28,4 +28,29 @@ This includes: - [`@celo/wallet-ledger`](https://www.npmjs.com/package/@celo/wallet-ledger) - [`@celo/wallet-local`](https://www.npmjs.com/package/@celo/wallet-local) - [`@celo/wallet-remote`](https://www.npmjs.com/package/@celo/wallet-remote) - - [`@celo/wallet-rpc`](https://www.npmjs.com/package/@celo/wallet-rpc) \ No newline at end of file + - [`@celo/wallet-rpc`](https://www.npmjs.com/package/@celo/wallet-rpc) + +## Contributing + +If you're interested in contributing, please read the [contributing docs](./CONTRIBUTING.md) +**before submitting a pull request**. + +## Documentation + +[Head to the documentation](https://docs.celo.org/) to read and learn more about Celo SDK(s) and +CLI(s). + +## Community + +Check out the following places for more developer tooling-related content: + +- Join the [discussions on GitHub](https://github.com/celo-org/developer-tooling/discussions) +- Follow [@cLabs](https://twitter.com/cLabs) and [@celo](https://twitter.com/Celo) on X + (formerly Twitter) for project updates + +## Authors + +- [@aaronmgdr](https://github.com/aaronmgdr) +- [@nicolasbrugneaux](https://github.com/nicolasbrugneaux) +- [@shazarre](https://github.com/shazarre) +- [@arthurgousset](https://github.com/arthurgousset) \ No newline at end of file