update guidelines

2026-07-01 01:54:27 +08:00 · 2026-03-17 08:19:05 +00:00
parent 9997438eec
commit 5ee6b1aa00
6 changed files with 299 additions and 0 deletions
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,88 @@
+name: Bug Report
+description: Report a bug in CLI-Anything
+title: "[Bug]: "
+labels: ["type: bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill out the information below to help us reproduce and fix it.
+
+  - type: input
+    id: software
+    attributes:
+      label: Affected Software/Harness
+      description: Which CLI harness is affected? (e.g., gimp, blender, inkscape, or "plugin" for the framework)
+      placeholder: e.g., gimp
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version / Commit
+      description: The version or commit hash you are using.
+      placeholder: e.g., v1.0.0 or commit abc1234
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - Linux
+        - macOS
+        - Windows
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      placeholder: e.g., 3.10.12
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: Provide clear steps to reproduce the bug.
+      placeholder: |
+        1. Install the harness with `pip install -e .`
+        2. Run `cli-anything-gimp project create test.xcf`
+        3. See error...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened? Include error messages or tracebacks if applicable.
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Logs / Tracebacks
+      description: Paste any relevant output here. This will be auto-formatted as code.
+      render: shell
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Any other context, screenshots, or information that might help.
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & Discussions
+    url: https://github.com/HKUDS/CLI-Anything/discussions
+    about: Please ask questions and discuss ideas here instead of opening an issue.
+  - name: CLI Generation Help
+    url: https://github.com/HKUDS/CLI-Anything/discussions/categories/q-a
+    about: Need help generating a CLI for a new software? Ask in Discussions first.
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,52 @@
+name: Feature Request
+description: Suggest a new feature or enhancement
+title: "[Feature]: "
+labels: ["type: enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please describe your idea clearly so we can evaluate it.
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Category
+      description: What type of feature is this?
+      options:
+        - New Software CLI
+        - Enhancement to Existing Harness
+        - Plugin / Framework Improvement
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem does this feature solve? What pain point are you experiencing?
+      placeholder: I'm always frustrated when...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution you'd like to see.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Have you considered any alternative solutions or workarounds?
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Any other context, mockups, or references that might help.
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,51 @@
+## Description
+
+<!-- Briefly describe the changes in this PR. -->
+
+Fixes #<!-- issue number -->
+
+## Type of Change
+
+<!-- Check the one that applies: -->
+
+- [ ] **New Software CLI** — adds a CLI harness for a new application
+- [ ] **New Feature** — adds new functionality to an existing harness or the plugin
+- [ ] **Bug Fix** — fixes incorrect behavior
+- [ ] **Documentation** — updates docs only
+- [ ] **Other** — please describe:
+
+---
+
+### For New Software CLIs
+
+<!-- If this PR adds a new software CLI, ALL items below must be checked. -->
+
+- [ ] `<SOFTWARE>.md` SOP document exists at `<software>/agent-harness/<SOFTWARE>.md`
+- [ ] `SKILL.md` exists inside the Python package (`cli_anything/<software>/SKILL.md`)
+- [ ] Unit tests at `cli_anything/<software>/tests/test_core.py` are present and pass without backend
+- [ ] E2E tests at `cli_anything/<software>/tests/test_full_e2e.py` are present
+- [ ] `README.md` includes the new software (with link to harness directory)
+- [ ] `repl_skin.py` in `utils/` is an unmodified copy from the plugin
+
+### For Existing CLI Modifications
+
+<!-- If this PR modifies an existing harness, ALL items below must be checked. -->
+
+- [ ] All unit tests pass: `python3 -m pytest cli_anything/<software>/tests/test_core.py -v`
+- [ ] All E2E tests pass: `python3 -m pytest cli_anything/<software>/tests/test_full_e2e.py -v`
+- [ ] No test regressions — no previously passing tests were removed or weakened
+
+### General Checklist
+
+- [ ] Code follows existing patterns and conventions
+- [ ] `--json` flag is supported on any new commands
+- [ ] Commit messages follow the conventional format (`feat:`, `fix:`, `docs:`, `test:`)
+- [ ] I have tested my changes locally
+
+## Test Results
+
+<!-- Paste the output of `pytest -v` for the affected harness(es). -->
+
+```
+<paste test output here>
+```
--- a/.gitignore
+++ b/.gitignore
@@ -13,8 +13,10 @@
 # Step 2: Allow .gitignore, README, assets, and marketplace
 !.gitignore
 !/README.md
+!/CONTRIBUTING.md
 !/assets/
 !/.claude-plugin/
+!/.github/

 # Step 3: Allow cli-anything-plugin, codex-skill, and skill_generation tests
 !/cli-anything-plugin/
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,98 @@
+# Contributing to CLI-Anything
+
+Thank you for your interest in contributing to CLI-Anything! This guide will help you get started.
+
+## Types of Contributions
+
+We welcome three main categories of contributions:
+
+### A) CLIs for New Software
+
+Adding a new CLI harness is the most impactful contribution. Before submitting a PR, ensure the following are in place:
+
+1. **`<SOFTWARE>.md`** — the SOP document exists at `<software>/agent-harness/<SOFTWARE>.md` describing the harness architecture.
+2. **`SKILL.md`** — the AI-discoverable skill definition exists inside the Python package at `cli_anything/<software>/SKILL.md`.
+3. **Tests** — unit tests (`test_core.py`, passable without backend) and E2E tests (`test_full_e2e.py`) are present and passing.
+4. **`README.md`** — the project README includes the new software with a link to its harness directory.
+5. **`repl_skin.py`** — an unmodified copy from the plugin exists in `utils/`.
+
+### B) New Features
+
+Feature contributions improve existing harnesses or the plugin framework. Examples include new CLI commands, output formats, backend improvements, or cross-platform fixes.
+
+- Open an issue first to discuss the feature before starting work.
+- Follow existing code patterns and conventions in the target harness.
+- Include tests for any new functionality.
+
+### C) Bug Fixes
+
+Bug fixes resolve incorrect behavior in existing harnesses or the plugin.
+
+- Reference the related issue in your PR (e.g., `Fixes #123`).
+- Include a test that reproduces the bug and verifies the fix.
+- Ensure all existing tests for the affected harness still pass.
+
+## Development Setup
+
+Each generated CLI lives in `<software>/agent-harness/` and is an independent Python package:
+
+```bash
+# Clone the repo
+git clone https://github.com/HKUDS/CLI-Anything.git
+cd CLI-Anything
+
+# Install a harness in editable mode
+cd <software>/agent-harness
+pip install -e .
+
+# Run tests
+python3 -m pytest cli_anything/<software>/tests/ -v
+```
+
+### Requirements
+
+- Python 3.10+
+- Click 8.0+
+- pytest 7.0+
+
+## Code Style
+
+- Follow PEP 8 conventions.
+- Use type hints where practical.
+- All CLI commands must support the `--json` flag for machine-readable output.
+
+## Commit Messages
+
+Use clear, descriptive commit messages following the conventional format:
+
+```
+feat: add Krita CLI harness
+fix: resolve Blender backend path on macOS
+docs: update README with new software entry
+test: add unit tests for Inkscape layer commands
+```
+
+## Running Tests
+
+```bash
+# Unit tests (no backend software needed)
+python3 -m pytest cli_anything/<software>/tests/test_core.py -v
+
+# E2E tests (requires real backend installed)
+python3 -m pytest cli_anything/<software>/tests/test_full_e2e.py -v
+
+# All tests for a harness
+python3 -m pytest cli_anything/<software>/tests/ -v
+```
+
+## Submitting a Pull Request
+
+1. Fork the repository and create a feature branch from `main`.
+2. Make your changes following the guidelines above.
+3. Ensure all tests pass for any harnesses you modified.
+4. Push your branch and open a Pull Request against `main`.
+5. Fill out the PR template completely.
+
+## Questions?
+
+If you have questions, feel free to open a [Discussion](https://github.com/HKUDS/CLI-Anything/discussions) or an issue tagged with `type: question`.