docs: add development guide

Signed-off-by: Zxilly <[email protected]>

DEVELOPMENT.md

@@ -0,0 +1,203 @@
+# Development Guide
+
+An overview of the tools and scripts used in the project.
+
+## Golang
+
+The project currently runs with `Go Toolchain`. Use any Go version that supports it.
+
+The project has some build tags that can be used to build the project with different configurations.
+
+### Build tags
+
+#### `embed`
+
+This tag is used to embed the static files into the binary. Without this tag, the static files are download from 
+the `v1` tag of the release.
+
+#### `js` and `wasm`
+
+This tag is used to build the project to WebAssembly. With this tag enabled, some printer will be disabled and the
+json marshaler will be changed to the `wasm` marshaler.
+
+#### profiler tags
+
+##### `pgo`
+
+Enables `cpu` profiler to collect info for Profile-Guided Optimization.
+
+##### `profiler`
+
+Enables all profilers while running integration tests.
+
+### Tests
+
+#### Unit tests
+
+Unit tests are split into different parts.
+
+- `embed` build tag
+- `GOOS=js GOARCH=wasm` build constraints
+
+For wasm tests, you will need a runner for wasm files. 
+
+You can give [Zxilly/go_js_wasm_exec](https://github.com/Zxilly/go_js_wasm_exec) a try. 
+
+> This runner needs `Node.js` installed on your machine. It's a wrapper of the official `misc/wasm/go_js_wasm_exec` runner.
+
+Or you can use [agnivade/wasmbrowsertest](https://github.com/agnivade/wasmbrowsertest), 
+but it has bugs under Go Toolchain environment. see [issue](https://github.com/agnivade/wasmbrowsertest/issues/61).
+
+#### Integration tests
+
+Integrations tests should run by helper scripts described following.
+It executes on the binaries from [Zxilly/go-testdata](https://github.com/Zxilly/go-testdata)
+
+### Helper scripts
+
+Helper scripts are managed by `poetry` and `python`. Make sure you have them installed.
+
+All the scripts are in the `scripts` directory.
+
+#### Download binary
+
+Download binary from the [Zxilly/go-testdata](https://github.com/Zxilly/go-testdata).
+
+```bash
+python scripts/ensure.py --help
+usage: ensure.py [-h] [--example] [--real]
+
+options:
+  -h, --help  show this help message and exit
+  --example   Download example binaries.
+  --real      Download real binaries.
+```
+
+#### Tests
+
+```bash
+python scripts/tests.py --help
+usage: tests.py [-h] [--unit-full] [--unit-wasm] [--unit-embed] [--unit] [--integration-example] [--integration-real] [--integration]
+
+options:
+  -h, --help            show this help message and exit
+  --unit-full           Run full unit tests.
+  --unit-wasm           Run unit tests for wasm.
+  --unit-embed          Run unit tests for embed
+  --unit                Run unit tests.
+  --integration-example
+                        Run integration tests for small binaries.
+  --integration-real    Run integration tests for large binaries.
+  --integration         Run all integration tests.
+```
+
+##### Integration binary source generator
+
+Generate `scripts/binaries.csv` as the source to tests.
+
+```bash
+python scripts/generate.py
+```
+
+##### Reporter for CI
+
+Collect the test results and generate a report in GitHub Actions format.
+
+Requires `svgo` installed to optimize the SVG files.
+
+It uses service [Zxilly/data2image](https://github.com/Zxilly/data2image) to bypass
+GitHub data-uri limit. This project was written in `Rust`.
+
+The svg data was optimized by `svgo` then compressed by `zstd` and encoded by `base64`
+to be included safely in the url.
+
+```bash
+python scripts/report.py
+```
+
+#### Build
+
+##### Wasm
+
+Requires [WebAssembly/binaryen](https://github.com/WebAssembly/binaryen) installed to optimize the wasm binary.
+
+```bash
+python scripts/wasm.py --help
+usage: wasm.py [-h] [--raw]
+
+options:
+  -h, --help  show this help message and exit
+  --raw       Do not optimize the wasm binary
+```
+
+##### Profile Guided Optimization
+
+Collect the profile data, then build `./cmd/gsa` with the profile data.
+
+```bash
+python scripts/pgo.py
+```
+
+### Linter
+
+The project uses `golangci-lint` to lint the code.
+
+> Golangci-lint doesn't official supports `Go 1.23` right now. Use preview version from PR.
+
+```bash
+golangci-lint run
+```
+
+## TypeScript and React
+
+The project uses `TypeScript` and `React` to build the web interface.
+Most of the file is in the `ui` directory.
+
+### Build
+
+The project uses `pnpm` to manage the dependencies.
+
+```bash
+pnpm install
+```
+
+#### Explorer
+
+The explorer needs built `wasm` file from go part.
+
+Just run `scripts/wasm.py` should place it at the right place.
+
+```bash
+pnpm run dev:explorer # Development
+pnpm run build:explorer # Production
+```
+
+#### Webui
+
+The built file `./ui/dist/index.html` should be placed in `internal/webui` to be embedded in the binary.
+Don't forget attach the `embed` build tag.
+
+```bash
+pnpm run dev:ui # Development
+pnpm run build:ui # Production
+```
+
+### Tests
+
+```bash
+pnpm run test
+```
+
+### Linter
+
+The project uses `eslint` to lint the code.
+
+```bash
+pnpm run lint
+pnpm run lint:fix
+```
+
+## Typos
+
+The project uses [crate-ci/typos](https://github.com/crate-ci/typos) to find typos.
+

README.md

@@ -7,7 +7,7 @@
 [![go-recipes](https://raw.githubusercontent.com/nikolaydubina/go-recipes/main/badge.svg?raw=true)](https://github.com/nikolaydubina/go-recipes?tab=readme-ov-file#-visualise-dependencies-size-in-compiled-binaries-with-go-size-analyzer)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Zxilly/go-size-analyzer/badge)](https://scorecard.dev/viewer/?uri=github.com/Zxilly/go-size-analyzer)
 
-English | [简体中文](./README_zh-CN.md)
+English | [简体中文](./README_zh_CN)
 
 A simple tool to analyze the size of a Go compiled binary.
 
@@ -245,6 +245,8 @@ Terminal interface options
 
 Any contribution is welcome, feel free to open an issue or a pull request.
 
+For development, see the [Development Guide](./DEVELOPMENT.md) for more details.
+
 ## LICENSE
 
 Published under the [AGPL-3.0](./LICENSE).

README_zh-CN.md → README_zh_CN.md

@@ -243,6 +243,8 @@ Terminal interface options
 
 欢迎任何形式的贡献，随时提出问题或拉取请求。
 
+关于开发，请查看 [开发指南](./DEVELOPMENT.md) 以获取更多详细信息。
+
 ## LICENSE
 
 根据 [AGPL-3.0](./LICENSE) 发布。