From 1810da31d154429dde7efe23d39cd382cd755d04 Mon Sep 17 00:00:00 2001 From: Loris Leiva Date: Wed, 6 Sep 2023 16:55:11 +0100 Subject: [PATCH] Add and update READMEs --- CONTRIBUTING.md | 35 +++++++++++++++++++ README.md | 19 +++++++++- clients/js/CONTRIBUTING.md | 59 ++++++++++++++++++++++++++++++++ clients/js/README.md | 23 +++++++++++-- programs/system-extras/README.md | 19 ++++++++++ programs/token-extras/README.md | 19 ++++++++++ 6 files changed, 171 insertions(+), 3 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 clients/js/CONTRIBUTING.md create mode 100644 programs/system-extras/README.md create mode 100644 programs/token-extras/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..8bf00139 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,35 @@ +# Contributing to Mpl Toolbox + +This is a quick guide to help you contribute to Mpl Toolbox. + +## Getting started + +The root folder has a private `package.json` containing a few scripts and JavaScript dependencies that help generate IDLs; clients and start a local validator. First, [ensure you have pnpm installed](https://pnpm.io/installation) and run the following command to install the dependencies. + +```sh +pnpm install +``` + +You will then have access to the following commands. + +- `programs:build` - Build all programs and fetch all dependant programs. +- `programs:test` - Test all programs. +- `programs:clean` - Clean all built and fetched programs. +- `pnpm generate:idls` - Generate IDLs for all programs, as configured in the `configs/shank.cjs` file. +- `pnpm generate:clients` - Generate clients using Kinobi, as configured in the `configs/kinobi.cjs` file. +- `pnpm generate` - Shortcut for `pnpm generate:idls && pnpm generate:clients`. +- `pnpm validator` - Start a local validator using Amman, as configured in the `configs/validator.cjs` file. +- `pnpm validator:stop` - Stop the local validator. +- `pnpm validator:logs` - Show the logs of the local validator. + +## Managing clients + +Each client has its own README with instructions on how to get started. You can find them in the `clients` folder. + +- [JavaScript client](./clients/js/README.md) + +## Setting up CI/CD using GitHub actions + +Most of the CI/CD should already be set up for you and the `.github/.env` file can be used to tweak the variables of the workflows. + +However, the "Deploy JS Client" workflow — configured in `.github/workflows/deploy-js.yml` — requires a few more steps to work. See the [CONTRIBUTING.md file of the JavaScript client](./clients/js/CONTRIBUTING.md#setting-up-github-actions) for more information. diff --git a/README.md b/README.md index 601588ff..5a8fe11f 100644 --- a/README.md +++ b/README.md @@ -2,4 +2,21 @@ Essential programs and clients to build on top of. -_Documentation coming soon..._ +## Programs + +This project contains the following programs: + +- [MPL System Extras](./programs/system-extras/README.md) `SysExL2WDyJi9aRZrXorrjHJut3JwHQ7R9bTyctbNNG` +- [MPL Token Extras](./programs/token-extras/README.md) `TokExjvjJmhKaRBShsBAsbSvEWMA1AgUNK7ps4SAc2p` + +You will need a Rust version compatible with BPF to compile the program, currently we recommend using Rust 1.68.0. + +## Clients + +This project contains the following clients: + +- [JavaScript](./clients/js/README.md) + +## Contributing + +Check out the [Contributing Guide](./CONTRIBUTING.md) the learn more about how to contribute to this project. diff --git a/clients/js/CONTRIBUTING.md b/clients/js/CONTRIBUTING.md new file mode 100644 index 00000000..98c011c3 --- /dev/null +++ b/clients/js/CONTRIBUTING.md @@ -0,0 +1,59 @@ +# Contributing to the JavaScript client + +This is a quick guide to help you contribute to the JavaScript client of Mpl Toolbox. + +## Getting started + +[Ensure you have pnpm installed](https://pnpm.io/installation) and run the following command to install the client's dependencies. + +```sh +pnpm install +``` + +You can then run the following commands to build, test and lint the client. + +```sh +# Build the client. +pnpm build + +# Test the client (requires building first). +pnpm build && pnpm test + +# Test a specific file or set of files. +pnpm build && pnpm test test/somefile.test.js +pnpm build && pnpm test test/somePattern* + +# Lint and/or format the client. +pnpm lint:fix +pnpm format:fix +``` + +When something changes in the program(s), make sure to run `pnpm generate` in the root directory, to re-generate the clients accordingly. + +## Deploying the JavaScript client + +You can deploy a new version of the JavaScript client by manually dispatching the "Deploy JS Client" workflow in the GitHub Actions tab of the repository. + +![Click on the "Actions" tab, then on the "Deploy JS Client" workflow, then on the "Run workflow" dropdown. Select your options before clicking on the final "Run workflow" button inside the dropdown body.](https://user-images.githubusercontent.com/3642397/235444901-6ee95f30-ed84-4eef-b1c4-8b8474ab82a4.png) + +For this to work, some initial setup is required on the repository as explained below. + +## Setting up GitHub actions + +To deploy JavaScript clients using GitHub actions, we first need the following secret variables to be set up on the repository. + +- `NPM_TOKEN` — An access token that can publish your packages to NPM. +- `VERCEL_TOKEN` — An access token that can deploy to Vercel. +- `VERCEL_ORG_ID` — The ID of the Vercel organization you want to deploy to. + +Then, we'll need to create a new GitHub environment called `js-client-documentation` for the generated documentation of the JavaScript client. We can then select the `main` branch only and add the following secret variable to this specific environment. + +- `VERCEL_PROJECT_ID` — The ID of the Vercel project you want to deploy to. + The convention for Metaplex is to create a new Vercel project named `mpl-toolbox-js-docs` with the following deployment settings: + + - Build Command: `pnpm run build:docs` + - Output Directory: `docs` + - Install Command: `pnpm install` + - Development Command: _None_ + +With all that set up, you can now run the "Deploy JS Client" workflow by dispatching it from the GitHub UI. \ No newline at end of file diff --git a/clients/js/README.md b/clients/js/README.md index cfb1acee..cde8ecc5 100644 --- a/clients/js/README.md +++ b/clients/js/README.md @@ -1,3 +1,22 @@ -# mpl-toolbox +# JavaScript client for Mpl Toolbox -TODO +A Umi-compatible JavaScript library for the project. + +## Getting started + +1. First, if you're not already using Umi, [follow these instructions to install the Umi framework](https://github.com/metaplex-foundation/umi/blob/main/docs/installation.md). +2. Next, install this library using the package manager of your choice. + ```sh + npm install @metaplex-foundation/mpl-toolbox + ``` +2. Finally, register the library with your Umi instance like so. + ```ts + import { mplToolbox } from '@metaplex-foundation/mpl-toolbox'; + umi.use(mplToolbox()); + ``` + +You can learn more about this library's API by reading its generated [TypeDoc documentation](https://mpl-toolbox-js-docs.vercel.app). + +## Contributing + +Check out the [Contributing Guide](./CONTRIBUTING.md) the learn more about how to contribute to this library. diff --git a/programs/system-extras/README.md b/programs/system-extras/README.md new file mode 100644 index 00000000..f9facc34 --- /dev/null +++ b/programs/system-extras/README.md @@ -0,0 +1,19 @@ +# Mpl System Extras + +Extra instructions built on top of the native System program. + +## Building + +This will build the program and output a `.so` file in a non-comitted `target/deploy` directory which is used by the `config/shank.cjs` configuration file to start a new local validator with the latest changes on the program. + +```sh +cargo build-bpf +``` + +## Testing + +You may run the following command to build the program and run its Rust tests. + +```sh +cargo test-bpf +``` diff --git a/programs/token-extras/README.md b/programs/token-extras/README.md new file mode 100644 index 00000000..2a991712 --- /dev/null +++ b/programs/token-extras/README.md @@ -0,0 +1,19 @@ +# Mpl Token Extras + +Extra instructions built on top of the native Token program. + +## Building + +This will build the program and output a `.so` file in a non-comitted `target/deploy` directory which is used by the `config/shank.cjs` configuration file to start a new local validator with the latest changes on the program. + +```sh +cargo build-bpf +``` + +## Testing + +You may run the following command to build the program and run its Rust tests. + +```sh +cargo test-bpf +```