github-featured/yishentu--claudian
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: add contribution guidelines and templates (#990)

Browse Source
This commit is contained in:
Yishen Tu
2026-07-28 12:29:18 +08:00
committed by GitHub
parent 053829b0b6
commit e6bacf19c6
6 changed files with 257 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/bug_report.yml
+77
View File
@@ -0,0 +1,77 @@
name: Bug report
description: Report a reproducible problem with Claudian
title: "[Bug]: "
labels:
- bug
body:
- type: markdown
attributes:
value: |
Thanks for reporting a problem. Clear behavior, reproduction steps, and environment details make an issue much easier to investigate.
- type: checkboxes
id: checks
attributes:
label: Before submitting
options:
- label: I searched existing issues and did not find the same problem.
required: true
- label: I removed API keys, tokens, private vault content, personal paths, and other sensitive information.
required: true
- type: textarea
id: problem
attributes:
label: Problem
description: What were you trying to do, and what went wrong?
placeholder: Describe the problem and its impact.
validations:
required: true
- type: textarea
id: reproduction
attributes:
label: Steps to reproduce
description: Provide the smallest reliable sequence that reproduces the problem.
placeholder: |
1. Open ...
2. Configure ...
3. Run ...
4. Observe ...
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected behavior
description: What did you expect to happen?
validations:
required: true
- type: textarea
id: environment
attributes:
label: Environment
description: Include every applicable version and installation detail.
value: |
- Claudian version:
- Obsidian version:
- Operating system:
- Provider:
- Provider CLI version:
- Provider CLI installation method:
validations:
required: true
- type: textarea
id: evidence
attributes:
label: Logs and other evidence
description: Add relevant logs, screenshots, recordings, or a minimal vault/example. Redact sensitive information first.
- type: textarea
id: context
attributes:
label: Additional context
description: Add anything else that may help explain or isolate the problem.
.github/ISSUE_TEMPLATE/config.yml
+1
View File
@@ -0,0 +1 @@
blank_issues_enabled: true
.github/ISSUE_TEMPLATE/feature_request.yml
+68
View File
@@ -0,0 +1,68 @@
name: Feature request
description: Describe an unmet use case or a focused improvement
title: "[Feature]: "
body:
- type: markdown
attributes:
value: |
Feature requests are welcome. Start with the problem or unmet use case; a proposed implementation is optional.
Pull requests that add a new provider are not accepted. Provider-related use cases may still be discussed, but opening an issue does not imply that the provider will be added.
- type: checkboxes
id: checks
attributes:
label: Before submitting
options:
- label: I searched existing issues and did not find the same request.
required: true
- type: textarea
id: problem
attributes:
label: Problem or unmet use case
description: What are you unable to do today, who does this affect, and why does it matter?
validations:
required: true
- type: textarea
id: outcome
attributes:
label: Desired outcome
description: Describe the behavior or result you would like, without assuming a particular implementation.
validations:
required: true
- type: dropdown
id: provider
attributes:
label: Affected provider
description: Select the closest match.
options:
- Not provider-specific
- Claude
- Codex
- Grok
- OpenCode
- Pi
- Other or new provider
validations:
required: true
- type: textarea
id: proposal
attributes:
label: Proposed solution
description: If you have an approach in mind, explain it and any tradeoffs you see.
- type: textarea
id: alternatives
attributes:
label: Alternatives considered
description: How do you handle this today, and what limitations does that workaround have?
- type: textarea
id: context
attributes:
label: Additional context
description: Add examples, screenshots, links, or environment details that clarify the request. Remove sensitive information first.
.github/PULL_REQUEST_TEMPLATE.md
+29
View File
@@ -0,0 +1,29 @@
## Why
<!-- What problem does this solve, who does it affect, and why is it worth solving? Link the issue when one exists. -->
## What Changed
<!-- Summarize the focused behavior or code changes. -->
## Why This Approach
<!-- Explain why this design is a good fit. Include meaningful alternatives and tradeoffs. -->
## Validation
<!-- List automated tests and manual checks. Add screenshots or recordings for user-facing changes. -->
## Impact and Follow-ups
<!-- Note compatibility or data risks, known limitations, and follow-up work. Write "None" when not applicable. -->
## Checklist
- [ ] This pull request addresses one focused problem.
- [ ] I linked the relevant issue, or explained why no issue is needed.
- [ ] I added or updated tests for behavior changes, or explained why tests are not applicable.
- [ ] I ran the relevant typecheck, lint, test, and build commands.
- [ ] I updated user-facing documentation when needed.
- [ ] This pull request does not add a new provider.
- [ ] I removed secrets, private vault content, and other sensitive information from the changes and evidence.
CONTRIBUTING.md
+76
View File
@@ -0,0 +1,76 @@
# Contributing to Claudian
Issues and pull requests are welcome. Issues are the preferred way to contribute: if you describe the problem and your environment clearly, I will review it and make a best effort to address it.
## Before You Start
- Search existing issues and pull requests to avoid duplicates.
- For a substantial change, open an issue first so the problem and scope can be discussed before implementation.
- Keep each pull request focused on one problem. Unrelated fixes, refactors, formatting changes, or dependency updates should be submitted separately.
## Reporting an Issue
A useful issue explains the problem well enough for someone else to understand and reproduce it. Please include:
- What you were trying to do.
- What happened and what you expected instead.
- Clear reproduction steps or a minimal example.
- Your Claudian version, Obsidian version, operating system, provider, provider CLI version, and installation method.
- Relevant logs, screenshots, or recordings.
Remove API keys, tokens, private vault content, personal paths, and other sensitive information before attaching logs or screenshots.
For a feature request, start with the user problem or unmet use case. A proposed solution is helpful, but explaining the need is more important than prescribing an implementation.
## Pull Requests
Pull requests are welcome when they solve a specific, well-defined problem. A pull request description must explain:
- **Why:** the problem being solved, who it affects, and why it is worth solving.
- **What:** the behavior or code that changes.
- **Why this approach:** why the proposed design is a good fit, including meaningful alternatives and tradeoffs.
- **Validation:** tests and manual checks performed, with screenshots or recordings for user-facing changes.
- **Impact:** known limitations, compatibility or data risks, and any follow-up work.
- **Context:** a linked issue when one exists.
Please also:
- Add or update tests for behavior changes and bug fixes.
- Preserve provider and feature ownership boundaries; avoid coupling shared feature code to provider internals.
- Avoid new production dependencies unless the need and tradeoff are explicit.
- Update documentation when behavior or user-facing configuration changes.
## New Provider Policy
Pull requests that add a new provider are not accepted.
This is a maintenance and product-quality boundary:
1. I am the sole maintainer of this project and remain responsible for every integration after it is merged. If I do not use a provider myself, I cannot test and maintain its integration responsibly over time.
2. Integrated providers must offer a broadly consistent feature set and user experience. Past attempts have shown that partial integrations are difficult to bring to parity and keep reliable.
3. Some provider CLIs do not currently expose the capabilities required for a complete integration. For example, Antigravity CLI does not expose ACP or a comparable integration protocol, and Cursor CLI does not allow the system prompt to be customized fully.
4. Integrating a separate CLI from every model vendor is not sustainable. OpenCode and Pi already support multiple model vendors through API configuration. Codex and Claude Code can also use alternative model endpoints through configuration. Inside an Obsidian vault, switching the underlying harness usually provides limited additional value compared with the ongoing integration and maintenance cost.
You may open an issue to describe an unmet provider-related use case, but please do not submit a new-provider implementation. An issue does not imply that the provider will be added.
Contributions that improve an existing provider are welcome when they follow the focused pull request requirements above and preserve the expected cross-provider experience.
## Development
Claudian requires the Node.js version declared in `.node-version`.
```bash
npm install
npm run dev
```
For a bug fix or new behavior, add or update a failing test first, then make the narrowest implementation change that passes it. Use focused checks while iterating. Before submitting a pull request, run the full verification suite:
```bash
npm run typecheck
npm run lint
npm run test
npm run build
```
The project architecture and area-specific development rules are documented in `AGENTS.md` and the scoped `AGENTS.md` files under `src/`.
README.md
+6
View File
@@ -82,6 +82,12 @@ npm run dev
npm run build
```
## Contributing
Issues and focused pull requests are welcome. Issues are the preferred starting point: describe the problem, reproduction steps, and environment clearly so it can be investigated.
Before opening a pull request, please read the [contribution guide](CONTRIBUTING.md). Pull requests must explain the problem, the proposed solution, why the approach is appropriate, and how the change was validated. Pull requests that add a new provider are not accepted; the guide explains this maintenance and product-quality boundary in detail.
## Privacy & Data Use
- **Sent to API**: Your input, attached files, images, and tool call outputs. Default: Anthropic (Claude), OpenAI (Codex), xAI (Grok), or the provider configured in Opencode/Pi; configurable via provider settings and environment variables.