| 1 | # Contributing to PPT Master |
| 2 | |
| 3 | Thank you for your interest in contributing! This guide will help you get started. |
| 4 | |
| 5 | ## Ways to Contribute |
| 6 | |
| 7 | - **Templates** — New layout templates or visual styles |
| 8 | - **Charts** — Additional chart types or SVG chart templates |
| 9 | - **Icons** — Vector icons for the icon library |
| 10 | - **Scripts** — Improvements to conversion or post-processing scripts |
| 11 | - **Docs** — Substantive guides or corrections that materially improve project usage |
| 12 | - **Bug reports** — Reproducible issues with clear descriptions |
| 13 | - **Ideas** — Feature requests and design suggestions |
| 14 | |
| 15 | ## Getting Started |
| 16 | |
| 17 | ### Prerequisites |
| 18 | |
| 19 | - **Python 3.10+** — the only required dependency |
| 20 | - **Node.js 18+** and **Pandoc** are edge-case fallbacks that 99% of contributors never need; install only if you're working on the specific paths that require them. See the [README Quick Start](./README.md#1-prerequisites) for when each applies. |
| 21 | |
| 22 | ### Setup |
| 23 | |
| 24 | ```bash |
| 25 | git clone https://github.com/hugohe3/ppt-master.git |
| 26 | cd ppt-master |
| 27 | pip install -r requirements.txt |
| 28 | ``` |
| 29 | |
| 30 | ## Before You Open a PR |
| 31 | |
| 32 | PPT Master is solo-maintained with limited review bandwidth. To keep things healthy for everyone: |
| 33 | |
| 34 | - **Tiny fixes** (typos, one-line usage/doc corrections, obvious small inconsistencies) — please open an issue instead of a PR. A clear report is usually faster for the maintainer to apply directly |
| 35 | - **Translations & wording-only edits** — please open an issue rather than a PR. Like other tiny fixes, these are faster for the maintainer to apply directly, and unrequested translation files add ongoing sync burden without a clear owner. Translated governance docs (CONTRIBUTING, Code of Conduct) are intentionally not maintained as separate `_CN` files |
| 36 | - **Focused bug fixes** — PRs are welcome when the fix is self-contained, has clear reproduction steps, and includes local verification |
| 37 | - **Code-only changes** — self-contained fixes to scripts or script behavior, with no edits to prompt/instruction text, can go straight to a PR as long as they meet the focused-bug-fix bar above |
| 38 | - **Prompt / instruction changes require a prior issue** — edits to `SKILL.md`, `references/*.md`, `workflows/*.md`, or any other agent-facing instruction text **must be discussed and agreed in an issue *before* you open a PR**. These files steer AI behavior deck-wide, sit close to a fixed prompt-token budget, and restating a rule the docs already state rarely fixes a non-compliant agent — the fix usually belongs in the agent, not in more prompt text. PRs that touch prompt/instruction files without a prior agreed issue may be closed without detailed review |
| 39 | - **Substantial features, new backends, or new abstractions** — please open an issue first to discuss fit and direction. PRs submitted without prior discussion may be closed without detailed review |
| 40 | - **Refactors, structural changes, broad cleanup, or workflow changes** — open an issue first. The project deliberately stays close to its current shape |
| 41 | |
| 42 | This isn't gatekeeping — it protects your time. A PR should be a meaningful, independently reviewable change, not just a few lines the maintainer could patch faster from an issue report. A 500-line PR that doesn't match the project direction is worse for you than a 10-line issue comment that clarifies it upfront. |
| 43 | |
| 44 | ### AI-assisted PRs |
| 45 | |
| 46 | AI assistance is welcome — this project is itself AI-driven. But an AI-drafted PR you haven't personally reviewed is not a contribution; it's an unreviewed code dump: |
| 47 | |
| 48 | - **Purely AI-generated PRs submitted without human review will be closed unmerged.** Before opening a PR, read the full diff yourself, run the affected scripts, and confirm the problem described actually exists in this repository — not just that it sounds plausible. |
| 49 | - **Every factual claim in the PR description is yours, not the AI's.** A description that asserts failures in code paths the repository doesn't actually have (an AI-invented problem narrative) gets the PR closed regardless of diff quality. |
| 50 | - Read this file in full before opening a PR; the PR template asks you to confirm the points above. **The template has three confirmation checkboxes — if any one of them is left unchecked, the PR is closed without review.** |
| 51 | |
| 52 | ## What We Accept / What We Don't |
| 53 | |
| 54 | **Welcome:** |
| 55 | |
| 56 | - Bug fixes with clear reproduction |
| 57 | - New layout templates, chart templates, icons |
| 58 | - Documentation updates that materially improve an existing workflow, installation path, or troubleshooting path |
| 59 | - Additional image backends that follow the existing `image_backends/` pattern |
| 60 | - SVG quality improvements that stay within the declared constraints |
| 61 | |
| 62 | **Not a fit (please don't open PRs for these):** |
| 63 | |
| 64 | - Introducing `uv`, `poetry`, or other tools as required dependencies — `pip + requirements.txt` is the only official install path |
| 65 | - Adding CI, test frameworks, pre-commit hooks, or linting infrastructure — deliberately out of scope for a solo-maintained project |
| 66 | - Repackaging the skill as a CLI, SaaS, desktop app, or installer — PPT Master is a chat-driven skill for AI IDEs by design |
| 67 | - Architectural refactors or large-scale renames — incremental cleanup only |
| 68 | - "Drive-by" cosmetic reformatting unrelated to a real fix |
| 69 | - Pure translations or wording-only edits that were not requested or discussed first |
| 70 | - Changing a foundational setting — the MIT license, or DrawingML component reuse / template-fill in place of AI-generated shapes. These are deliberate founding choices and won't change midway |
| 71 | - Fixed numeric quotas to constrain generation (`max_cards` / `max_bullets` / `max_table_rows` and similar) — density is governed by narrative rhythm and one primary focus per page, not hard caps |
| 72 | - Post-processing that is quality smoothing rather than compatibility — we fix things that are broken/unusable if not done (e.g. AI-image size/format/alpha); "nicer if done" polish (loudness normalization, kerning) stays out. If a model or service falls short, the fix is to switch it, not to make the project adapt to it |
| 73 | - A new backend, path, or option that duplicates a capability the repo already provides — check current behavior first (e.g. OpenAI-compatible providers already run under `IMAGE_BACKEND=openai`) |
| 74 | |
| 75 | If you're unsure, open an issue to ask — that's always welcome. |
| 76 | |
| 77 | ## Contribution Workflow |
| 78 | |
| 79 | 1. **Fork** the repository and create a branch from `main` |
| 80 | 2. **One PR, one thing** — keep each PR focused on a single concern. If you notice unrelated improvements, open a separate PR |
| 81 | 3. **Write a useful PR description** — explain *what* changed and *why*, not just a diff summary. If your change fixes a bug, include reproduction steps |
| 82 | 4. **Test locally** before submitting — run the affected scripts and verify output |
| 83 | 5. **Don't overstate** — if your PR description claims tests or behavior changes, make sure the diff actually contains them |
| 84 | |
| 85 | ## Review Process |
| 86 | |
| 87 | - Reviews are best-effort, usually within a few days. Ping the PR if it's been a week without response |
| 88 | - Review feedback will be specific: what to change, and whether it's a blocker. If a PR needs more than ~2 rounds to converge, it may be closed with a note — reopening is fine once the direction is clearer |
| 89 | - Focused fixes may be merged as-is; larger contributions will usually be squash-merged to keep history readable |
| 90 | |
| 91 | ## SVG Guidelines |
| 92 | |
| 93 | If your contribution involves SVG files, follow the canonical authoring and |
| 94 | PPTX-compatibility contract in |
| 95 | [`shared-standards.md`](./skills/ppt-master/references/shared-standards.md). |
| 96 | This guide does not duplicate its required, forbidden, or conditional entries. |
| 97 | |
| 98 | Validate the affected SVG file or directory before submitting: |
| 99 | |
| 100 | ```bash |
| 101 | python3 skills/ppt-master/scripts/svg_quality_checker.py <file_or_directory> |
| 102 | ``` |
| 103 | |
| 104 | ## Reporting Bugs |
| 105 | |
| 106 | Open an issue on [GitHub Issues](https://github.com/hugohe3/ppt-master/issues) and include: |
| 107 | |
| 108 | - A clear description of the problem |
| 109 | - Steps to reproduce |
| 110 | - Expected vs. actual behavior |
| 111 | - Environment details (OS, Python version, AI editor used) |
| 112 | |
| 113 | ## Code of Conduct |
| 114 | |
| 115 | Please read and follow our [Code of Conduct](./CODE_OF_CONDUCT.md). |
| 116 | |
| 117 | ## License |
| 118 | |
| 119 | By contributing, you agree that your contributions will be licensed under the [MIT License](./LICENSE). |
| 120 |