Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(docs): add docs on contributing #2117

Merged
merged 1 commit into from
Jul 23, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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"
}
11 changes: 11 additions & 0 deletions common/changes/@neo-one/cli-common/release_2020-07-23-21-27.json
Original file line number Diff line number Diff line change
@@ -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"
}
11 changes: 11 additions & 0 deletions common/changes/@neo-one/cli/release_2020-07-23-21-27.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"changes": [
{
"packageName": "@neo-one/cli",
"comment": "Update CLI compile options.",
"type": "patch"
}
],
"packageName": "@neo-one/cli",
"email": "spencercorwin@icloud.com"
}
30 changes: 23 additions & 7 deletions packages/neo-one-cli-common-node/src/configuration.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'),
Expand Down Expand Up @@ -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: {
Expand Down Expand Up @@ -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,
Expand All @@ -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.
Expand Down Expand Up @@ -297,8 +313,8 @@ const validateConfig = async (rootDir: string, configIn: any): Promise<Configura
},
contracts: {
...config.contracts,
path: nodePath.resolve(rootDir, config.contracts.path),
outDir: nodePath.resolve(rootDir, config.contracts.outDir),
path: nodePath.resolve(rootDir, config.contracts.path),
},
codegen: {
...config.codegen,
Expand Down
6 changes: 5 additions & 1 deletion packages/neo-one-cli-common/src/configuration.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,12 @@ export type CodegenFramework = 'none' | 'react' | 'angular' | 'vue';
export type CodegenLanguage = 'typescript' | 'javascript';

export interface ContractsConfiguration {
readonly path: string;
readonly outDir: string;
readonly path: string;
readonly json?: boolean;
readonly avm?: boolean;
readonly debug?: boolean;
readonly opcodes?: boolean;
}

export interface CodegenConfiguration {
Expand Down
34 changes: 19 additions & 15 deletions packages/neo-one-cli/src/cmd/compile.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,28 +13,32 @@ export const builder = (yargsBuilder: typeof yargs) =>
.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<ReturnType<typeof builder>>) => {
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();
});
};
4 changes: 2 additions & 2 deletions packages/neo-one-cli/src/cmd/console.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<ReturnType<typeof builder>>) => {
start(async (_cmd, config) => startConsole(config, argv.networks));
Expand Down
2 changes: 1 addition & 1 deletion packages/neo-one-cli/src/cmd/stop/neotracker.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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) => {
Expand Down
Original file line number Diff line number Diff line change
@@ -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)
103 changes: 103 additions & 0 deletions packages/neo-one-website/docs/0-installation/2-cli.md
Original file line number Diff line number Diff line change
@@ -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 <command> --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 <arg>`) 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 <arg>`) 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 |
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading