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 37b5ce179 docs: move development guide to docs root (#3591)
37b5ce179 is described below
commit 37b5ce17922b02e99d8e37410c07ff01d7e2dd49
Author: Shawn Yang <[email protected]>
AuthorDate: Mon Apr 20 20:08:42 2026 +0800
docs: move development guide to docs root (#3591)
## Why?
## What does this PR do?
## Related issues
## AI Contribution Checklist
- [ ] Substantial AI assistance was used in this PR: `yes` / `no`
- [ ] If `yes`, I included a completed [AI Contribution
Checklist](https://github.com/apache/fory/blob/main/AI_POLICY.md#9-contributor-checklist-for-ai-assisted-prs)
in this PR description and the required `AI Usage Disclosure`.
- [ ] If `yes`, my PR description includes the required `ai_review`
summary and screenshot evidence of the final clean AI review results
from both fresh reviewers on the current PR diff or current HEAD after
the latest code changes.
## 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/docs-and-formatting.md | 4 +-
.agents/repo-reference.md | 2 +-
.github/sync.yml | 2 +
AGENTS.md | 4 +-
CONTRIBUTING.md | 6 +-
README.md | 148 +++++++++++++++++++++++++++++++++++++---
docs/{guide => }/DEVELOPMENT.md | 0
7 files changed, 150 insertions(+), 16 deletions(-)
diff --git a/.agents/docs-and-formatting.md b/.agents/docs-and-formatting.md
index 80fb6c6d5..809b2eda3 100644
--- a/.agents/docs-and-formatting.md
+++ b/.agents/docs-and-formatting.md
@@ -6,7 +6,7 @@ Load this file when changing documentation, public APIs,
protocol specs, benchma
- `README.md`
- `CONTRIBUTING.md`
-- `docs/guide/DEVELOPMENT.md`
+- `docs/DEVELOPMENT.md`
- language guides under `docs/guide/`
- `docs/specification/**`
- `docs/compiler/**`
@@ -18,7 +18,7 @@ Load this file when changing documentation, public APIs,
protocol specs, benchma
- Keep examples working and aligned with the current API and protocol behavior.
- Provide or update working examples when adding new features or materially
changing workflows.
- Add migration guidance when a change is breaking or materially changes
workflow.
-- Updates under `docs/guide/` and `docs/benchmarks/` are synced to
`apache/fory-site`; other website content should be changed there instead of
this repo.
+- `docs/DEVELOPMENT.md` plus updates under `docs/guide/` and
`docs/benchmarks/` are synced to `apache/fory-site`; other website content
should be changed there instead of this repo.
- When benchmark logic, scripts, config, or compared serializers change, rerun
the relevant benchmarks and refresh the report and plots under
`docs/benchmarks/**`.
- Never manually edit generated code for compiler or IDL outputs; regenerate
from the source schema or IDL.
diff --git a/.agents/repo-reference.md b/.agents/repo-reference.md
index 2e2d55de7..8df1d30b8 100644
--- a/.agents/repo-reference.md
+++ b/.agents/repo-reference.md
@@ -19,7 +19,7 @@ Load this file when you need repo layout, protocol context,
compiler guidance, o
- `CLAUDE.md`: compatibility shim that points back to `AGENTS.md`
- `README.md`: project overview and quick start
- `CONTRIBUTING.md`: contributor workflow and environment notes
-- `docs/guide/DEVELOPMENT.md`: development setup and build notes
+- `docs/DEVELOPMENT.md`: development setup and build notes
- `docs/cpp_debug.md`: C++ debugging guidance
- `licenserc.toml`: license header configuration
diff --git a/.github/sync.yml b/.github/sync.yml
index 8901cafdc..43f5a0049 100644
--- a/.github/sync.yml
+++ b/.github/sync.yml
@@ -16,6 +16,8 @@
# under the License.
apache/fory-site@main:
+ - source: docs/DEVELOPMENT.md
+ dest: docs/community/DEVELOPMENT.md
- source: docs/guide/
dest: docs/guide/
- source: docs/specification/
diff --git a/AGENTS.md b/AGENTS.md
index 544766741..5ac63b639 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -51,10 +51,10 @@ This is the entry point for AI guidance in Apache Fory.
Read this file first, th
## Source of Truth
-- Primary references: `README.md`, `CONTRIBUTING.md`,
`docs/guide/DEVELOPMENT.md`, and language guides under `docs/guide/`.
+- Primary references: `README.md`, `CONTRIBUTING.md`, `docs/DEVELOPMENT.md`,
and language guides under `docs/guide/`.
- Protocol changes require reading and updating the relevant specs in
`docs/specification/**` and aligning the relevant cross-language tests.
- If instructions conflict, follow the most specific module docs and call out
the conflict.
-- Updates under `docs/guide/` and `docs/benchmarks/` are synced to
`apache/fory-site`; other website content belongs there.
+- `docs/DEVELOPMENT.md` plus updates under `docs/guide/` and
`docs/benchmarks/` are synced to `apache/fory-site`; other website content
belongs there.
- When benchmark logic, scripts, configuration, or compared serializers
change, rerun the relevant benchmarks and refresh the artifacts under
`docs/benchmarks/**`.
## Shared Engineering Expectations
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index dd49508c2..2cf1fa02b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -41,7 +41,7 @@ Key points:
## Testing
-For environmental requirements, please check
[DEVELOPMENT.md](./docs/guide/DEVELOPMENT.md).
+For environmental requirements, please check
[DEVELOPMENT.md](./docs/DEVELOPMENT.md).
### Python
@@ -235,10 +235,10 @@ And due to the usage of `sun.misc.Unsafe` API, which is
not visible in Java 11+,
Apache Foryβ’'s website consists of static pages hosted at
https://github.com/apache/fory-site.
-All updates about docs under [guide](docs/guide) and
[benchmarks](docs/benchmarks) will be synced to the site repo automatically.
+Updates to [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md), docs under
[guide](docs/guide), and docs under [benchmarks](docs/benchmarks) will be
synced to the site repo automatically.
If you want write a blog, or update other contents about the website, please
submit PR to the site repo.
## Development
-For more information, please refer to [Development
Guide](https://fory.apache.org/docs/docs/guide/development).
+For more information, please refer to [Development
Guide](./docs/DEVELOPMENT.md).
diff --git a/README.md b/README.md
index ea9a1b5eb..a9e5104fb 100644
--- a/README.md
+++ b/README.md
@@ -212,6 +212,36 @@ Fory C++ supports both CMake and Bazel build systems. See
[C++ Installation Guid
go get github.com/apache/fory/go/fory
```
+**NodeJS/JavaScript**:
+
+```bash
+npm install @apache-fory/core
+```
+
+Optional Node.js string fast-path support:
+
+```bash
+npm install @apache-fory/core @apache-fory/hps
+```
+
+**C#**:
+
+```xml
+<ItemGroup>
+ <PackageReference Include="Apache.Fory" Version="0.17.0" />
+</ItemGroup>
+```
+
+**Dart**:
+
+```yaml
+dependencies:
+ fory: ^0.17.0
+
+dev_dependencies:
+ build_runner: ^2.4.0
+```
+
## Quick Start
This section provides quick examples for getting started with Apache Foryβ’.
For comprehensive guides, see the [Documentation](#documentation).
@@ -342,6 +372,105 @@ int main() {
For detailed C++ usage including collections, smart pointers, and error
handling, see [C++ Guide](docs/guide/cpp).
+#### NodeJS/JavaScript Serialization
+
+JavaScript native mode uses registered schemas to generate fast serializers
for repeated use in browser or Node.js applications.
+
+```ts
+import Fory, { Type } from "@apache-fory/core";
+
+const personType = Type.struct("example.person", {
+ name: Type.string(),
+ age: Type.int32(),
+});
+
+const fory = new Fory();
+const { serialize, deserialize } = fory.register(personType);
+
+const bytes = serialize({
+ name: "chaokunyang",
+ age: 28,
+});
+const person = deserialize(bytes);
+console.log(person.name, person.age); // Output: chaokunyang 28
+```
+
+For detailed JavaScript usage including schema registration, references, and
cross-language support, see [JavaScript Guide](docs/guide/javascript).
+
+#### C# Serialization
+
+C# native mode provides source-generator-backed serialization for registered
.NET types.
+
+```csharp
+using Apache.Fory;
+
+[ForyObject]
+public sealed class Person
+{
+ public long Id { get; set; }
+ public string Name { get; set; } = string.Empty;
+}
+
+Fory fory = Fory.Builder().Build();
+fory.Register<Person>(1);
+
+Person person = new()
+{
+ Id = 1,
+ Name = "chaokunyang",
+};
+
+byte[] bytes = fory.Serialize(person);
+Person result = fory.Deserialize<Person>(bytes);
+Console.WriteLine($"{result.Name} {result.Id}"); // Output: chaokunyang 1
+```
+
+For detailed C# usage including configuration, custom serializers, and
thread-safe runtime options, see [C# Guide](docs/guide/csharp).
+
+#### Dart Serialization
+
+Dart native mode uses generated serializers for fast serialization without
runtime reflection.
+
+```dart
+import 'package:fory/fory.dart';
+
+part 'person.fory.dart';
+
+@ForyStruct()
+class Person {
+ Person();
+
+ String name = '';
+ Int32 age = Int32(0);
+}
+
+void main() {
+ final fory = Fory();
+ PersonFory.register(
+ fory,
+ Person,
+ namespace: 'example',
+ typeName: 'Person',
+ );
+
+ final person = Person()
+ ..name = 'chaokunyang'
+ ..age = Int32(28);
+
+ final bytes = fory.serialize(person);
+ final result = fory.deserialize<Person>(bytes);
+ print('${result.name} ${result.age}');
+}
+```
+
+Generate the companion file before running the program:
+
+```bash
+dart run build_runner build --delete-conflicting-outputs
+```
+
+For detailed Dart usage including code generation, field configuration, and
cross-language guidance, see [Dart Guide](docs/guide/dart).
+
#### Scala Serialization
Scala native mode provides optimized serialization for Scala-specific types
including case classes, collections, and Option types.
@@ -406,7 +535,7 @@ For detailed Kotlin usage including null safety and default
value support, see [
**Only use xlang mode when you need cross-language data exchange.** Xlang mode
adds type metadata overhead for cross-language compatibility and only supports
types that can be mapped across all languages. For single-language use cases,
always prefer native mode for better performance.
-The following examples demonstrate serializing a `Person` object across Java
and Rust. For other languages (Python, Go, JavaScript, etc.), simply set the
language mode to `XLANG` and follow the same pattern.
+The following examples demonstrate serializing a `Person` object across Java
and Rust. For other languages (Python, Go, JavaScript, etc.), simply set the
xlang mode to `true` and follow the same pattern.
**Java**
@@ -419,10 +548,7 @@ public class XlangExample {
public static void main(String[] args) {
// Create Fory instance with XLANG mode
- Fory fory = Fory.builder()
- .withLanguage(Language.XLANG)
- .build();
-
+ Fory fory = Fory.builder().withXlang(true).build();
// Register with cross-language type id/name
fory.register(Person.class, 1);
// fory.register(Person.class, "example.Person");
@@ -447,7 +573,7 @@ struct Person {
}
fn main() -> Result<(), Error> {
- let mut fory = Fory::default();
+ let mut fory = Fory::default().xlang(true);
fory.register::<Person>(1)?;
// fory.register_by_name::<Person>("example.Person")?;
let person = Person {
@@ -582,10 +708,16 @@ For more details on row format, see [Row Format
Specification](docs/specificatio
| **Python** | Python-specific features and usage
| [python](docs/guide/python) | [π
View](https://fory.apache.org/docs/guide/python/) |
| **Rust** | Rust implementation and patterns
| [rust](docs/guide/rust) | [π
View](https://fory.apache.org/docs/guide/rust/) |
| **C++** | C++ implementation and patterns
| [cpp](docs/guide/cpp) | [π
View](https://fory.apache.org/docs/guide/cpp/) |
+| **Go** | Go serialization and runtime usage
| [go](docs/guide/go) | [π
View](https://fory.apache.org/docs/guide/go/) |
+| **JavaScript/NodeJS** | JavaScript and Node.js serialization
guide | [javascript](docs/guide/javascript) | [π
View](https://fory.apache.org/docs/guide/javascript/) |
+| **C#** | C# serialization and .NET usage
| [csharp](docs/guide/csharp) | [π
View](https://fory.apache.org/docs/guide/csharp/) |
+| **Swift** | Swift implementation and patterns
| [swift](docs/guide/swift) | [π
View](https://fory.apache.org/docs/guide/swift/) |
+| **Dart** | Dart serialization and codegen usage
| [dart](docs/guide/dart) | [π
View](https://fory.apache.org/docs/guide/dart/) |
| **Scala** | Scala integration and best practices
| [scala](docs/guide/scala) | [π
View](https://fory.apache.org/docs/guide/scala/) |
+| **Kotlin** | Kotlin integration and type support
| [kotlin](docs/guide/kotlin) | [π
View](https://fory.apache.org/docs/guide/kotlin/) |
| **Cross-Language Serialization** | Multi-language object exchange
| [xlang](docs/guide/xlang) | [π
View](https://fory.apache.org/docs/guide/xlang/) |
| **GraalVM** | Native image support and AOT compilation
| [graalvm-support.md](docs/guide/java/graalvm-support.md) | [π
View](https://fory.apache.org/docs/guide/java/graalvm_support) |
-| **Development** | Building and contributing to Fory
| [DEVELOPMENT.md](docs/guide/DEVELOPMENT.md) | [π
View](https://fory.apache.org/docs/guide/development) |
+| **Development** | Building and contributing to Fory
| [DEVELOPMENT.md](docs/DEVELOPMENT.md) | [π
View](docs/DEVELOPMENT.md) |
### Protocol Specifications
@@ -658,7 +790,7 @@ We welcome contributions! Please read our [Contributing
Guide](CONTRIBUTING.md)
- π§ͺ Add test cases
- π Share benchmarks
-See [Development Guide](docs/guide/DEVELOPMENT.md) for build instructions and
development workflow.
+See [Development Guide](docs/DEVELOPMENT.md) for build instructions and
development workflow.
## License
diff --git a/docs/guide/DEVELOPMENT.md b/docs/DEVELOPMENT.md
similarity index 100%
rename from docs/guide/DEVELOPMENT.md
rename to docs/DEVELOPMENT.md
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
