docs(README): refactor

2022-01-28 14:59:37 +01:00
parent 4c6ecf8b28
commit 647aabb39c
1 changed files with 119 additions and 31 deletions
--- a/README.md
+++ b/README.md
@@ -1,47 +1,118 @@
-# app-ethereum
-Ethereum wallet application framework for Nano S and Nano X.
-Ledger Blue is not maintained anymore, but the app can still be compiled for this target using the branch `blue-final-release`.
+<br />
+<div align="center">
+  <a href="https://github.com/LedgerHQ/app-ethereum">
+    <img src="https://img.icons8.com/nolan/64/ethereum.png"/>
+  </a>
+
+  <h1 align="center">app-ethereum</h1>
+
+  <p align="center">
+    Ethereum wallet application for Ledger Blue, Nano S and Nano X
+    <br />
+    <a href="https://github.com/LedgerHQ/app-ethereum/tree/master/doc"><strong>« Explore the docs »</strong></a>
+    <br />
+    <br />
+    <a href="https://github.com/LedgerHQ/app-ethereum/issues">Report Bug</a>
+    · <a href="https://github.com/LedgerHQ/app-ethereum/issues">Request Feature</a>
+  </p>
+</div>
+<br/>
+
+<details>
+  <summary>Table of Contents</summary>
+
+- [About the project](#about-the-project)
+- [Documentation](#documentation)
+  - [Plugins](#plugins)
+- [Testing](#testing)
+  - [Requirement](#requirement)
+    - [Build the applications required by the test suite](#build-the-applications-required-by-the-test-suite)
+  - [Running all tests](#running-all-tests)
+    - [With Makefile](#with-makefile)
+    - [With yarn](#with-yarn)
+  - [Running a specific tests](#running-a-specific-tests)
+  - [Adding tests](#adding-tests)
+    - [Zemu](#zemu)
+    - [Update binaries](#update-binaries)
+- [Contributing](#contributing)
+
+
+</details>
+
+## About the project
+
+Ethereum wallet application framework for Nano S and Nano X.  
+Ledger Blue is not maintained anymore, but the app can still be compiled for this target using the branch [`blue-final-release`](https://github.com/LedgerHQ/app-ethereum/tree/blue-final-release).
+
+## Documentation

 This app follows the specification available in the `doc/` folder.

 To compile it and load it on a device, please check out our [developer portal](https://developers.ledger.com/docs/nano-app/introduction/).

-# Plugins
+### Plugins

-This app support external plugins. More info in [doc/ethapp_plugin.asc](https://github.com/LedgerHQ/app-ethereum/blob/master/doc/ethapp_plugins.asc). If you wish to have a look at an existing plugin, feel free to check out the [Boilerplate plugin](https://github.com/LedgerHQ/app-plugin-boilerplate).
+We have the concept of plugins in the ETH app.  
+Find the documentations here:  
+- [Blog Ethereum plugins](https://blog.ledger.com/ethereum-plugins/)
+- [Ethereum application Plugins : Technical Specifications](https://github.com/LedgerHQ/app-ethereum/blob/master/doc/ethapp_plugins.asc)
+- [Plugin guide](https://hackmd.io/300Ukv5gSbCbVcp3cZuwRQ)
+- [Boilerplate plugin](https://github.com/LedgerHQ/app-plugin-boilerplate)

-# Testing
+## Testing

 Testing is done via the open-source framework [zemu](https://github.com/Zondax/zemu).

-## Running tests
+### Requirement

-First [install yarn](https://classic.yarnpkg.com/en/docs/install/#debian-stable).
-Open `tests/build_local_test_elfs.sh` and add your BOLOS SDKs path to `NANOS_SDK` and `NANOX_SDK`.
-This helper script will build the applications required by the test suite and move them at the right place.
-```
-cd tests
-./build_local_test_elfs.sh
-```
-Then you can install the project by simply running:
-```
-cd ..
-make test
-```
-This will run `make install_tests` and `make run_tests`
+- [nodeJS](https://github.com/nvm-sh/nvm)
+- [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#debian-stable)
+- [build environnement](https://github.com/LedgerHQ/ledger-app-builder/blob/master/Dockerfile)

-To run a specific tests (here the send test):
-```
-cd tests
-jest --runInBand --detectOpenHandles src/send.test.js
-```
+#### Build the applications required by the test suite  

-Make sure you're in the `tests` folder before running `jest` or `yarn test`.
+1. Add your BOLOS SDKs path to:
+    - `NANOS_SDK` and `NANOX_SDK`
+
+2. Go to the `tests` folder and run `./build_local_test_elfs.sh`
+    - ```sh
+        cd tests
+        # This helper script will build the applications required by the test suite and move them at the right place.
+        yarn install
+        ./build_local_test_elfs.sh
+      ```
+
+### Running all tests
+#### With Makefile
+
+1. Then you can install the project by simply running on the `root` of the repo:
+    - ```sh
+        make test
+      ```
+    - This will run `make install_tests` and `make run_tests`
+
+#### With yarn
+
+1. Go to the `tests` folder and run:
+    - ```sh
+        yarn test
+      ```
+
+### Running a specific tests
+
+1.  Go to the `tests` folder and run:
+    - ```sh
+        yarn jest --runInBand --detectOpenHandles {YourTestFile}
+      ```
+2.  For example with the `send test`:
+    - ```sh
+        yarn jest --runInBand --detectOpenHandles src/send.test.js
+      ```


-## Adding tests
+### Adding tests

-### Zemu
+#### Zemu

 To add tests, copy one of the already existing test files in `tests/src/`.
 You then need to adapt the `buffer` and `tx` variables to adapt to the APDU you wish to send.
@@ -54,16 +125,33 @@ You then need to adapt the `buffer` and `tx` variables to adapt to the APDU you

 Finally make sure you adapt the expected signature!

-### Update binaries
+#### Update binaries

 Don't forget to update the binaries in the test folder. To do so, compile with those environement variables:
-```
+
+```sh
 make DEBUG=1 ALLOW_DATA=1
 ```

 Then copy the binary to the `tests/elfs` folder (in this case, compiled with SDK for nanoS):
-```
+
+```sh
 cp bin/app.elf tests/elfs/ethereum_nanos.elf
 ```

 Repeat the operation for a binary compiled with nanoX SDK and change for `ethereum_nanox.elf`.
+
+
+## Contributing
+
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+
+If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag `enhancement`.
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/my-feature`)
+3. Commit your Changes (`git commit -m 'feat: my new feature`)
+4. Push to the Branch (`git push origin feature/my-feature`)
+5. Open a Pull Request
+
+Please try to follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).