Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
125 lines (82 loc) · 3.29 KB

CONTRIBUTING.md

File metadata and controls

125 lines (82 loc) · 3.29 KB

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:

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:

git remote add upstream https://github.com/OthmanAdi/planning-with-files.git
git fetch upstream

The canonical skill lives here:

skills/planning-with-files/SKILL.md

Before opening a pull request, run the test suite:

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:

skills/planning-with-files/

Language variants live under directories that follow this pattern:

skills/planning-with-files-<lang>/

IDE adapter variants live under these directories:

.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:

fix/short-description
feat/short-description
docs/short-description

Use Conventional Commits for commit messages:

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:

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:

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.