Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

Clarify DataConverter vs PayloadConverter in data-handling docs for core-based SDKs

已关闭
  • 哪里不对？
#86 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 2 天内回复

还没有人认领这个 Issue。

评估

难度
3/5
预计耗时
1-2 天
新手友好度
78/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
冷清
技术栈
csharp, python, typescript
领域
documentation

调研方向

从 references/dotnet/data-handling.md、references/python/data-handling.md 和 references/typescript/data-handling.md 中的 Overview 和 default converter 部分开始。将它们的术语和示例与未更改的 Go 和 Java 文件进行比较，然后验证每个更新后的文件都解释了三层模型，包含 Go/Java 的区别，并保持范围外的文件不变。

由索引模型根据 Issue 内容生成。

描述

Background

The current data-handling.md overviews in references/dotnet, references/python, and references/typescript treat "data converter" and "payload converter" as if they were the same thing. For example:

"The .NET SDK uses data converters to serialize/deserialize workflow inputs, outputs, and activity parameters."

This is technically imprecise for the core-based SDKs (.NET, Python, TypeScript, Ruby, Rust), where a DataConverter is a composite of three sub-components:

  • PayloadConverter — converts values ↔ bytes (this is what actually performs serialization)
  • PayloadCodec — bytes ↔ bytes transformation (e.g. encryption, compression)
  • FailureConverter — converts exceptions ↔ serialized failures

This is distinct from Go and Java, where DataConverter is the serialization interface (methods like ToPayload/FromPayload). In those SDKs, DataConverter plays the role that PayloadConverter plays in the core-based SDKs, and codecs are layered separately via CodecDataConverter.

Because developers (and AI skills using these docs) naturally assume "data conversion" works identically across SDKs, the current framing causes confusion. The Go and Java overviews are already accurate; the three core-based SDKs need updates.

See reviewer context: https://github.com/temporalio/skill-temporal-developer/pull/39#discussion_r... and the canonical description in https://github.com/temporalio/sdk-dotnet?tab=readme-ov-file#data-conversion.

Scope

Update these three files, applying the same depth of treatment to each:

  • references/dotnet/data-handling.md
  • references/python/data-handling.md
  • references/typescript/data-handling.md

Do not change references/go/data-handling.md or references/java/data-handling.md — their current framing is accurate for those SDKs.

Detailed changes per file

For each of the three files above:

1. Rewrite the Overview section

Introduce the three-layer model explicitly. Suggested structure:

The SDK uses a DataConverter to move values between the SDK and the Temporal Service. A DataConverter is a composite of three sub-components:

  • PayloadConverter — serializes values to/from Payload bytes (the default handles null, byte arrays, Protobuf messages, and JSON-serializable types).
  • PayloadCodec — transforms payload bytes (e.g. for encryption or compression).
  • FailureConverter — serializes exceptions/errors to/from Temporal Failure protobufs.

Most customization happens at the PayloadConverter layer. Encryption and compression belong in a PayloadCodec. Custom exception serialization belongs in a FailureConverter.

Adjust wording per-SDK to match idiomatic terms (e.g., Python uses failure_converter, TypeScript uses failureConverter, .NET uses FailureConverter).

2. Rename "Default Data Converter" → "Default Payload Converter"

The existing section that lists supported types (null, byte[], Protobuf, JSON, etc.) is describing what the default payload converter supports, not the DataConverter as a whole. Rename the section and adjust the leading sentence accordingly.

3. Review code examples

Make sure customization examples show the three-layer structure clearly — e.g., that overriding serialization means replacing the PayloadConverter inside DataConverter.Default, not replacing the DataConverter itself. (The current .NET example is already correct here; verify Python and TypeScript.)

4. Cross-reference

Add a short note in each updated overview that Go and Java use a different model (their DataConverter is the serialization interface) so readers don't transfer assumptions. One sentence is enough; avoid going into detail.

Out of scope

  • Go and Java data-handling.md files.
  • Changes to the actual SDK code or sample repos.
  • The core/data-handling.md file (if it exists) — to be reviewed separately.

Acceptance criteria

  • Overviews in .NET, Python, and TypeScript data-handling.md files describe DataConverter as the three-layer composite, with PayloadConverter identified as the serialization layer.
  • "Default Data Converter" → "Default Payload Converter" rename applied where the section describes payload-type support.
  • Each of the three files has a one-line note that Go/Java use a different model.
  • Go and Java files are unchanged.
  • Code examples remain accurate and compile-ready.
主要语言
没有语言数据
星标
230
派生
31
平均合并
1 天 18 小时
30 天内合并 PR
21

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

temporalio/skill-temporal-developer 的其他 Issue

查看 temporalio/skill-temporal-developer 的全部 Issue

相似的 Issue

更多 Documentation Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。