90 lines
4.8 KiB
Markdown
90 lines
4.8 KiB
Markdown
# Contributing To I Hate PDFs
|
|
|
|
I Hate PDFs is a native macOS app for local PDF reading and annotation. Contributions should preserve that direction: small bundle, native system frameworks, local files, no account requirement, no analytics, and no cloud upload.
|
|
|
|
By contributing, you agree that your contribution is licensed under GNU General Public License version 2 only.
|
|
|
|
Vibe coded pull requests are welcome. This is a vibe coded repo, but vibe coded does not mean unreviewed: every change must be understandable, documented, tested at the right level, and held to the same strict QA bar as hand-written code.
|
|
|
|
## Before You Start
|
|
|
|
- Check existing issues and pull requests before starting duplicate work.
|
|
- Open an issue first for large UI changes, new dependencies, release-process changes, or features that affect PDF saving/export behavior.
|
|
- Read `docs/QA.md` before changing a user workflow.
|
|
- Read `docs/RELEASE.md` before preparing a release.
|
|
|
|
## Development
|
|
|
|
Requirements:
|
|
|
|
- macOS 13 or newer
|
|
- Xcode 15 or newer with command line tools
|
|
- Swift Package Manager
|
|
|
|
Useful local commands:
|
|
|
|
```sh
|
|
swift run IHatePDFs
|
|
swift test
|
|
swift build -c release
|
|
scripts/build-app.sh
|
|
scripts/make-dmg.sh
|
|
scripts/verify-release-artifacts.sh
|
|
```
|
|
|
|
Run the checks that match your change and list them in the pull request. If you skip a relevant check, say why.
|
|
|
|
## Engineering Policy
|
|
|
|
- Build with Swift, SwiftUI, AppKit, PDFKit, and system frameworks that ship with macOS.
|
|
- Do not replace the app with Electron, Chromium, a web runtime, a bundled JavaScript shell, or a cross-platform UI toolkit.
|
|
- Do not bundle a PDF renderer, OCR engine, database, scripting runtime, or large framework when a macOS system API can satisfy the requirement.
|
|
- Keep third-party dependencies at or near zero. Any new package must justify shipped size, runtime cost, maintenance cost, and why system APIs are insufficient.
|
|
- Keep assets minimal. Avoid large raster images, fonts, sample PDFs, videos, model files, or generated resources in the app bundle.
|
|
- Keep expensive work page-scoped or lazy when possible.
|
|
- Treat release-size growth as a product regression. Each direct-download per-architecture installer must stay under 400,000 bytes.
|
|
- Run `scripts/make-tiny-archives.sh` before release-impacting changes; it builds and checks the per-architecture archives.
|
|
|
|
## Pull Request Policy
|
|
|
|
- Keep each pull request focused on one behavior, bug fix, or documentation change.
|
|
- Explain the user-visible behavior change, not only the implementation detail.
|
|
- For vibe coded changes, say so in the pull request and describe what you reviewed manually before opening it.
|
|
- Link the issue when one exists.
|
|
- Update `CHANGELOG.md` for user-visible changes.
|
|
- Avoid unrelated formatting churn.
|
|
- Do not add a new dependency, bundled asset, PDF engine, runtime, or release artifact without explaining the size and maintenance impact.
|
|
- Preserve the app's local-first privacy model.
|
|
- Document the before/after behavior clearly enough that a maintainer can review the intent without reverse-engineering the diff.
|
|
- Include the QA commands and manual checks that prove the change works.
|
|
|
|
## UI Screenshot Policy
|
|
|
|
Every pull request that changes visible UI must include screenshots or a short screen recording in the pull request description.
|
|
|
|
For UI changes:
|
|
|
|
- Include before and after screenshots when changing an existing screen.
|
|
- Include at least one screenshot when adding a new screen, state, toolbar item, sidebar, popover, dialog, menu, or empty state.
|
|
- Cover light and dark mode when the change affects colors, contrast, icons, materials, or selection states.
|
|
- Cover narrow window behavior when the change affects layout or toolbar/sidebar density.
|
|
- Keep every screenshot, recording, and committed media file under 1 MB.
|
|
|
|
If a UI change cannot be captured meaningfully, explain that in the pull request.
|
|
|
|
## Size Policy
|
|
|
|
The app is intentionally small. Pull requests should keep source, assets, and release artifacts lean.
|
|
|
|
- Each committed screenshot, recording, fixture image, or other media file added or changed in a pull request must be less than 1 MB.
|
|
- Prefer cropped screenshots that show the changed UI instead of full-desktop captures.
|
|
- Prefer compressed PNG, JPEG, or WebP where appropriate.
|
|
- Do not commit raw screen recordings, large sample PDFs, generated archives, `.app` bundles, `.dmg` files, or App Store packages.
|
|
- Explain any app-size increase caused by assets, dependencies, or release packaging changes.
|
|
|
|
The `media-size.yml` workflow checks changed media files in pull requests. PR description attachments are still governed by this policy even though GitHub Actions cannot inspect them.
|
|
|
|
## Review Expectations
|
|
|
|
Maintainers may ask for smaller scope, screenshots, reduced assets, additional tests, or release-size justification before merging. Release submission and App Store upload decisions stay with the maintainers.
|