diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b1d8d1ccfd..bc02350218 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,6 +46,9 @@ GitHub provides additional document on [forking a repository](https://help.githu ## Finding contributions to work on Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start. +## Developer Guides +- [Node](./node/DEVELOPER.md) +- [Python](./python/DEVELOPER.md) ## Code of Conduct This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). diff --git a/node/DEVELOPER.md b/node/DEVELOPER.md new file mode 100644 index 0000000000..0a8d297c8b --- /dev/null +++ b/node/DEVELOPER.md @@ -0,0 +1,71 @@ +# Developer Guide + +This document describes how to set up your development environment to build and test the Babushka Node wrapper. + +### Development Overview + +The Babushka Node wrapper consists of both TypeScript and Rust code. Rust bindings for Node.js are implemented using [napi-rs](https://github.com/napi-rs/napi-rs). The Node and Rust components communicate using the [protobuf](https://github.com/protocolbuffers/protobuf) protocol. + + +### Build + +- Follow the building instructions for the Node wrapper in the [Build from source](https://github.com/aws/babushka/blob/main/node/README.md#build-from-source) section to clone the code and build the wrapper. +- For a fast build, execute `npm run build`. This will perform a full, unoptimized build, which is suitable for developing tests. Keep in mind that performance is significantly affected in an unoptimized build, so it's required to build with the `build:release` or `build:benchmark` option when measuring performance. +- If your modifications are limited to the TypeScript code, run `npm run build-external` to build the external package without rebuilding the internal package. +- If your modifications are limited to the Rust code, execute `npm run build-internal` to build the internal package and generate TypeScript code. +- To generate Node's protobuf files, execute `npm run build-protobuf`. Keep in mind that protobuf files are generated as part of full builds (e.g., `build`, `build:release`, etc.). + +> Note: Once building completed, you'll find the compiled JavaScript code in the `node/build-ts` folder. + + +### Test + +To run tests, use the following command: + +```bash +npm test +``` + +### Submodules + +After pulling new changes, ensure that you update the submodules by running the following command: + +```bash +git submodule update +``` + +### Linters +Development on the Node wrapper may involve changes in either the TypeScript or Rust code. Each language has distinct linter tests that must be passed before committing changes. + +#### Language-specific Linters + +__TypeScript:__ +- ESLint +- Prettier + +__Rust:__ +- clippy +- fmt + +#### Running the linters +1. TypeScript + ```bash + # Run from the `node` folder + npm install eslint-plugin-import@latest @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-tsdoc eslint typescript eslint-plugin-import@latest eslint-config-prettier + npm i + npx eslint . --max-warnings=0 + ``` +2. Rust + ```bash + # Run from the `node/rust-client` folder + rustup component add clippy rustfmt + cargo clippy --all-features --all-targets -- -D warnings + cargo fmt --manifest-path ./Cargo.toml --all + ``` + +### Recommended extensions for VS Code +- [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - JavaScript / TypeScript formatter. +- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - linter. +- [Jest Runner](https://marketplace.visualstudio.com/items?itemName=firsttris.vscode-jest-runner) - in-editor test runner. +- [Jest Test Explorer](https://marketplace.visualstudio.com/items?itemName=kavod-io.vscode-jest-test-adapter) - adapter to the VSCode testing UI. +- [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) - Rust language support for VSCode. diff --git a/python/DEVELOPER.md b/python/DEVELOPER.md index 7ae6c0c5d4..8a505d25b5 100644 --- a/python/DEVELOPER.md +++ b/python/DEVELOPER.md @@ -1,10 +1,10 @@ # Developer Guide -This document describes how to set up your development environment to build and test Babushka Python wrapper. +This document describes how to set up your development environment to build and test the Babushka Python wrapper. ### Development Overview -The Babushka Python wrapper consists of both Python and Rust code. Rust bindings for Python are implemented using [PyO3](https://github.com/PyO3/pyo3), and the Python package is built using [maturin](https://github.com/PyO3/maturin). The Python and Rust components communicate using the [protobuf](https://github.com/protocolbuffers/protobuf) protocol. +The Babushka Python wrapper consists of both Python and Rust code. Rust bindings for Python are implemented using [PyO3](https://github.com/PyO3/pyo3), and the Python package is built using [maturin](https://github.com/PyO3/maturin). The Python and Rust components communicate using the [protobuf](https://github.com/protocolbuffers/protobuf) protocol. ### Build @@ -79,6 +79,7 @@ Run from the main `/python` folder 1. Python > Note: make sure to [generate protobuf with interface files]("#protobuf-interface-files") before running mypy linter ```bash + pip install -r dev_requirements.txt isort . --profile black --skip-glob python/pybushka/protobuf black . --exclude python/pybushka/protobuf flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics --exclude=python/pybushka/protobuf,.env/* --extend-ignore=E230 @@ -88,6 +89,7 @@ Run from the main `/python` folder ``` 2. Rust ```bash + rustup component add clippy rustfmt cargo clippy --all-features --all-targets -- -D warnings cargo fmt --manifest-path ./Cargo.toml --all