Skip to content

Commit

Permalink
README.md grammar and formatting updates (#833)
Browse files Browse the repository at this point in the history
<!--
Thanks for submitting a pull request! Here are some helpful tips:

* Always create branches on and target the `develop` branch.
* Run all the tests locally and ensure that they are passing.
* Run `make format` to ensure that the code is formatted.
* Run `make check` to ensure that all checks passed successfully.
* Small commits and contributions that attempt one single goal is
preferable.
* If the idea changes or adds anything functional which will affect
users, an
AIP discussion is required first on the Aurora forum: 

https://forum.aurora.dev/discussions/AIPs%20(Aurora%20Improvement%20Proposals).
* Avoid breaking the public API (namely in engine/src/lib.rs) unless
required.
* If your PR is a WIP, ensure that you enable "draft" mode.
* Your first PRs won't use the CI automatically unless a maintainer
starts.
If this is not your first PR, please do NOT abuse the CI resources.

Checklist:
- [x] I have performed a self-review of my code
- [ ] I have documented my code, particularly in the hard-to-understand
areas
- [ ] I have made corresponding changes to the documentation
- [ ] I have added tests to prove my fix or new feature is effective and
works
- [ ] Any dependent changes have been merged
- [x] The PR is targeting the `develop` branch and not `master`
- [ ] I have pre-squashed my commits into a single commit and rebased.
-->

## Description

<!-- 
Provide a general summary of your changes. A clear overview along with
an
in-depth explanation is beneficial.

If this PR closes any issues, be sure to add "closes #<number>"
somewhere.
-->

This is a documentation only change to the `README.md` file. I updated
some portions that had some grammar issues and updated some formatting.

## Performance / NEAR gas cost considerations

N/A

## Testing

N/A, `README.md` change only.

## How should this be reviewed

README only change, so let me know if the changes make it easier to
read/follow the instructions. Happy to make more updates.

---------

Co-authored-by: Oleksandr Anyshchenko <oleksandr.anyshchenko@aurora.dev>
  • Loading branch information
ForwardSlashBack and aleksuss authored Oct 11, 2023
1 parent eccae2f commit 4d8d547
Showing 1 changed file with 42 additions and 37 deletions.
79 changes: 42 additions & 37 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ cargo install --force cargo-make
### Branches

- [`master`] is the current stable branch.
It must be ready, anytime, to deployed on chain at a moment's notice.
It must be ready, at all times, to be deployed on chain at a moment's notice.

- [`develop`] is our bleeding-edge development branch.
In general, kindly target all pull requests to this branch.
Expand All @@ -53,37 +53,38 @@ cargo install --force cargo-make
Every task with `cargo make` must have a `--profile` argument.

The current available `profile`s are:
- `mainnet`, suitable for mainnet.
- `mainnet-silo`, silo contract suitable for mainnet.
- `testnet`, suitable for testnet.
- `testnet-silo`, silo contract suitable for testnet.
- `local`, suitable for local development.
- `custom`, suitable for custom environments, see note below.

A custom environment may be required depending on the circumstances. This can
- `mainnet`: suitable for mainnet.
- `mainnet-silo`: silo contract suitable for mainnet.
- `testnet`: suitable for testnet.
- `testnet-silo`: silo contract suitable for testnet.
- `local`: suitable for local development.
- `custom`: suitable for custom environments, see note below.

In some circumstances, you may require a custom environment. This can
be created in the `.env` folder as `custom.env` following the structure of the
other `.env` files. See `bin/local-custom.env` for more details.

Every make must follow the following pattern, though `--profile` is not required
for all such as cleanup:
Every `make` invocation must follow the following pattern, though `--profile` is
not required in all cases (such as cleanup):

```sh
cargo make [--profile <profile>] <task>
```

#### Building the engine and contracts

To build the binaries there are a few commands to do such following the format.
There are several commands that can be used to build the binaries. The currently supported parameters
for the `task` field are listed below:

The current available build `task`s are:
- `default`, does not need to be specified, runs `build`. Requires a `--profile`
- `default`: does not need to be specified, runs `build`. Requires a `--profile`
argument.
- `build`, builds all engine smart contract and produces the
- `build`: builds all engine smart contract and produces the
`aurora-<profile>-test.wasm` in the `bin` folder. Requires `build-contracts`.
Requires a `--profile` argument.
- `build-test`, builds all the below using test features. Requires a `--profile`
- `build-test`: builds all the below using test features. Requires a `--profile`
argument.
- `build-contracts`, builds all the ETH contracts.
- `build-docker`, builds the `aurora-<profile>-test.wasm` in the `bin` folder using docker build environment. The purpose of this task is to produce reproducible binaries.
- `build-contracts`: builds all the ETH contracts.
- `build-docker`: builds the `aurora-<profile>-test.wasm` in the `bin` folder using docker build environment. The purpose of this task is to produce reproducible binaries.

For example, the following will build the mainnet debug binary:
```sh
Expand All @@ -92,7 +93,7 @@ cargo make --profile mainnet build

#### Verifying binary hash

To verify that a deployed binary matches the source code, you may want build it reproducibly and then check that their hashes match. The motivation behind that is to prevent malicious code from being deployed.
To verify that a deployed binary matches the source code, you may want build it reproducibly and then verify that the SHA256 hash matches that of the deployed binary. The motivation behind this is to prevent malicious code from being deployed.

Run these commands to produce the binary hash:
```sh
Expand All @@ -103,11 +104,12 @@ shasum -a 256 bin/aurora-<profile>.wasm
#### Running unit & integration tests

To run tests, there are a few cargo make tasks we can run:
- `test`, tests the whole cargo workspace, ETH contracts and runs modexp benchmarks. Requires a `--profile` argument.
- `test-flow`, tests the whole cargo workspace and ETH contracts. Requires a `--profile` argument.
- `bench-modexp`, runs modexp benchmarks. Requires a `--profile` argument.
- `test-workspace`, tests only the cargo workspace.
- `test-contracts`, tests only the contracts.
- `test`: tests the whole cargo workspace and ETH contracts. Requires a `--profile` argument.
- `test-workspace`: tests only the cargo workspace.
- `test-contracts`: tests only the contracts.
- `test`: tests the whole cargo workspace, ETH contracts and runs modexp benchmarks. Requires a `--profile` argument.
- `test-flow`: tests the whole cargo workspace and ETH contracts. Requires a `--profile` argument.
- `bench-modexp`: runs modexp benchmarks. Requires a `--profile` argument.

For example, the following will test the whole workspace and ETH contracts:
```sh
Expand All @@ -116,28 +118,31 @@ cargo make --profile mainnet test

#### Running checks & lints

To run lints and checks, the following tasks are available:
- `check`, checks the format, clippy and ETH contracts.
- `check-contracts`, runs yarn lints on the ETH contracts.
- `check-fmt`, checks the workspace Rust format only.
- `clippy`, checks the Rust workspace with clippy only.
The following tasks are available to run lints and checks:

- `check`: checks the format, clippy and ETH contracts.
- `check-contracts` runs yarn lints on the ETH contracts.
- `check-fmt`: checks the workspace Rust format only.
- `clippy`: checks the Rust workspace with clippy only.

For example the following command will run the checks. `profile` is not required
For example, the following command will run the checks. `profile` is not required
here:
```
cargo make check
```

#### Cleanup

To clean up the workspace, the following tasks are available:
- `clean`, cleans all built binaries and ETH contracts.
- `clean-cargo`, cleans with cargo.
- `clean-contracts`, cleans the ETH contracts.
- `clean-bin`, cleans the binaries.
The following tasks are available to clean up the workspace:

- `clean`: cleans all built binaries and ETH contracts.
- `clean-cargo`: cleans with cargo.
- `clean-contracts`: cleans the ETH contracts.
- `clean-bin`: cleans the binaries.

Additionally, there is also but not included in the `clean` task:
- `sweep`, sweeps the set amount of days in the ENV, default at 30 days.

- `sweep`: sweeps the set amount of days in the ENV, default at 30 days.

For example, the following command will clean everything. `profile` is not
required:
Expand All @@ -150,5 +155,5 @@ cargo make clean

## License
**aurora-engine** has multiple licenses:
* all crates except `engine-test` has **CCO-1.0** license
* All crates except `engine-test` has **CCO-1.0** license
* `engine-test` has **GPL-v3** license

0 comments on commit 4d8d547

Please sign in to comment.