开源项目根目录文档指南

这篇文章是对项目根目录存放的文件的介绍。方便刚进入开源社区的同志们快速了解开源项目，也方便准备发布自己的开源项目的同志们按需选择。

下面是各个文件的介绍和简单示例。

总览表

文件	一句话作用	必备度
README.md	项目门面：是什么、怎么装、怎么用	必选
LICENSE	授权条款，法律效力的核心文件	必选
CONTRIBUTING.md	外部贡献者参与流程	强烈建议
CODE_OF_CONDUCT.md	社区行为准则与违规处理	建议
SECURITY.md	漏洞私下披露通道与支持版本	建议
SUPPORT.md	用户求助渠道分流	可选
INSTALL.md	详细安装/部署说明	可选
ARCHITECTURE.md	设计意图、分层与关键决策	建议
TESTING.md	测试策略、命令与准入门槛	建议
RELEASING.md	发版流程与回滚预案	建议
PORTING.md	移植到新平台/架构的清单	可选
ROADMAP.md	方向性规划与优先级	可选
CHANGELOG.md	版本间变更记录	强烈建议
GOVERNANCE.md	角色、晋升与决策机制	多人协作建议
COMPLIANCE.md	出口管制、依赖许可、SBOM 等合规约束	企业/受监管场景
AUTHORS.md	作者、贡献者与致谢	可选
CITATION.cff	学术引用元数据	科研类项目
CLA.md	贡献者许可/专利授权条款	企业主导项目
FUNDING.yml	赞助入口配置	可选
AGENTS.md	给 AI 编码代理的仓库级指令	新增，建议
HANDOFF.md	项目/职责交接说明	交接场景
TRADEMARK.md	名称与 Logo 使用政策	有品牌资产时

介绍与操作

README.md

仓库首页渲染的文件，项目介绍与文档、贡献、许可入口。

# flowc — 把 SQL 编译成可执行计划

https://github.com/example/flowc/actions/workflows/ci.yml/badge.svg](...)
https://img.shields.io/badge/license-MIT-green.svg](LICENSE)

## 安装
pipx install flowc

## 快速开始
flowc run query.sql   # 输出 JSON 结果

## 文档
完整文档见 docs/；架构见 ARCHITECTURE.md

## 参与
见 CONTRIBUTING.md，行为准则见 CODE_OF_CONDUCT.md

## 许可
MIT，见 LICENSE

INSTALL.md

README 只放”最省事的一条命令”，多平台、离线、源码编译、排障都下沉到这里。

## 环境要求
Python 3.11+；可选 Docker（沙箱执行模式需要）

## 三种安装方式
1. pip：`pipx install flowc`
2. 源码：`git clone ... && cd flowc && uv sync`
3. 离线：`pip install --no-index --find-links=./wheels flowc`

## 验证
flowc --version && flowc run examples/hello.sql

## 常见问题
- Linux 报缺 libssl：`apt install libssl-dev`

SUPPORT.md

把”提问”这件事分流，避免 Issue 区被使用问题淹没。

提问前请先查 docs/ 并搜索已有 issue。

| 你想做的事 | 去哪里 |
|---|---|
| 用法咨询 | GitHub Discussions |
| 报 Bug | Issue |
| 安全漏洞 | 请勿开 issue，见 SECURITY.md |
| 商业支持/培训 | support@example.org |

响应预期：社区志愿维护，Issue 通常 5 个工作日内回应。

法律与合规

LICENSE

选一个标准许可证（MIT / Apache-2.0 / GPL-3.0），只替换版权行。改写即可能导致授权无效。

MIT License

Copyright (c) 2026 Example Foundation

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...
（以下为完整免责声明，切勿删改）

TRADEMARK.md

代码可以随便用，名字和 Logo 不能随便用。企业项目和基金会项目尤其需要。

"FlowC" 名称与 Logo 归 Example 基金会所有，本项目代码采用 MIT 许可，
但 MIT 不包含商标授权。

✅ 允许：文字表述"基于 FlowC 构建"；文档中使用未修改的 Logo 并注明归属
❌ 禁止：将 FlowC 用作自有产品名或域名；修改 Logo；暗示官方背书或认证

疑问请联系 trademark@example.org。

CLA.md

贡献者许可协议，核心是拿到版权许可和专利许可，让项目未来能换许可证或商业化。轻量替代方案是 DCO（git commit -s 签署）。

## 贡献者许可协议（个人版 · 摘要）
1. 版权许可：你以本项目许可证（MIT）授予我们永久、全球、可再许可的权利
2. 专利许可：就你的贡献所必然涵盖的专利，授予免费用许可
3. 你保证有权提交该贡献；贡献按"原样"提供，不含任何担保

签署方式：首次 PR 时由 CLA 助手引导勾选；单次提交可用 DCO：
git commit -s -m "feat: 支持窗口函数"

COMPLIANCE.md

项目的合规要求，让贡献者在提 PR 时就知道红线在哪。

- 依赖许可：运行时依赖仅限 MIT/BSD/Apache-2.0；引入 GPL 需 TSC 书面批准
- SBOM：每次发版生成 CycloneDX 清单，随 Release 附件发布
- 出口管制：含加密功能，分类 EAR99
- 个人信息：日志禁止记录 PII；默认关闭遥测
- 审计：每季度跑 pip-audit 并复核依赖清单

CITATION.cff

机器可读的引用元数据，给学术界用。GitHub 会直接显示”Cite this repository”按钮。

cff-version: 1.2.0
title: "flowc: 一个轻量级 SQL 编译器"
message: "若使用本软件，请按如下方式引用。"
type: software
version: 1.4.0
license: MIT
authors:
  - family-names: "张"
    given-names: "岚"
    orcid: "https://orcid.org/0000-0002-1825-0097"
repository-code: "https://github.com/example/flowc"

社区与治理

CONTRIBUTING.md

减少由贡献产生的摩擦。重点写清分支命名、提交规范、测试要求、评审标准、大改动先讨论。

## 流程
1. Fork 后建分支：`feat/window-func`
2. `uv sync` 装依赖；写代码同时写测试
3. 提交前必须通过：`uv run pytest`
4. 提交信息用 Conventional Commits：`feat: 支持 ROW_NUMBER`
5. 开 PR：填模板、关联 issue、签署 CLA

小改动可直接 PR；架构类改动请先开 issue 讨论再动手。

CODE_OF_CONDUCT.md

一般直接采用 Contributor Covenant，只需替换举报邮箱，不要自行发挥。

## 我们的承诺
不论年龄、性别、国籍、经验水平，承诺让每个人都能无骚扰地参与。

## 不可接受行为
- 性化的语言或图像、挑衅或侮辱性评论
- 公开或私下的骚扰
- 未经明确许可发布他人隐私信息

## 举报与处理
conduct@example.org，48 小时内受理并对举报人保密。
处理分级：私下纠正 → 公开警告 → 临时封禁 → 永久封禁。
（基于 Contributor Covenant 2.1）

GOVERNANCE.md

回答三个问题：谁说了算、怎么当上说了算的人、分歧怎么裁决。项目超过 3 个活跃维护者就该写。

## 角色
用户 → 贡献者 → Committer（有合并权）→ 核心团队 TSC（5 人，每年改选 2/3）

## 决策
默认懒共识：提案公示 72 小时无人反对即通过；
有争议则升级为投票，简单多数通过；平票由 TSC 主席决定。

## 晋升
近 6 个月 ≥10 个被合并 PR + 现任 Committer 提名 + TSC 投票过半。

## 记录
所有重大决策存入 docs/decisions/（ADR 格式）。

AUTHORS.md

区分核心维护者和贡献者。

# 作者

## 核心维护者
- 张岚 <lan@example.org> — 创始人、TSC 成员
- 李默 <mo@example.org> — Committer，负责优化器

## 贡献者
感谢所有贡献者，完整名单见 GitHub Contributors 图表。

## 致谢
设计受 SQLite 与 DuckDB 启发；初始原型来自 2024 年内部 Hackathon。

FUNDING.yml

放在 .github/FUNDING.yml，GitHub 会在仓库页显示”Sponsor”按钮。

# .github/FUNDING.yml
github: ["lanzhang"]
open_collective: flowc
custom: ["https://example.org/donate"]

工程与流程

ARCHITECTURE.md

解释为什么这么设计，而不是复述代码结构。核心是分层 + 关键决策 + 硬约束。

## 目标
把 SQL 编译成可执行计划，优先保证可测试性与可移植性，而非极致性能。

## 分层
parser → analyzer → optimizer → codegen → runtime

## 关键决策
- ADR-003：采用 Volcano 迭代模型而非生成机器码（可移植性优先于峰值性能）
- 层间传递不可变 AST，禁止跨层共享可变状态

## 硬约束
- core 层不得调用任何 OS 相关 API，I/O 一律走 platform 层

TESTING.md

写清跑哪些命令、覆盖多少算达标、什么情况下测试必须新增。

## 层级
单元测试（pytest，行覆盖 ≥80%）/ 集成测试（docker-compose 起依赖）/ 端到端（examples/）

## 命令
uv run pytest -q                              # 单元 + 集成
uv run pytest -m e2e                          # 端到端（需 Docker）
uv run pytest --cov=flowc --cov-fail-under=80 # 覆盖率门禁

## 规矩
- 修 bug 必须先写一个能复现失败的测试
- 禁止用 sleep 等待，改用轮询
- 不稳定的测试 24 小时内修不好就标记跳过并开 issue

RELEASING.md

版本发布规范。

版本规则：语义化版本 MAJOR.MINOR.PATCH，预发布形如 1.6.0-rc.1

1. `git switch -c release/1.6.0`
2. 把 CHANGELOG 的 Unreleased 改为 1.6.0 并填日期；更新 __version__
3. `git tag -a v1.6.0 -m "v1.6.0" && git push origin v1.6.0`
4. CI 自动构建 wheel、生成 SBOM、发布到 PyPI 与 GitHub Release
5. 回滚：PyPI 撤回需 TSC 两人批准，随后补发 patch 版本

PORTING.md

面向搬迁项目的人，给出必须实现的接口清单和验收标准。

## 分层原则
core（纯 C99，无平台依赖）/ platform（平台抽象）/ binding（语言绑定）

## 需实现的接口（platform/port.h）
port_fs_read / port_fs_write / port_thread_create / port_mutex_lock / port_now_ms

## 移植清单
1. 新建 platform/<os>/ 实现上述接口
2. `make PORT=<os>` 且通过 test/port 测试套件
3. 补充 CI 矩阵与文档

已支持：Linux、macOS、Windows、FreeRTOS

ROADMAP.md

介绍项目的发展方向。用 Now / Next / Later 三档最清晰，并明确”已拒绝”以减少重复讨论。

## Now（本季度）
- v1.5 增量编译缓存

## Next（下季度）
- 插件 API 稳定化
- Windows ARM64 支持

## Later（探索中，不承诺时间）
- WASM 运行时、分布式构建

## 明确不做
- 图形化 IDE（超出项目范围）

CHANGELOG.md

项目升级迭代记录。用 Keep a Changelog 格式，破坏性变更必须显式标注。

# 更新日志
遵循语义化版本，格式参考 Keep a Changelog。

## [Unreleased]
### Added
- 实验性 `--watch` 模式

## [1.4.0] - 2026-08-20
### Added
- 支持窗口函数 ROW_NUMBER

### Fixed
- 修复空输入时崩溃 (#298)

### Changed
- **破坏性**：`flowc run` 默认输出改为 JSON，需兼容旧行为请加 `--format=text`

SECURITY.md

提供非公开报告渠道，并声明哪些版本仍在维护。

## 支持版本
| 版本 | 是否支持 |
| 1.4.x | ✅ |
| ≤ 1.3 | ❌ |

## 报告漏洞
邮件 security@example.org（PGP 指纹 4AEE…），或用 GitHub 私有漏洞报告。
请勿公开开 issue。

## 响应承诺
72 小时内确认；修复后协调披露时间；严重漏洞 7 天内发布补丁版本。

AI 协作与交接

AGENTS.md

给 AI agent的项目介绍。内容应是可执行的命令和硬禁令，而不是泛泛而谈的风格描述。

# AGENTS.md
本仓库是 Python CLI 工具，Python 3.11+，包管理器 uv。

- 装依赖：uv sync
- 跑测试：uv run pytest -q（提交前必须通过）
- 格式与 lint：uv run ruff check . && uv run ruff format .
- 禁止：修改 LICENSE；直接 push main；新增运行时依赖前先开 issue 讨论
- 提交信息用 Conventional Commits；PR 需关联 issue 并更新 CHANGELOG.md
- 不确定时先提问，不要猜测业务规则

HANDOFF.md

维护者离职、项目易主、团队轮换时用。

## 交接概览
交接人：张岚 → 接手人：李默；交接期：2026-09-16 至 2026-10-16

## 当前状态
版本 1.4.0，上周刚发版，无待发布热修。
在办：PR #312（缓存重构，等压测报告）

## 资产与权限
- 代码仓库 / PyPI 令牌（1Password "PyPI"）/ CI 密钥 / 域名 DNS 控制台

## 风险与待办
- 依赖 X 已 EOL，须在下季度前替换

## 联系人
基础设施：@ops；安全接口人：@sec

欢迎来到我的博客!