75 lines
3.4 KiB
Markdown
75 lines
3.4 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.
|
|
|
|
## 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/ENGINEERING.md` before adding dependencies, bundled assets, PDF engines, runtimes, or broad architectural changes.
|
|
- Read `docs/WORKFLOW_AUDIT.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.
|
|
|
|
## 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.
|
|
- 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.
|
|
|
|
## 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.
|