From af2c839231b836503952a0f9648429fb5b0e5529 Mon Sep 17 00:00:00 2001 From: zhayujie Date: Mon, 1 Jun 2026 11:01:28 +0800 Subject: [PATCH] docs: add contributing guide and issue/PR templates --- .github/ISSUE_TEMPLATE/1.bug.yml | 145 ++++++--------------------- .github/ISSUE_TEMPLATE/2.feature.yml | 31 +++--- .github/ISSUE_TEMPLATE/config.yml | 5 + .github/PULL_REQUEST_TEMPLATE.md | 21 ++++ CONTRIBUTING.md | 61 +++++++++++ 5 files changed, 135 insertions(+), 128 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/1.bug.yml b/.github/ISSUE_TEMPLATE/1.bug.yml index a4f10926..7c0ec054 100644 --- a/.github/ISSUE_TEMPLATE/1.bug.yml +++ b/.github/ISSUE_TEMPLATE/1.bug.yml @@ -1,131 +1,46 @@ name: Bug report 🐛 -description: 项目运行中遇到的Bug或问题。 +description: Report a bug or unexpected behavior. +title: "[Bug] " labels: ['status: needs check'] body: - type: markdown attributes: value: | - ### ⚠️ 前置确认 - 1. 网络能够访问openai接口 - 2. python 已安装：版本在 3.7 ~ 3.10 之间 - 3. `git pull` 拉取最新代码 - 4. 执行`pip3 install -r requirements.txt`，检查依赖是否满足 - 5. 拓展功能请执行`pip3 install -r requirements-optional.txt`，检查依赖是否满足 - 6. [FAQS](https://github.com/zhayujie/chatgpt-on-wechat/wiki/FAQs) 中无类似问题 + > 💡 English is recommended so global developers can help. 【中文用户】推荐使用英文提交，谢谢 ❤️ - type: checkboxes attributes: - label: 前置确认 + label: Self check options: - - label: 我确认我运行的是最新版本的代码，并且安装了所需的依赖，在[FAQS](https://github.com/zhayujie/chatgpt-on-wechat/wiki/FAQs)中也未找到类似问题。 + - label: I'm on the latest version and searched [existing issues](https://github.com/zhayujie/CowAgent/issues) (incl. closed) — no duplicate. required: true - - type: checkboxes + - type: textarea attributes: - label: ⚠️ 搜索issues中是否已存在类似问题 - description: > - 请在 [历史issue](https://github.com/zhayujie/chatgpt-on-wechat/issues) 中清空输入框，搜索你的问题 - 或相关日志的关键词来查找是否存在类似问题。 - options: - - label: 我已经搜索过issues和disscussions，没有跟我遇到的问题相关的issue - required: true - - type: markdown - attributes: - value: | - 请在上方的`title`中填写你对你所遇到问题的简略总结，这将帮助其他人更好的找到相似问题，谢谢❤️。 - - type: dropdown - attributes: - label: 操作系统类型? - description: > - 请选择你运行程序的操作系统类型。 - options: - - Windows - - Linux - - MacOS - - Docker - - Railway - - Windows Subsystem for Linux (WSL) - - Other (请在问题中说明) - validations: - required: true - - type: dropdown - attributes: - label: 运行的python版本是? - description: | - 请选择你运行程序的`python`版本。 - 注意：在`python 3.7`中，有部分可选依赖无法安装。 - 经过长时间的观察，我们认为`python 3.8`是兼容性最好的版本。 - `python 3.7`~`python 3.10`以外版本的issue，将视情况直接关闭。 - options: - - python 3.7 - - python 3.8 - - python 3.9 - - python 3.10 - - other - validations: - required: true - - type: dropdown - attributes: - label: 使用的chatgpt-on-wechat版本是? - description: | - 请确保你使用的是 [releases](https://github.com/zhayujie/chatgpt-on-wechat/releases) 中的最新版本。 - 如果你使用git, 请使用`git branch`命令来查看分支。 - options: - - Latest Release - - Master (branch) - validations: - required: true - - type: dropdown - attributes: - label: 运行的`channel`类型是? - description: | - 请确保你正确配置了该`channel`所需的配置项，所有可选的配置项都写在了[该文件中](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/config.py)，请将所需配置项填写在根目录下的`config.json`文件中。 - options: - - wechatmp(公众号, 订阅号) - - wechatmp_service(公众号, 服务号) - - terminal - - other + label: Environment + description: "Version (`cow status`), OS, Python version, install method, model & channel." + placeholder: | + Version: v1.2.0 + OS: macOS / Linux / Windows / Docker + Python: 3.11 + Install: installer / Docker / source + Model & channel: deepseek-v4-flash, web validations: required: true - type: textarea attributes: - label: 复现步骤 🕹 - description: | - **⚠️ 不能复现将会关闭issue.** - - type: textarea - attributes: - label: 问题描述 😯 - description: 详细描述出现的问题，或提供有关截图。 - - type: textarea - attributes: - label: 终端日志 📒 - description: | - 在此处粘贴终端日志，可在主目录下`run.log`文件中找到，这会帮助我们更好的分析问题，注意隐去你的API key。 - 如果在配置文件中加入`"debug": true`，打印出的日志会更有帮助。 + label: What happened? + description: "Steps to reproduce, what you expected, and what happened instead. Screenshots welcome." + placeholder: | + 1. ... + 2. ... -
- 示例 - ```log - [DEBUG][2023-04-16 00:23:22][plugin_manager.py:157] - Plugin SUMMARY triggered by event Event.ON_HANDLE_CONTEXT - [DEBUG][2023-04-16 00:23:22][main.py:221] - [Summary] on_handle_context. content: $总结前100条消息 - [DEBUG][2023-04-16 00:23:24][main.py:240] - [Summary] limit: 100, duration: -1 seconds - [ERROR][2023-04-16 00:23:24][chat_channel.py:244] - Worker return exception: name 'start_date' is not defined - Traceback (most recent call last): - File "C:\ProgramData\Anaconda3\lib\concurrent\futures\thread.py", line 57, in run - result = self.fn(*self.args, **self.kwargs) - File "D:\project\chatgpt-on-wechat\channel\chat_channel.py", line 132, in _handle - reply = self._generate_reply(context) - File "D:\project\chatgpt-on-wechat\channel\chat_channel.py", line 142, in _generate_reply - e_context = PluginManager().emit_event(EventContext(Event.ON_HANDLE_CONTEXT, { - File "D:\project\chatgpt-on-wechat\plugins\plugin_manager.py", line 159, in emit_event - instance.handlers[e_context.event](e_context, *args, **kwargs) - File "D:\project\chatgpt-on-wechat\plugins\summary\main.py", line 255, in on_handle_context - records = self._get_records(session_id, start_time, limit) - File "D:\project\chatgpt-on-wechat\plugins\summary\main.py", line 96, in _get_records - c.execute("SELECT * FROM chat_records WHERE sessionid=? and timestamp>? ORDER BY timestamp DESC LIMIT ?", (session_id, start_date, limit)) - NameError: name 'start_date' is not defined - [INFO][2023-04-16 00:23:36][app.py:14] - signal 2 received, exiting... - ``` -
- value: | - ```log - <此处粘贴终端日志> - ``` \ No newline at end of file + Expected: ... + Actual: ... + validations: + required: true + - type: textarea + attributes: + label: Logs + description: "Relevant logs from `nohup.out` (set `\"debug\": true` for more detail). ⚠️ Redact your API keys." + render: shell + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/2.feature.yml b/.github/ISSUE_TEMPLATE/2.feature.yml index bbf0888a..4bf3f9d1 100644 --- a/.github/ISSUE_TEMPLATE/2.feature.yml +++ b/.github/ISSUE_TEMPLATE/2.feature.yml @@ -1,28 +1,33 @@ name: Feature request 🚀 -description: 提出你对项目的新想法或建议。 +description: Suggest a new idea or improvement. +title: "[Feature] " labels: ['status: needs check'] body: - type: markdown attributes: value: | - 请在上方的`title`中填写简略总结，谢谢❤️。 + > 💡 English is recommended so global developers can help. 【中文用户】推荐使用英文提交，谢谢 ❤️ - type: checkboxes attributes: - label: ⚠️ 搜索是否存在类似issue - description: > - 请在 [历史issue](https://github.com/zhayujie/chatgpt-on-wechat/issues) 中清空输入框，搜索关键词查找是否存在相似issue。 + label: Self check options: - - label: 我已经搜索过issues和disscussions，没有发现相似issue + - label: I searched [existing issues](https://github.com/zhayujie/CowAgent/issues) (incl. closed) — no duplicate. required: true - type: textarea attributes: - label: 总结 - description: 描述feature的功能。 + label: What problem does this solve? + description: "The use case or pain point — what are you trying to do, and what gets in the way?" + validations: + required: true - type: textarea attributes: - label: 举例 - description: 提供聊天示例，草图或相关网址。 - - type: textarea + label: Proposed solution + description: "What you'd like. Examples, sketches, or links welcome." + validations: + required: false + - type: checkboxes attributes: - label: 动机 - description: 描述你提出该feature的动机，比如没有这项feature对你的使用造成了怎样的影响。 请提供更详细的场景描述，这可能会帮助我们发现并提出更好的解决方案。 \ No newline at end of file + label: Contribution + options: + - label: I'd be interested in helping implement this. + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..a37a397e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: 📖 Documentation + url: https://docs.cowagent.ai + about: Setup guides, configuration, and FAQ. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..74c15bc7 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,21 @@ + + +## What does this PR do? + + + +## Type of change + +- [ ] Bug fix +- [ ] New feature +- [ ] Docs +- [ ] Refactor / chore + +## Checklist + +- [ ] I tested this change locally +- [ ] Code comments and docs are in English +- [ ] Linked related issue (if any): closes # diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..46f3fc3e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,61 @@ +# Contributing to CowAgent + +Thanks for taking the time to contribute! 🎉 CowAgent is built by a global +community, and contributions of all sizes are welcome — from typo fixes to new +features. + +## Language policy + +To keep the project accessible to a global community, **please write issues, +pull requests, code comments, and commit messages in English.** + +> 【致中文开发者】为方便全球开发者协作，请尽量使用**英文**提交 issue、PR、代码注释与 +> commit message。不必担心英文不完美——表达清楚即可，工具翻译也完全没问题。感谢理解 ❤️ + +## Reporting issues + +Found a bug or have an idea? [Open an issue](https://github.com/zhayujie/CowAgent/issues/new/choose). + +Before opening one, please search existing issues (including closed ones) to +avoid duplicates, and make sure you're on the latest version. + +## Submitting a pull request + +1. **Fork** the repo and create a branch from `master` + (e.g. `feat/web-search`, `fix/telegram-reconnect`). +2. Make your change. Keep it focused — one logical change per PR. +3. Follow the existing code style. Write comments and docstrings in English. +4. Run the app locally to confirm your change works. +5. Open a PR with a clear title and a short description of **what** and **why**. + +We keep the bar friendly: clear, focused, and working is enough. Maintainers are +happy to help polish details during review. + +### Commit & PR titles + +Use a short, imperative summary. The [Conventional Commits](https://www.conventionalcommits.org/) +style is preferred but not required: + +``` +feat: add web search tool +fix: reconnect Telegram websocket on timeout +docs: clarify Docker setup +``` + +## Development setup + +See the [Install from Source](https://docs.cowagent.ai/guide/manual-install) +guide. In short: + +```bash +git clone https://github.com/zhayujie/CowAgent.git +cd CowAgent +pip install -r requirements.txt +pip install -e . +cow start +``` + +## Code of conduct + +Be respectful and constructive. We want CowAgent to be a welcoming place for +everyone.