dagger-design-proposals

Dagger 设计提案

编写 Dagger 功能设计提案的指南。

编写前

务必先调研：

1. 查阅相关内部文档，例如 internal-docs/dagger-codegen.md，了解背景
2. 查看 Dagger 代码库中的相关代码：
   • GraphQL schema：core/schema/*.go
   • CLI 命令：cmd/dagger/*.go
   • 核心类型：core/*.go
3. 对于公共 API 或工作区提案，请阅读 internal-docs/version-gating.md
4. 提出新方案前，先了解现有模式

结构

# Part N: Title

*Builds on [Part N-1: Title](link)*

## Table of Contents
- [Problem](#problem)
- [Solution](#solution)
- [Core Concept](#core-concept)
- [CLI](#cli)
- [Status](#status)

## Problem

Numbered, concise limitations:

1. **Short title** - One sentence explanation.
2. **Short title** - One sentence explanation.

## Solution

One paragraph summary.

## Core Concept

GraphQL type definitions with inline docstrings:

```graphql
"""
Type description here.
"""
type Example {
  """Method description."""
  method(arg: String!): Result!
}
```

Go for implementation examples:

```go
func New(ws dagger.Workspace) *Example {
    // ...
}
```

## CLI

Real command examples:

```bash
$ dagger command --flag
OUTPUT
```

## Status

One line.

---

- Previous: [Part N-1](link)
- Next: [Part N+1](link) or "Part N+1: Title (coming soon)"

风格

• 简洁 - 相信读者的理解能力，删去冗余内容。
• 表格 - 使用表格进行比较。
• API 使用 GraphQL - 使用类型定义，而非 Go 接口。
• 实现使用 Go - 通过示例展示模块如何使用 API。
• 真实示例 - 使用 go-toolchain、node-toolchain，而非抽象的 Foo/Bar。
• 少即是多 - 有人提出质疑时，删去相应章节。

应避免的内容

• 单独的“方法”章节（使用 GraphQL 文档字符串）
• 除非确有价值，否则不要写“设计理由”章节
• 并非真正阻碍工作的“待解决问题”
• 用 Go 编写类型定义（应使用 GraphQL）
• 可能造成混淆的布局示例
• 过度解释

流程

1. 以 Gist 为准 - 尽早发布，并在 Gist 中迭代
2. 串联各部分 - 在底部添加“上一篇/下一篇”链接，并在顶部标注“基于”
3. 每部分都可独立阅读 - 同时建立在前文基础上
4. 快速迭代 - 根据用户反馈进行修改

与用户迭代

如果你有需要澄清的问题或备注：

1. 先列出 - 以高层级编号列表列出所有问题和备注
2. 逐项讨论 - 一次讨论一项，并等待用户回复
3. 不要一股脑列出 - 切勿一次性提供所有问题的完整细节

代码库参考

编写提案时，请引用 Dagger 中的实际代码：

主题	位置
GraphQL schema 定义	core/schema/*.go
CLI 命令	cmd/dagger/*.go
核心类型（Directory、File 等）	core/*.go
引擎内部实现	engine/*.go
SDK 代码生成	internal-docs/dagger-codegen.md、cmd/codegen/*.go
API 版本门控	internal-docs/version-gating.md、core/schema/*.go

示例：在提出 Workspace.findUp 之前，先了解 Host.findUp 的工作方式：

# Find the schema definition
grep -r "findUp" core/schema/host.go

# Find the implementation
grep -r "FindUp" core/host.go

发布

# Create new gist
gh gist create file.md --desc "Dagger Design: Part N - Title" --public

# Update existing gist
gh gist edit GIST_ID file.md

# Post changelog comment (always do this after updates)
gh api --method POST /gists/GIST_ID/comments -f body="## Changelog
- Change 1
- Change 2"

对 Gist 进行重大更新后，务必发布一条变更日志评论。

相关技能

查找其他可能有助于调研的 Dagger 技能：

• engine-debugging - 引擎调试工作流、跟踪检查、缓存快照
• internal-docs/dagger-codegen.md - SDK 代码生成、模板、绑定
• internal-docs/version-gating.md - schema 视图和公共 API 版本门控
• internal-docs/ - 缓存和引擎实现参考