This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory.git
The following commit(s) were added to refs/heads/main by this push:
new 7abce8da1 docs: update agents.md (#3162)
7abce8da1 is described below
commit 7abce8da18a3124dad20c2916db6506235d7b0fe
Author: Shawn Yang <[email protected]>
AuthorDate: Mon Jan 19 19:50:28 2026 +0800
docs: update agents.md (#3162)
## Why?
## What does this PR do?
## Related issues
## Does this PR introduce any user-facing change?
- [ ] Does this PR introduce any public API change?
- [ ] Does this PR introduce any binary protocol compatibility change?
## Benchmark
---
AGENTS.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 49 insertions(+), 6 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 6e7f83f04..db1a45d7b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,11 +12,19 @@ While working on Fory, please remember:
- **Focused Testing**: Only add tests that verify internal behaviors or fix
specific bugs; don't create unnecessary tests unless requested.
- **Git-Tracked Files**: When reading code, skip all files not tracked by git
by default unless generated by yourself.
- **Cross-Language Consistency**: Maintain consistency across language
implementations while respecting language-specific idioms.
-- **Graalvm Support using fory codegen**: For graalvm, please use `fory
codegen` to generate the serializer when building graalvm native image, do not
use graallvm reflect-related configuration unless for JDK `proxy`.
+- **GraalVM support using fory codegen**: For GraalVM, use `fory codegen` to
generate the serializer when building a native image. Do not use GraalVM
reflect-related configuration unless for JDK `proxy`.
- **Xlang Type System**: Java `native mode(xlang=false)` shares same type
systems between type id from `Types.BOOL~Types.STRING` with `xlang
mode(xlang=true)`, but for other types, java `native mode` has different type
ids.
- **Remote git repository**: `[email protected]:apache/fory.git` is remote
repository, do not use other remote repository when you want to check code
under `main` branch.
- **Contributor git repository**: A contributor should fork the
`[email protected]:apache/fory.git` repo, and git push the code changes into
their forked repo, then create a pull request from the branch in their forked
repo into `[email protected]:apache/fory.git`.
+## Documentation Sources and Change Rules
+
+- **Primary references**: `README.md`, `CONTRIBUTING.md`,
`docs/guide/DEVELOPMENT.md`, and language guides under `docs/guide/`.
+- **Protocol changes**: Read and update the relevant specs in
`docs/specification/**` and align cross-language tests.
+- **Docs publishing**: Updates under `docs/guide/` and `docs/benchmarks/` are
synced to https://github.com/apache/fory-site; other website content should be
changed in that repo.
+- **Debugging docs**: C++ debugging guidance lives in `docs/cpp_debug.md`.
+- **Conflicts**: If instructions conflict, follow the most specific module
docs and call out the conflict in your response.
+
## Build and Development Commands
### Java Development
@@ -24,6 +32,7 @@ While working on Fory, please remember:
- All maven commands must be executed within the `java` directory.
- All changes to `java` must pass the code style check and tests.
- Fory java needs JDK `17+` installed.
+- Modules target different bytecode levels (fory-core Java 8, fory-format Java
11); avoid using newer APIs in those modules.
- Use '.\*' form of import is not allowed.
```bash
@@ -56,7 +65,8 @@ mvn -T16 test -Dtest=org.apache.fory.TestClass#testMethod
- All commands must be executed within the `cpp` directory.
- Fory c++ use c++ 17, you must not use features from higher version of C++.
-- Whnen you updated the code, use `clang-format` to update the code
+- Bazel uses bzlmod (`MODULE.bazel`); prefer Bazel 8+.
+- When you updated the code, use `clang-format` to update the code
- When invoking a method that returns `Result`, always use `FORY_TRY` unless
in a control flow context.
- Wrap error checks with `FORY_PREDICT_FALSE` for branch prediction
optimization.
- Continue on error for trivial errors; only return early for critical errors
like buffer overflow.
@@ -169,9 +179,9 @@ FORY_GO_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn test
-Dtest=org.apache.fory.xla
- All cargo commands must be executed within the `rust` directory.
- All changes to `rust` must pass the clippy check and tests.
-- You must set `RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1` when debuging rust
tests to get backtrace.
-- You must add `-- --nocapture` to cargo test command when debuging tests.
-- You must not set `FORY_PANIC_ON_ERROR=1` when runing all rust tests to check
whether all tests pass, some tests will check Error content, which will fail if
error just panic.
+- You must set `RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1` when debugging rust
tests to get backtrace.
+- You must add `-- --nocapture` to cargo test command when debugging tests.
+- You must not set `FORY_PANIC_ON_ERROR=1` when running all rust tests to
check whether all tests pass, some tests will check Error content, which will
fail if error just panic.
```bash
# Check code
@@ -313,6 +323,7 @@ cd $it_dir/cpython_benchmark && pip install -r
requirements.txt && python benchm
- **API Documentation**: When updating important public APIs, update
documentation under `docs/`.
- **Protocol Specifications**: `docs/specification/**` contains Fory protocol
specifications. Read these documents carefully before making protocol changes.
- **User Guides**: `docs/guide/**` contains user guides for different features
and languages.
+- **Repo-wide formatting**: `bash ci/format.sh --all` runs format/lint across
languages.
## Repository Structure Understanding
@@ -329,6 +340,9 @@ The `origin` points to forked repository instead of the
official repository.
- `docs/specification/`: Protocol specifications (critical for understanding)
- `docs/guide/`: User guides and development guides
- `docs/benchmarks/`: Performance benchmarks documentation
+- **`benchmarks/`**: Benchmark suites and harnesses
+- **`examples/`**: Usage examples and sample code
+- **`compiler/`**: Code generation and compiler-related utilities
- **Language Implementations**:
- `java/`: Java implementation (maven-based, multi-module)
@@ -349,7 +363,9 @@ The `origin` points to forked repository instead of the
official repository.
- **Build Configuration**:
- `BUILD`, `WORKSPACE`: Bazel configuration
- `.bazelrc`, `.bazelversion`: Bazel settings
+ - `MODULE.bazel`: Bazel bzlmod dependency management
- Various `pom.xml`, `package.json`, `Cargo.toml`, etc.
+- **`licenses/`**: Third-party license reports and metadata
### Important Files
@@ -359,6 +375,8 @@ The `origin` points to forked repository instead of the
official repository.
- **`README.md`**: Project overview and quick start
- **`.gitignore`**: Git ignore patterns (includes build dirs)
- **`licenserc.toml`**: License header configuration
+- **`docs/guide/DEVELOPMENT.md`**: Environment setup and build notes
+- **`docs/cpp_debug.md`**: C++ debugging guide
## Architecture Overview
@@ -521,11 +539,16 @@ Fory rust provides macro-based serialization and
deserialization. Fory rust cons
- **Endianness**: Handle byte order correctly for cross-platform compatibility
- **Version Compatibility**: Maintain backward compatibility when possible
+### Security and Compatibility
+
+- **Class registration**: Keep class registration enabled unless explicitly
requested; use custom class checkers or policies if disabling.
+- **Schema evolution**: Prefer schema-consistent mode unless compatibility is
required; update compatibility tests when changing schema rules.
+
### Testing Strategy
- **Unit Tests**: Focus on internal behavior verification
- **Integration Tests**: Use `integration_tests/` for cross-language
compatibility
-- **Langauge alignment and Protocol Compatibility**: Executing
`test_cross_language.py` for language and protocol alignment
+- **Language alignment and protocol compatibility**: Run
`org.apache.fory.xlang.CPPXlangTest`, `org.apache.fory.xlang.RustXlangTest`,
`org.apache.fory.xlang.GoXlangTest`, and
`org.apache.fory.xlang.PythonXlangTest` when changing xlang or type mapping
behavior
- **Performance Tests**: Include benchmarks for performance-critical changes
### Documentation Requirements
@@ -571,6 +594,21 @@ Fory rust provides macro-based serialization and
deserialization. Fory rust cons
- **Dependency Issues**: Check version compatibility
- **Bazel Issues**: Use `bazel clean --expunge` for deep cleaning
+### Language-Specific Debugging
+
+- **Java**: Set `FORY_CODE_DIR` to dump generated code;
`ENABLE_FORY_GENERATED_CLASS_UNIQUE_ID=false` keeps stable generated class
names.
+- **Python**: Use `cython --cplus -a pyfory/serialization.pyx` for annotated
output; `FORY_DEBUG=true python setup.py build_ext --inplace` for debug builds.
+- **C++**: See `docs/cpp_debug.md`; generate `compile_commands.json` with
`bazel run :refresh_compile_commands`.
+- **Crash debugging**: For macOS core dump setup, follow `CONTRIBUTING.md`.
+
+### Profiling
+
+- **C++**: DTrace-based stack sampling is documented in `CONTRIBUTING.md`.
+
+## IDE Notes
+
+- **IntelliJ IDEA**: Java modules target different bytecode levels (Java
8/11). Use a JDK 11+ project SDK and disable `--release` if it blocks
`sun.misc.Unsafe` access (see `CONTRIBUTING.md`).
+
## CI/CD Understanding
### GitHub Actions Workflows
@@ -613,6 +651,11 @@ Common CI failures and fixes:
- **C++ Build Errors**: Check for missing dependencies or header includes
- **Test Failures**: Run tests locally to reproduce and fix
+## PR and Benchmark Expectations
+
+- **PR titles**: Follow Conventional Commits; CI uses
`.github/workflows/pr-lint.yml` to enforce naming.
+- **Performance changes**: Use the `perf` type and include benchmark data (see
`benchmarks/java_benchmark/README.md`).
+
## Commit Message Format
Use conventional commits with language scope:
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
