From 2601a50638e7144f784e6c3d91160f1332fcb8f4 Mon Sep 17 00:00:00 2001 From: Spencer Corwin Date: Wed, 22 Jul 2020 17:37:29 -0700 Subject: [PATCH] feat(docs): add docs on contributing --- .../release_2020-07-23-21-27.json | 11 ++ .../cli-common/release_2020-07-23-21-27.json | 11 ++ .../cli/release_2020-07-23-21-27.json | 11 ++ .../src/configuration.ts | 30 +++-- .../neo-one-cli-common/src/configuration.ts | 6 +- packages/neo-one-cli/src/cmd/compile.ts | 34 +++--- packages/neo-one-cli/src/cmd/console.ts | 4 +- .../neo-one-cli/src/cmd/stop/neotracker.ts | 2 +- .../2020-07-23-neo-one-2-7-announcement.md | 67 ++++++++++++ .../docs/0-installation/2-cli.md | 103 ++++++++++++++++++ .../{2-playground.md => 3-playground.md} | 0 .../4-contributing/0-how-to-contribute.md | 19 ++++ .../2-smart-contract-compiler.md | 58 +++++++++- 13 files changed, 329 insertions(+), 27 deletions(-) create mode 100644 common/changes/@neo-one/cli-common-node/release_2020-07-23-21-27.json create mode 100644 common/changes/@neo-one/cli-common/release_2020-07-23-21-27.json create mode 100644 common/changes/@neo-one/cli/release_2020-07-23-21-27.json create mode 100644 packages/neo-one-website/blog/2020-07-23-neo-one-2-7-announcement.md create mode 100644 packages/neo-one-website/docs/0-installation/2-cli.md rename packages/neo-one-website/docs/0-installation/{2-playground.md => 3-playground.md} (100%) diff --git a/common/changes/@neo-one/cli-common-node/release_2020-07-23-21-27.json b/common/changes/@neo-one/cli-common-node/release_2020-07-23-21-27.json new file mode 100644 index 0000000000..19a6b98e32 --- /dev/null +++ b/common/changes/@neo-one/cli-common-node/release_2020-07-23-21-27.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "@neo-one/cli-common-node", + "comment": "Update CLI compile options.", + "type": "patch" + } + ], + "packageName": "@neo-one/cli-common-node", + "email": "spencercorwin@icloud.com" +} \ No newline at end of file diff --git a/common/changes/@neo-one/cli-common/release_2020-07-23-21-27.json b/common/changes/@neo-one/cli-common/release_2020-07-23-21-27.json new file mode 100644 index 0000000000..e911433ed1 --- /dev/null +++ b/common/changes/@neo-one/cli-common/release_2020-07-23-21-27.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "@neo-one/cli-common", + "comment": "Update CLI compile options.", + "type": "patch" + } + ], + "packageName": "@neo-one/cli-common", + "email": "spencercorwin@icloud.com" +} \ No newline at end of file diff --git a/common/changes/@neo-one/cli/release_2020-07-23-21-27.json b/common/changes/@neo-one/cli/release_2020-07-23-21-27.json new file mode 100644 index 0000000000..7a1bd89368 --- /dev/null +++ b/common/changes/@neo-one/cli/release_2020-07-23-21-27.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "@neo-one/cli", + "comment": "Update CLI compile options.", + "type": "patch" + } + ], + "packageName": "@neo-one/cli", + "email": "spencercorwin@icloud.com" +} \ No newline at end of file diff --git a/packages/neo-one-cli-common-node/src/configuration.ts b/packages/neo-one-cli-common-node/src/configuration.ts index a58b3116d5..94b394a2e1 100644 --- a/packages/neo-one-cli-common-node/src/configuration.ts +++ b/packages/neo-one-cli-common-node/src/configuration.ts @@ -17,8 +17,12 @@ const configurationDefaults = { path: nodePath.join('neo-one', 'migration.js'), }, contracts: { - path: nodePath.join('neo-one', 'contracts'), outDir: nodePath.join('neo-one', 'compiled'), + path: nodePath.join('neo-one', 'contracts'), + json: true, + avm: false, + debug: false, + opcodes: false, }, codegen: { path: nodePath.join('src', 'neo-one'), @@ -91,11 +95,15 @@ const configurationSchema = { }, contracts: { type: 'object', - allRequired: true, + allRequired: false, additionalProperties: false, properties: { - path: { type: 'string' }, outDir: { type: 'string' }, + path: { type: 'string' }, + json: { type: 'boolean' }, + avm: { type: 'boolean' }, + debug: { type: 'boolean' }, + opcodes: { type: 'boolean' }, }, }, codegen: { @@ -157,8 +165,8 @@ const relativizePaths = (config: Configuration) => ({ }, contracts: { ...config.contracts, - path: nodePath.relative(process.cwd(), config.contracts.path), outDir: nodePath.relative(process.cwd(), config.contracts.outDir), + path: nodePath.relative(process.cwd(), config.contracts.path), }, codegen: { ...config.codegen, @@ -181,10 +189,18 @@ const createDefaultConfiguration = (configIn: Configuration, importDefaultNetwor ${exportConfig} { contracts: { - // NEO•ONE will look for smart contracts in this directory. - path: '${config.contracts.path}', // The NEO•ONE compile command will output the compile results in this directory. outDir: '${config.contracts.outDir}', + // NEO•ONE will look for smart contracts in this directory. + path: '${config.contracts.path}', + // Set this to true if you want the compile command to output JSON. + // json: ${config.contracts.json}, + // Set this to true if you want the compile command to output AVM. + // avm: ${config.contracts.avm}, + // Set this to true if you want the compile command to output additional debug information. + // debug: ${config.contracts.debug}, + // Set this to true if you want the compile command to output the AVM in a human-readable format for debugging (requires debug: true). + // opcodes: ${config.contracts.opcodes}, }, artifacts: { // NEO•ONE will store build and deployment artifacts that should be checked in to vcs in this directory. @@ -297,8 +313,8 @@ const validateConfig = async (rootDir: string, configIn: any): Promise .describe('path', 'Contract directory') .boolean('json') .describe('json', 'Output the contract with the JSON format') - .default('json', true) .boolean('avm') .describe('avm', 'Output the contract with the AVM format') - .default('avm', false) .boolean('debug') .describe('debug', 'Output additional debug information') - .default('debug', false) .boolean('opcodes') - .describe('opcodes', 'Output the AVM in a human readable format for debugging, requires --debug') - .default('opcodes', false); + .describe('opcodes', 'Output the AVM in a human readable format for debugging, requires --debug'); export const handler = (argv: Yarguments>) => { start(async (_cmd, config) => { - await createTasks( - argv.path ? argv.path : config.contracts.path, - argv.outDir ? argv.outDir : config.contracts.outDir, - { - json: argv.json ? argv.json : !argv.avm, - avm: argv.avm, - debug: argv.debug, - opcodes: argv.debug ? argv.opcodes : false, - }, - ).run(); + const configOptions = config.contracts; + const path = argv.path ? argv.path : configOptions.path; + const outDir = argv.outDir ? argv.outDir : configOptions.outDir; + const options = { + json: argv.json ? argv.json : configOptions.json, + avm: argv.avm ? argv.avm : configOptions.avm, + debug: argv.debug ? argv.debug : configOptions.debug, + opcodes: argv.opcodes ? argv.opcodes : configOptions.opcodes, + }; + if (options.opcodes && !options.debug) { + throw new Error('`opcodes` flag may only be specified alongside the `debug` flag'); + } + await createTasks(path, outDir, { + json: options.json ? options.json : !options.avm, + avm: options.avm ? options.avm : false, + debug: options.debug ? options.debug : false, + opcodes: options.opcodes ? options.opcodes : false, + }).run(); }); }; diff --git a/packages/neo-one-cli/src/cmd/console.ts b/packages/neo-one-cli/src/cmd/console.ts index ae0a3da899..087d7ff81a 100644 --- a/packages/neo-one-cli/src/cmd/console.ts +++ b/packages/neo-one-cli/src/cmd/console.ts @@ -6,11 +6,11 @@ import { startConsole } from '../console'; const defaultNetworks: readonly string[] = ['local']; export const command = 'console'; -export const describe = 'Starts a repl with project contracts and client APIs available.'; +export const describe = 'Starts a REPL with project contracts and client APIs available.'; export const builder = (yargsBuilder: typeof yargs) => yargsBuilder .array('networks') - .describe('networks', 'Networks to initialize before starting the repl.') + .describe('networks', 'Networks to initialize before starting the REPL.') .default('networks', defaultNetworks); export const handler = (argv: Yarguments>) => { start(async (_cmd, config) => startConsole(config, argv.networks)); diff --git a/packages/neo-one-cli/src/cmd/stop/neotracker.ts b/packages/neo-one-cli/src/cmd/stop/neotracker.ts index 8147aab7ed..fab58f153b 100644 --- a/packages/neo-one-cli/src/cmd/stop/neotracker.ts +++ b/packages/neo-one-cli/src/cmd/stop/neotracker.ts @@ -3,7 +3,7 @@ import { start } from '../../common'; import { findKillProcess } from '../../utils'; export const command = 'neotracker'; -export const describe = 'Stops the local neotracker instance.'; +export const describe = 'Stops the local NEO Tracker instance.'; export const builder = (yargsBuilder: typeof yargs) => yargsBuilder; export const handler = () => { start(async (_cmd, config) => { diff --git a/packages/neo-one-website/blog/2020-07-23-neo-one-2-7-announcement.md b/packages/neo-one-website/blog/2020-07-23-neo-one-2-7-announcement.md new file mode 100644 index 0000000000..0f396eda2b --- /dev/null +++ b/packages/neo-one-website/blog/2020-07-23-neo-one-2-7-announcement.md @@ -0,0 +1,67 @@ +--- +slug: 2020/07/23/neo-one-2-7-announcement +title: NEO•ONE 2.7 Announcement +author: The NEO•ONE Team +twitter: https://twitter.com/neo_one_suite +--- + +## NEO•ONE 2.7 + +We are excited to announce our latest release of NEO•ONE. For this release we have been focused on cleaning up bugs, adding new compiler features, expanding documentation, and preparing for future versions of NEO•ONE as we draw closer to the Neo3 release. + +To get started with NEO•ONE you can install our CLI with +`yarn install @neo-one/cli` + +## Compile + +Starting with NEO•ONE 2.7 you will be able to output your compiled smart contract to various format types as well as generate debug information as per the spec listed [here](https://github.com/ngdseattle/design-notes/blob/master/NDX-DN11%20-%20NEO%20Debug%20Info%20Specification.md). We hope this will give our users more freedom in the end-to-end tooling they choose to use for developing their smart contracts. To get started with testing these new features you can use: + +`yarn install @neo-one/cli` +`yarn neo-one init` +`yarn neo-one compile --json --avm --debug --opcodes` + +For more information on how to enable AVM / debug generation use + +`yarn neo-one compile --help` + +or see the [pull request](https://github.com/neo-one-suite/neo-one/pull/2071). + +### Further Work + +While we have added the ability to output our compiled smart contracts as `.debug` and `.avm` files there is still work to be done to integrate these features with other tooling, like the Neo Blockchain Toolkit. See the PR linked above or visit the new issue page [here](https://github.com/neo-one-suite/neo-one/issues/2113) for more information. Also be sure to check out our [documentation](/docs/how-to-contribute#How-Can-I-Contribute) on building from source if you would like to help contribute to the project! + +## Typescript Updates + +In continuing with our efforts to keep NEO•ONE up to date with Typescript we have [updated](https://github.com/neo-one-suite/neo-one/pull/2063) the project to use TypeScript version 3.9.5. While there aren’t as many new features available in the compiler as our [last](https://github.com/neo-one-suite/neo-one/pull/1984) update we want to keep our feature set as familiar to new developers as we can, especially as we gear up for Neo3. + +## Documentation + +We’ve added several new sections of documentation to the website: + +- [Deployment documentation](/docs/deployment) +- [The NEO•ONE CLI](/docs/cli) +- [Network configuration](/docs/configuration-options) +- [Project contribution](/docs/how-to-contribute#How-Can-I-Contribute) +- [Compiler contribution](/docs/smart-contract-compiler) + +Stumped on something and can’t find documentation for it? Feel free to submit a new [issue](https://github.com/neo-one-suite/neo-one/issues) to request it! + +## Bug Fixes / Feature Changes + +In NEO•ONE 2.7 several bugs have been fixed and features have been updated. You can see all the changes listed below. + +- [#2056 Generated createClient does not wait For account setup](https://github.com/neo-one-suite/neo-one/pull/2056) +- [#2051 Update default network options](https://github.com/neo-one-suite/neo-one/pull/2051) +- [#2093 Fix switch-statement execution](https://github.com/neo-one-suite/neo-one/pull/2093) +- [#2095 Fix number mismatches in SetStorage, ArrayStorage and MapStorage](https://github.com/neo-one-suite/neo-one/pull/2095) +- [#2086 Export `defaultnetwork` helper from CLI](https://github.com/neo-one-suite/neo-one/pull/2086) +- [#2080 Fix missing type declarations in shipped packages](https://github.com/neo-one-suite/neo-one/pull/2091) +- [#2096 Fix ‘receive’ invocations when relaying transactions to a live network](https://github.com/neo-one-suite/neo-one/pull/2096) +- [#2112 Fix error when using typescript migration file for deployment](https://github.com/neo-one-suite/neo-one/pull/2112) +- [#2034 Update npm release process for smoother releases](https://github.com/neo-one-suite/neo-one/pull/2034) + +## Future + +NEO•ONE 2.7 will be the last milestone release for NEO•ONE 2.x, while small bug fixes and integration fixes (like https://github.com/neo-one-suite/neo-one/pull/2034) will continue to be released on the 2.x version our work will primarily focus on updating NEO•ONE to be compatible with the Neo3 protocol. Look out for the upcoming releases that will include Neo3 Preview, TestNet and MainNet compatibility. + +Questions or concerns? Feel free to reach out to us on [GitHub](https://github.com/neo-one-suite/neo-one) or [Twitter](https://twitter.com/neo_one_suite) diff --git a/packages/neo-one-website/docs/0-installation/2-cli.md b/packages/neo-one-website/docs/0-installation/2-cli.md new file mode 100644 index 0000000000..27742281f9 --- /dev/null +++ b/packages/neo-one-website/docs/0-installation/2-cli.md @@ -0,0 +1,103 @@ +--- +slug: CLI +title: CLI +--- + +The NEO•ONE CLI is your entry point for all of NEO•ONE's functionality. + +Run `yarn neo-one --help` to see the CLI commands available and their descriptions. +Run `yarn neo-one --help` to see what arguments are available for that command. +Run `yarn neo-one --version` to get the version of NEO•ONE that you are running. + +--- + +[[toc]] + +--- + +## neo-one init + +Initializes a new project in the current directory. This will create a default `.neo-one.config.ts` configuration file, +a sample `Hello World` smart contract in `neo-one/contracts/HelloWorld.ts`, and a unit test in +`src/__tests__/HelloWorld.ts`. + +| Argument | Type | Default | Description | +| --------- | --------- | ------- | -------------------------------------------------------------------------------------------------------- | +| `--react` | `boolean` | `false` | Setting this to true will generate an example. React component that uses the `HelloWorld` smart contract | + +--- + +## neo-one build + +Builds the project and deploys it to the local development network based on the configuration found in the +NEO•ONE config file. + +| Argument | Type | Default | Description | +| --------- | --------- | ------- | ------------------------------------------------- | +| `--reset` | `boolean` | `false` | Setting this to true will reset the local project | + +--- + +## neo-one new + +Create new resources. `neo-one new private-key` is the only available option for now, which will generate a +new private key. + +--- + +## neo-one start + +Start NEO•ONE services. This command takes one argument after the command (`neo-one start `) which +can be either `network` or `neotracker`. `neo-one start network` will start the local development network. +`neo-one start neotracker` will start the local NEO Tracker instance. + +--- + +## neo-one stop + +Stop NEO•ONE services. This command takes one argument after the command (`neo-one stop `) which +can be either `network` or `neotracker`. `neo-one stop network` will stop the local development network. +`neo-one stop neotracker` will stop the local NEO Tracker instance. + +--- + +## neo-one deploy + +Deploys the project using the migration file. + +| Argument | Type | Default | Description | +| ----------- | -------- | -------- | ------------------------------- | +| `--network` | `string` | `"test"` | Network to run the migration on | + +--- + +## neo-one info + +Prints the project configuration. + +--- + +## neo-one compile + +Compiles a project's smart contracts and outputs the code to a local directory. You can set the arguments for this command +either in the NEO•ONE config file (`.neo-one.config.ts`) or as a CLI argument. A CLI argument will override what is found in the +config file. If an argument is not defined as a CLI argument and is not defined in the config file then the below defaults will be used. + +| Argument | Type | Default | Description | +| ----------- | --------- | ------------------- | ---------------------------------------------------------------------------- | +| `--outDir` | `string` | `neo-one/compiled` | Directory to output the compiled code | +| `--path` | `string` | `neo-one/contracts` | Path to the smart contract directory | +| `--json` | `boolean` | `true` | Output the contract with the JSON format | +| `--avm` | `boolean` | `false` | Output the contract with the AVM format | +| `--debug` | `boolean` | `false` | Output additional debug information | +| `--opcodes` | `boolean` | `false` | Output the AVM in a human-readable format for debugging (requires `--debug`) | + +--- + +## neo-one console + +Starts a REPL with project contracts and NEO•ONE Client APIs. + +| Argument | Type | Default | Description | +| ------------ | ------- | ----------- | ----------------------------------------------- | +| `--networks` | `array` | `["local"]` | Networks to initialize before starting the REPL | diff --git a/packages/neo-one-website/docs/0-installation/2-playground.md b/packages/neo-one-website/docs/0-installation/3-playground.md similarity index 100% rename from packages/neo-one-website/docs/0-installation/2-playground.md rename to packages/neo-one-website/docs/0-installation/3-playground.md diff --git a/packages/neo-one-website/docs/4-contributing/0-how-to-contribute.md b/packages/neo-one-website/docs/4-contributing/0-how-to-contribute.md index 074d108f3b..ec9c271bea 100644 --- a/packages/neo-one-website/docs/4-contributing/0-how-to-contribute.md +++ b/packages/neo-one-website/docs/4-contributing/0-how-to-contribute.md @@ -31,6 +31,25 @@ Well-written bug reports with consistently reproducible steps are invaluable to Feature requests are welcome. But take a moment to find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Please provide as much detail and context as possible. +### How to Get Started in the NEO•ONE Repo + +- Make sure you have [Node](https://nodejs.org) >= 10.16.0 installed (We recommend the latest version). + - Linux and Mac: We recommend using [Node Version Manager](https://github.com/creationix/nvm). + - Windows: We recommend using [Chocolatey](https://chocolatey.org/). +- Install [RushJS](https://rushjs.io/) with `npm install -g @microsoft/rush`. + - We use RushJS for monorepo management. When you get started in the NEO•ONE repo you will use RushJS for nearly every task, like installing dependencies, building the packages, running tests, etc. + - For more information on RushJS, see the [docs](https://rushjs.io/pages/intro/welcome/). + - All Rush commands should be run inside the NEO•ONE repo. +- Clone the repo with `git clone https://github.com/neo-one-suite/neo-one.git`. +- Then run `rush install` to install the dependencies. +- Then run `rush build` to build the packages. Rush will perform an "incremental build", which means that it will only build packages whose source files have changed since the last successful build and the packages that depend on those packages. +- You should now be ready to start making changes to the source code. Once you're done making changes make sure to run `rush build` before running E2E tests or trying to run a bin. +- To run all the unit tests run `rush test`. To run all the E2E tests run `rush e2e`. + - There are A LOT of unit tests, which can take a few minutes to run all the way through. To only run a smaller set of tests you can specify a file or blob of tests to run with `rush test -t` or `rush e2e -t`. + - For example, if you wanted to only run the unit tests in `neo-one-client-common` you would run `rush test -t packages/neo-one-client-common/src/__tests__/**/*` +- If you want to test your changes with the NEO•ONE CLI run `rush build`. Then, to start the CLI you'd run `node packages/neo-one-cli/bin/neo-one.js` from inside the NEO•ONE repository. You will then be running the new NEO•ONE CLI with your changes. From there you can see your new code directly in action. +- To see all the available RushJS commands run `rush --help`. + ### Your First Code Contribution Unsure where to begin contributing to NEO•ONE? Here are some great ways to get started: diff --git a/packages/neo-one-website/docs/4-contributing/2-smart-contract-compiler.md b/packages/neo-one-website/docs/4-contributing/2-smart-contract-compiler.md index c1b9c8f035..170dac5dbf 100644 --- a/packages/neo-one-website/docs/4-contributing/2-smart-contract-compiler.md +++ b/packages/neo-one-website/docs/4-contributing/2-smart-contract-compiler.md @@ -3,4 +3,60 @@ slug: smart-contract-compiler title: Smart Contract Compiler --- -Coming soon! +## How Can I Add New Features or Fix Bugs in the Smart Contract Compiler? + +### Basics of the Smart Contract Compiler + +The NEO•ONE Smart Contract Compiler is by far the _largest_ NEO•ONE package. The compiler takes in (almost) regular +TypeScript code and compiles it to [NeoVM](https://docs.neo.org/docs/en-us/basic/technology/neovm.html) bytecode, which can +then be deployed to the Neo blockchain and run on the NeoVM. NEO•ONE uses the TypeScript compiler API to parse the TypeScript code +into a tree of "nodes" with information about each node. Our compiler then "visits" each node and begins to output specific +bytecode for the VM instructions that are needed in order to execute the logic that is specified by the TypeScript code. +The bytecode outputted by the compiler corresponds to human-readable opcodes that each correspond to an action that the +NeoVM will perform. These actions are the manipulation of data by the NeoVM that will ultimately translate to changes to the +state of the Neo blockchain. + +### Where to Look in the Code + +Now that you have a _very_ basic understanding of how the NEO•ONE compiler works, you can start digging into the `neo-one-smart-contract-compiler` +package. Most likely you'll be looking in `neo-one-smart-contract-compiler/compiler/` (where `` is one of `constants`, `declaration`, `expression`, `helper`, `scope`, `statement`) +for the specific syntax that is broken or where you want to add a feature. For example, if you want to change how we compile the `==` token, you would +look for `EqualsEqualsEqualsHelper.ts` in `neo-one-smart-contract-compiler/compiler/helper/relational/EqualsEqualsHelper.ts`. In there you'll see +how this helper will "emit" different opcodes, syscalls, and other helpers to manipulate the Evaluation Stack. The comment line above each emit shows a +representation of the Evaluation Stack _after_ that bytecode is evaluated. + +### Write Unit Tests for What You're Working On + +Once you have an understanding of what helpers or syntax compilers you need to change in order to make your compiler change, the best way to begin is to write +a unit test that you will run to test your change. You'll see that nearly every helper and syntax compiler has a corresponding set of unit tests in `neo-one-smart-contract-compiler/src/__tests__`. +For example, the `IfStatementCompiler.ts` has a set of unit tests in `IfStatementCompiler.test.ts`. In there you'll see that we typically use the built in `assertEqual` method to +test if values are what we expect them to be. You'll also see that we have helpers, like the `helpers.executeString()` helper, that make it easy to compile a string and test for certain behavior. + +Here is an example unit test you would write to test your changes: + +```ts +import { helpers } from '../../../__data__'; + +describe('MyNewCompiler', () => { + test.only('simple test', async () => { + await helpers.executeString(` + if (!true) { + throw 'Failure'; + } + + const x = '10'; + assertEqual(x, '10'); + `); + }); +}); +``` + +### Start Hacking + +Once you've created a unit test that either recreates the bug you're trying to fix, or tests for the expected behavior of your new feature, you can start to make changes +to the compiler's source code and run your unit test. If you want to add logging (ie. `console.log`) to the source code to get more information you can, just make sure +to change the console settings in `neo-one-build-tests/environments/test/jestSetup.js`. From there you should make sure to only run one unit test at a time +so that you're only getting logs from the compilation of that one unit test. This will make it easier to learn what the compiler is doing when compiling a specific string. +To run a specific unit test, rather than all unit tests, run `rush test -t `. + +And that's it! Once you have this workflow setup you can hack away at the compiler code and run the unit test to test your changes, get logs, etc.