From 786835c9bc08ee2afc1a351a689ee9d0122209e8 Mon Sep 17 00:00:00 2001 From: Syngnat Date: Tue, 3 Mar 2026 15:49:58 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(contributing):=20=E8=A1=A5?= =?UTF-8?q?=E5=85=85=E4=B8=AD=E8=8B=B1=E6=96=87=E8=B4=A1=E7=8C=AE=E6=8C=87?= =?UTF-8?q?=E5=8D=97=E5=B9=B6=E7=BB=9F=E4=B8=80=20README=20=E5=85=A5?= =?UTF-8?q?=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增英文版 CONTRIBUTING.md 作为正式贡献文档 - 新增中文版 CONTRIBUTING.zh-CN.md 作为中文贡献说明 - 调整 README 和 README.zh-CN 的贡献入口指向对应语言文档 --- CONTRIBUTING.md | 154 ++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.zh-CN.md | 154 ++++++++++++++++++++++++++++++++++++++++++ README.md | 10 +-- README.zh-CN.md | 10 +-- 4 files changed, 318 insertions(+), 10 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.zh-CN.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..561dd32 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,154 @@ +# Contributing Guide + +Thank you for contributing to this project. + +This repository follows a release-first workflow: `main` is the default public branch, while releases are prepared through `release/*` branches. + +--- + +## Branch Model + +- `main`: stable release branch and default branch +- `dev`: day-to-day integration branch for maintainers +- `release/*`: release preparation branches for maintainers +- Recommended branch names for external contributors: + - `fix/*`: bug fixes + - `feature/*`: new features or enhancements + +Maintainer release flow: + +```text +feature/* / fix/* -> dev -> release/* -> main -> tag(vX.Y.Z) +``` + +--- + +## How External Contributors Should Open Pull Requests + +Whether your branch is `fix/*` or `feature/*`, external contributors should **open pull requests directly against `main`**. + +Reasons: + +- `main` is the default branch, so the PR entry point is clearer +- merged contributions are immediately visible on the default branch +- maintainers can handle downstream sync and release preparation in one place + +Recommended flow: + +1. Fork this repository +2. Create a branch in your fork (`fix/*` or `feature/*` is recommended) +3. Make your changes and perform basic self-checks +4. Push the branch to your fork +5. Open a pull request against the `main` branch of this repository + +--- + +## Pull Request Requirements + +Please keep each pull request focused, reviewable, and easy to validate. + +Recommended expectations: + +- one pull request should address one logical change +- use a clear title that explains the purpose +- include the following in the description: + - background and problem statement + - key changes + - impact scope + - validation method +- include screenshots or recordings for UI changes when helpful +- explicitly mention risk and rollback notes for compatibility, data, or build-chain changes + +--- + +## Merge Strategy for Maintainers + +Pull requests merged into `main` should generally use **Squash and merge**. + +Reasons: + +- keeps `main` history clean and linear +- maps each PR to a single commit on `main` +- reduces release, audit, and rollback complexity + +--- + +## Maintainer Sync Rules + +Because external pull requests are merged directly into `main`, maintainers must sync `main` back to development and release branches to avoid branch drift. + +### 1. Sync `main` -> `dev` (required) + +Every change merged into `main` must be synced into `dev`: + +```bash +git checkout dev +git pull +git merge main +git push +``` + +### 2. Create `release/*` from `dev` + +Before a release, create a release branch from `dev`, for example: + +```bash +git checkout dev +git pull +git checkout -b release/v0.6.0 +git push -u origin release/v0.6.0 +``` + +### 3. Release from `release/*` back to `main` + +When release preparation is complete, merge the release branch back into `main` and create a tag: + +```bash +git checkout main +git pull +git merge release/v0.6.0 +git push +git tag v0.6.0 +git push origin v0.6.0 +``` + +### 4. Sync `main` back to `dev` after release + +After the release, sync `main` back into `dev` again: + +```bash +git checkout dev +git pull +git merge main +git push +``` + +--- + +## Commit Message Recommendation + +Keep commit messages clear and easy to audit. + +Recommended format: + +```text +emoji type(scope): concise description +``` + +Examples: + +```text +🔧 fix(ci): fix DuckDB driver toolchain on Windows AMD64 +✨ feat(redis): add Stream data browsing support +♻️ refactor(datagrid): optimize large-table horizontal scrolling and rendering +``` + +--- + +## Additional Notes + +- Please include validation results for documentation, build-chain, or driver compatibility changes +- For larger changes, opening an issue or draft PR first is recommended +- Maintainers may ask contributors to narrow the scope if the change conflicts with the current project direction + +Thank you for contributing. diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md new file mode 100644 index 0000000..20cc60e --- /dev/null +++ b/CONTRIBUTING.zh-CN.md @@ -0,0 +1,154 @@ +# 贡献指南 + +感谢你对本项目的贡献。 + +本项目采用“发布优先（`main` 为默认分支）+ `release/*` 分支发版”的协作模型。为减少分支漂移与 PR 处理成本，请在提交贡献前先阅读本指南。 + +--- + +## 分支模型 + +- `main`：稳定发布分支，也是仓库默认分支 +- `dev`：日常开发集成分支，主要供维护者使用 +- `release/*`：发布准备分支，主要供维护者使用 +- 外部贡献者建议使用以下分支命名： + - `fix/*`：问题修复 + - `feature/*`：功能新增或增强 + +维护者发布流转如下： + +```text +feature/* / fix/* -> dev -> release/* -> main -> tag(vX.Y.Z) +``` + +--- + +## 外部贡献者如何提 Pull Request + +无论是 `fix/*` 还是 `feature/*`，**外部贡献者统一直接向 `main` 发起 Pull Request**。 + +这样做的原因： + +- `main` 是默认分支，PR 入口更直观 +- 合并后贡献会直接体现在默认分支 +- 便于维护者统一做后续同步与发版整理 + +建议流程： + +1. Fork 本仓库 +2. 从你自己的仓库创建分支（建议命名为 `fix/*` 或 `feature/*`） +3. 完成代码修改，并进行必要自检 +4. 推送到你的远程分支 +5. 向本仓库的 `main` 分支发起 Pull Request + +--- + +## Pull Request 要求 + +请尽量保证 PR 单一、清晰、可审核。 + +建议遵循以下要求： + +- 一个 PR 只解决一类问题，避免混入无关改动 +- 标题清晰说明改动目的 +- 描述中说明： + - 背景与问题 + - 变更点 + - 影响范围 + - 验证方式 +- 如涉及 UI 调整，建议附截图或录屏 +- 如涉及兼容性、数据变更或构建链路调整，请明确说明风险和回滚方式 + +--- + +## PR 合并策略（维护者） + +`main` 分支上的 PR 建议使用 **Squash and merge**。 + +原因： + +- 保持 `main` 历史干净、线性 +- 每个 PR 在 `main` 上对应一个清晰提交 +- 降低发布排查与回滚成本 + +--- + +## 维护者同步规则 + +由于外部 PR 会直接合入 `main`，维护者必须及时将 `main` 的变更同步到开发与发布分支，避免分支漂移。 + +### 1. main → dev 同步（必做） + +任何合入 `main` 的变更，都必须同步到 `dev`： + +```bash +git checkout dev +git pull +git merge main +git push +``` + +### 2. 发版前从 dev 切 release/* + +发布前由维护者基于 `dev` 创建发布分支，例如： + +```bash +git checkout dev +git pull +git checkout -b release/v0.6.0 +git push -u origin release/v0.6.0 +``` + +### 3. release/* → main 发版 + +发布准备完成后，将 `release/*` 合并回 `main`，并打标签发布： + +```bash +git checkout main +git pull +git merge release/v0.6.0 +git push +git tag v0.6.0 +git push origin v0.6.0 +``` + +### 4. main 回流到 dev（发版后必做） + +发布完成后，再次将 `main` 回流到 `dev`，确保开发线与发布线一致： + +```bash +git checkout dev +git pull +git merge main +git push +``` + +--- + +## 提交建议 + +建议保持提交信息简洁、明确，便于维护者审查与后续追踪。 + +推荐格式： + +```text +emoji type(scope): 中文描述 +``` + +示例： + +```text +🔧 fix(ci): 修复 Windows AMD64 下 DuckDB 驱动构建工具链 +✨ feat(redis): 新增 Stream 类型数据浏览支持 +♻️ refactor(datagrid): 优化大表横向滚动与渲染结构 +``` + +--- + +## 其他说明 + +- 文档、构建链路、驱动兼容性相关改动，请尽量附带验证结果 +- 若改动较大，建议先提 Issue 或 Draft PR，先对齐方案再实施 +- 如提交内容与项目当前架构方向冲突，维护者可能要求收敛范围后再合并 + +感谢你的贡献。 diff --git a/README.md b/README.md index de049cd..4ad80ac 100644 --- a/README.md +++ b/README.md @@ -200,11 +200,11 @@ If you use Linux artifacts with the `-WebKit41` suffix, prefer Debian 13 / Ubunt Issues and pull requests are welcome. -1. Fork the repository. -2. Create a feature branch. -3. Commit your changes. -4. Push to your branch. -5. Open a pull request. +For the full workflow, branch model, and maintainer sync rules, see: + +- [CONTRIBUTING.md](CONTRIBUTING.md) + +External contributors should open pull requests directly against `main`. ## License diff --git a/README.zh-CN.md b/README.zh-CN.md index b572ee8..3a2f2d5 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -183,11 +183,11 @@ sudo apt-get install -y libgtk-3-0 libwebkit2gtk-4.0-37 libjavascriptcoregtk-4.0 欢迎提交 Issue 与 Pull Request。 -1. Fork 本仓库。 -2. 创建特性分支。 -3. 提交改动。 -4. 推送分支。 -5. 发起 Pull Request。 +完整流程、分支模型与维护者同步规则请查看： + +- [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md) + +外部贡献者统一直接向 `main` 发起 Pull Request。 ## 开源协议