김경종
161 lines
5.6 KiB
Markdown
161 lines
5.6 KiB
Markdown
# Contributing to claude-obsidian
|
||
|
||
Thanks for your interest in improving this plugin. claude-obsidian is a small, focused project; contributions that match its philosophy land quickly.
|
||
|
||
## Philosophy
|
||
|
||
Three constraints shape every change:
|
||
|
||
1. **Read before write.** Every contribution starts by reading the affected files, their tests, and their callers. Removals break assumptions as often as additions.
|
||
2. **Smallest unit that works.** No speculative abstraction. Complexity is earned, not anticipated. Three real callers minimum before an abstraction lands.
|
||
3. **Failure is the spec.** Every new failure mode needs explicit handling. Untrusted input, network calls, and state changes need an explicit blast-radius answer.
|
||
|
||
The full kernel lives in [`/best-practices`](https://github.com/AgriciDaniel/best-practices) (composable Claude Code skill). The pre-commit verifier agent at [`agents/verifier.md`](agents/verifier.md) enforces it for non-trivial changes.
|
||
|
||
## Workflow
|
||
|
||
### 1. Open an issue first (for non-trivial changes)
|
||
|
||
For typo fixes, doc clarifications, or single-line changes, skip straight to a PR. For anything bigger:
|
||
|
||
- Open an issue using the bug-report or feature-request template
|
||
- Describe the problem, the proposed change, and the blast radius
|
||
- Wait for a thumbs-up before investing time
|
||
|
||
### 2. Fork + branch
|
||
|
||
Contributions are accepted on the public canonical repo. Fork [`AgriciDaniel/claude-obsidian`](https://github.com/AgriciDaniel/claude-obsidian) on GitHub, then:
|
||
|
||
```bash
|
||
git clone https://github.com/<your-username>/claude-obsidian.git
|
||
cd claude-obsidian
|
||
git checkout -b your-feature-name
|
||
```
|
||
|
||
> ℹ️ The public repo (`AgriciDaniel/claude-obsidian`) is the canonical source of truth. Raise all PRs against it. AI Marketing Hub Pro members working from the early-access mirror (`AI-Marketing-Hub/claude-obsidian`) should target the public canonical too, so contributions land in one place.
|
||
|
||
Branch names: `fix/...`, `feat/...`, `docs/...`, `refactor/...`.
|
||
|
||
### 3. Set up locally
|
||
|
||
The plugin runs anywhere Claude Code runs. For development:
|
||
|
||
```bash
|
||
# Run the hermetic test suite — required before submitting a PR
|
||
make test
|
||
|
||
# Optionally provision the v1.7 retrieval pipeline (requires consent for API egress)
|
||
bash bin/setup-retrieve.sh
|
||
|
||
# Optionally pick a methodology mode for testing the v1.8 routing
|
||
bash bin/setup-mode.sh
|
||
```
|
||
|
||
### 4. Make the change
|
||
|
||
Follow the six-cut kernel:
|
||
- Read every file you're touching
|
||
- Name new identifiers like the next reader is hostile
|
||
- Smallest unit that works
|
||
- Delete more than you add (when superseding)
|
||
- Evidence over intuition (tests for new behavior)
|
||
- Failure-mode + undo plan documented
|
||
|
||
If you add a new skill, agent, script, or hook, also add a test under `tests/`. The 9 hermetic test suites are the project's safety net.
|
||
|
||
### 5. Run the tests
|
||
|
||
```bash
|
||
make test
|
||
```
|
||
|
||
All 9 suites must pass (~1240 assertions). Tests are hermetic: no network, no ollama, no Anthropic API. If your change adds a network call, gate it behind a `--consent`/`--allow-egress`/env-var pattern matching `scripts/contextual-prefix.py` or `scripts/tiling-check.py`.
|
||
|
||
### 6. Run the verifier (optional but recommended)
|
||
|
||
For multi-file changes:
|
||
|
||
```bash
|
||
# After git add, before git commit, dispatch the verifier agent
|
||
# (Claude Code: invoke agents/verifier.md on the staged diff)
|
||
```
|
||
|
||
The verifier applies the six-cut + agent kernel to your staged diff and returns findings in BLOCKER / HIGH / MEDIUM / LOW tiers. Address BLOCKER + HIGH before committing.
|
||
|
||
### 7. Commit
|
||
|
||
Commit message convention (Conventional Commits):
|
||
|
||
```
|
||
<type>(<scope>): <short description>
|
||
|
||
<longer body if needed>
|
||
```
|
||
|
||
Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `perf`, `style`.
|
||
|
||
Example:
|
||
```
|
||
fix(wiki-mode): close path-traversal in route_path safe_name
|
||
|
||
Sanitize routing input via safe_name() before string-concat into
|
||
the vault-relative path. Adds 9 hermetic test assertions for traversal
|
||
vectors. Closes audit finding S1.
|
||
```
|
||
|
||
### 8. Update CHANGELOG.md
|
||
|
||
Add an entry under `## [Unreleased]` (create the section if needed). Follow the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format:
|
||
|
||
```markdown
|
||
## [Unreleased]
|
||
|
||
### Added
|
||
- Description of new feature
|
||
|
||
### Fixed
|
||
- Description of bug fix
|
||
```
|
||
|
||
The maintainer will move your entry to a versioned section at release time.
|
||
|
||
### 9. Open a PR
|
||
|
||
Use the PR template. Required fields:
|
||
- What changed
|
||
- Why
|
||
- How it was tested (paste `make test` output if relevant)
|
||
- Audit/verifier results if applicable
|
||
|
||
PRs are reviewed against the kernel. Expect feedback on naming, scope, and failure-mode coverage.
|
||
|
||
## Testing standards
|
||
|
||
- **Hermetic.** No network, no external services, no user-specific environment.
|
||
- **Fast.** The full suite runs in under a minute.
|
||
- **Deterministic.** Same input → same output, every time.
|
||
- **Documented.** Every test asserts a named behavior, not a coincidence.
|
||
|
||
If you can't make your test hermetic, ask in the issue whether a mocked alternative is acceptable.
|
||
|
||
## What we will NOT merge
|
||
|
||
- Code without tests for new behavior
|
||
- Speculative abstractions (no real callers yet)
|
||
- Network calls without an explicit consent gate
|
||
- Path construction from user input without sanitization (see `scripts/wiki-mode.py:safe_name`)
|
||
- Skills/agents that shell out without documenting the failure mode
|
||
- Anything that breaks the existing test suite without a documented reason
|
||
|
||
## Security
|
||
|
||
Found a vulnerability? Do NOT open a public issue. See [SECURITY.md](SECURITY.md) for disclosure.
|
||
|
||
## License
|
||
|
||
By contributing, you agree your contributions are licensed under the [MIT License](LICENSE).
|
||
|
||
## Code of Conduct
|
||
|
||
Participation is governed by the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
|