wehub-resource-sync
126 lines
3.3 KiB
Markdown
126 lines
3.3 KiB
Markdown
# Contributing
|
|
|
|
Thank you for considering a contribution to planning-with-files.
|
|
|
|
This project keeps contribution work small, traceable, and reviewable. Please make one logical change per pull request and keep the tone concise and concrete.
|
|
|
|
## How to set up locally
|
|
|
|
Fork the repository, then clone your fork:
|
|
|
|
```bash
|
|
git clone https://github.com/YOUR-USERNAME/planning-with-files.git
|
|
cd planning-with-files
|
|
```
|
|
|
|
Add the upstream repository so you can sync your fork with the original project:
|
|
|
|
```bash
|
|
git remote add upstream https://github.com/OthmanAdi/planning-with-files.git
|
|
git fetch upstream
|
|
```
|
|
|
|
The canonical skill lives here:
|
|
|
|
```text
|
|
skills/planning-with-files/SKILL.md
|
|
```
|
|
|
|
Before opening a pull request, run the test suite:
|
|
|
|
```bash
|
|
python -m pytest tests/ -q
|
|
```
|
|
|
|
Two pre-existing Windows exec-bit test failures may appear on Windows. If those are the only failures, note that in your pull request description.
|
|
|
|
## Project layout
|
|
|
|
The canonical skill source is:
|
|
|
|
```text
|
|
skills/planning-with-files/
|
|
```
|
|
|
|
Language variants live under directories that follow this pattern:
|
|
|
|
```text
|
|
skills/planning-with-files-<lang>/
|
|
```
|
|
|
|
IDE adapter variants live under these directories:
|
|
|
|
```text
|
|
.codebuddy/
|
|
.codex/
|
|
.cursor/
|
|
.factory/
|
|
.hermes/
|
|
.mastracode/
|
|
.opencode/
|
|
.pi/
|
|
```
|
|
|
|
The `clawhub-upload/` directory is gitignored and handled manually. Do not rely on it as the source of truth for repository changes.
|
|
|
|
## Submitting a PR
|
|
|
|
Use a focused branch name that describes the type of change:
|
|
|
|
```text
|
|
fix/short-description
|
|
feat/short-description
|
|
docs/short-description
|
|
```
|
|
|
|
Use Conventional Commits for commit messages:
|
|
|
|
```text
|
|
fix: describe the bug fix
|
|
feat: describe the new behavior
|
|
docs: describe the documentation change
|
|
```
|
|
|
|
Keep each pull request to one logical change. A documentation fix, a language variant update, and a test change should usually be separate pull requests.
|
|
|
|
When opening the pull request, include:
|
|
|
|
- What changed
|
|
- Why it changed
|
|
- How you tested it
|
|
- Any known limitations or platform-specific notes
|
|
|
|
If the pull request closes an issue, include the issue reference in the description:
|
|
|
|
```text
|
|
Closes #123
|
|
```
|
|
|
|
## Authorship and credit
|
|
|
|
The project maintains contributor credit in `CONTRIBUTORS.md`.
|
|
|
|
Merged pull requests earn a permanent contributor entry. Keep your Git author information accurate because your commits remain part of the project history and are not treated as disposable metadata.
|
|
|
|
Small contributions count. Documentation fixes, language variant updates, tests, and adapter improvements all help maintain the project.
|
|
|
|
## Language variant contributions
|
|
|
|
Translations and language variant improvements are welcome.
|
|
|
|
When working on a language variant, compare it against the canonical skill in:
|
|
|
|
```text
|
|
skills/planning-with-files/SKILL.md
|
|
```
|
|
|
|
Keep translated variants in parity with the canonical version. Do not ship a localized description with an English body stub. If a section cannot be translated yet, leave a clear note in the pull request instead of hiding incomplete work in the file.
|
|
|
|
## Where to ask questions
|
|
|
|
For general questions, use GitHub Discussions.
|
|
|
|
For issue-specific questions, comment on the relevant issue. If maintainer attention is needed, tag `@OthmanAdi` and describe the specific point you need help with.
|
|
|
|
Good questions include context, what you tried, and where you are blocked.
|