feat: doc

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,10 +5,10 @@ _Please list issues fixed by this PR here, using format "Fixes #the-issue-number
 ## Checklist
 
 - [ ] An issue to be fixed by this PR is listed above.
-- [ ] New tests are added to ensure new features are working. End-to-end tests are usually in the `./frb_example/pure_dart` example, more specifically, `rust/src/api/whatever.rs` and `test/api/whatever_test.dart`.
+- [ ] New tests are added to ensure new features are working. Please refer to [this page](https://cjycode.com/flutter_rust_bridge/guides/contributing/tip) to see how to add a test.
 - [ ] `./frb_internal precommit --mode slow` (or `fast`) is run (it internal runs code generator, does auto formatting, etc).
 - [ ] If this PR adds/changes features, documentations (in the `./website` folder) are updated.
-- [ ] CI is passing. (Operations are reproducible using corresponding `./frb_internal something` commands shown in CI.)
+- [ ] CI is passing. Please refer to [this page](https://cjycode.com/flutter_rust_bridge/guides/contributing/tip) to see how to solve a failed CI.
 
 ## Remark for PR creator
 

README.md

@@ -87,6 +87,7 @@ This package is [officially Flutter Favorite](https://docs.flutter.dev/packages-
 * **Easy to code-review & convince yourself**: This package simply simulates how humans write boilerplate code. If you want to convince yourself (or your team) that it is safe, there is not much code to track.
 * **Fast**: It is only a thin (though feature-rich) wrapper, benchmarked on CI, and even has multiple codecs for best performance under different workloads.
 * **Hackable**: If (for whatever reason) you want to hack the source, there are contributor guides, code is modular, and the execution logic is intuitive.
+* **Ask questions**: Feel free to ask questions in the issue tracker, and I usually reply within hours (if not sleeping).
 
 ### Why Flutter + Rust?
 

website/docs/guides/contributing/tip.md

@@ -1,32 +1,52 @@
-# Tips for development
+# Tips and procedures
 
-## The `./frb_internal`
+## How to add a test
+
+:::info
+This package has some scripts to automatically create more tests based on the test you write,
+so you write one test and get (usually) six tests ;)
+
+That's why adding a test seems slightly more complex than usual - but surely quicker than manually writing 6 tests.
+:::
+
+1. In `./frb_example/pure_dart`,
+add your test in (for example) `rust/src/api/whatever.rs` and `test/api/whatever_test.dart`.
+2. Remember to mimic existing tests and add `_twin_normal`/`TwinNormal`/etc as appropriate (this allows more "twin" tests to be generated).
+3. Run `./frbinternal precommit --mode slow`, or if that's too slow,
+run `./frb_internal generate-internal-frb-example-pure-dart && ./frb_internal generate-run-frb-codegen-command-generate --package frb_example/pure_dart`
+
+## How to solve failed CI
+
+* **When it is merely flaky**: Sometimes it is just flaky, not real bug. Thus, try to re-run the CI jobs
+(e.g. by pushing a commit that does no real work in order to trigger the CI) and see.
+* **Quickly solve git-diff errors**: If the CI is unhappy and provide you git diffs,
+you can either run code generator locally, or directly *copy-and-paste* and `git apply` those diffs to fix your code.
+* **How to reproduce locally**: Operations are usually reproducible using corresponding `./frb_internal something` commands shown in CI.
+* **Automatic fix commands**: For many `./frb_internal` commands, there is a `--fix` option which tries to automatically fix everything.
+
+## Tips for development
+
+### The `./frb_internal`
 
 The `./frb_internal whatever-command` (or `./frb_internal.bat`) delegates to the `./tools/frb_internal` dart package.
 It contains all scripts to work on flutter_rust_bridge development.
 It as a similar role as [justfile](https://github.com/casey/just/blob/master/justfile), makefile, etc.
-For example, `./frb_internal precommit --fast` (or `--slow`) runs code generator, formatter, etc for you.
+For example, `./frb_internal precommit --mode fast` (or `--mode slow`) runs code generator, formatter, etc for you.
 
-## The `just codegen`
+### The `just codegen`
 
 To run the `flutter_rust_bridge_codegen`, but using the local code (instead of a released version),
 please replace it with `just codegen`.
 
-## Reproduce CI failures
-
-As is seen in [the CI workflow definitions](https://github.com/fzyzcjy/flutter_rust_bridge/blob/master/.github/workflows/ci.yaml),
-most CI jobs are nothing but a `./frb_internal some-command`.
-Therefore, to debug and fix CI failures, you can often run that command locally.
-
-## Check the dumped data
+### Check the dumped data
 
 With `dump_all: true` in the config (which is already done for `frb_example/pure_dart`),
 many things are dumped into the `rust/target/frb_dump/` folder,
 which is often helpful for debugging the codegen.
 For example, you can check the effective configuration, the IR (intermediate representation),
 the generated spec, the generated code, etc.
 
-## Use `frb_example/dart_minimal` as testing bed
+### Use `frb_example/dart_minimal` as testing bed
 
 A lot of tests reside in `frb_example/pure_dart`, thus it is a bit big and slow to compile and examine.
 Therefore, I (personally) often use `frb_example/dart_minimal` as a testing bed.

website/docs/guides/how-to/report-error.md

@@ -1,6 +1,26 @@
 # Report errors
 
-To configure to report errors to your backend, in addition to telling Dart, we can simply use a [custom Handler](../custom/rust):
+## At Dart side
+
+Just follow Flutter's guide, or your error backend's guide, to setup the error handling.
+
+It will catch all pure Dart errors, as well as all Rust errors that are propagated to Dart.
+
+## Ensure Rust stack traces
+
+If you are not seeing Rust stack traces, please refer to [this page](stack-trace) to setup.
+
+## (Optional) At Rust side
+
+:::info
+I personally do this because my Rust code has symbols stripped.
+Thus, to see the Rust stack traces, I have to integrate the error reporting SDK at this layer,
+to let it capture enough information for symbolication.
+
+For normal users, try to do the Dart side setup first, and only do this if that does not give you enough information.
+:::
+
+We can simply use a [custom Handler](../custom/rust):
 
 ```rust
 pub struct MyErrorHandler(ReportDartErrorHandler);

website/docs/index.md

@@ -92,6 +92,7 @@ This package is [officially Flutter Favorite](https://docs.flutter.dev/packages-
 * **Easy to code-review & convince yourself**: This package simply simulates how humans write boilerplate code. If you want to convince yourself (or your team) that it is safe, there is not much code to track.
 * **Fast**: It is only a thin (though feature-rich) wrapper, benchmarked on CI, and even has multiple codecs for best performance under different workloads.
 * **Hackable**: If (for whatever reason) you want to hack the source, there are contributor guides, code is modular, and the execution logic is intuitive.
+* **Ask questions**: Feel free to ask questions in the issue tracker, and I usually reply within hours (if not sleeping).
 
 ### Why Flutter + Rust?