Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
100 lines (73 loc) · 4.54 KB

CONTRIBUTING.md

File metadata and controls

100 lines (73 loc) · 4.54 KB
Raw

Contributing to PdfiumRaster

Bug reports, documentation fixes, tests, and focused rendering improvements are welcome.

PdfiumRaster is deliberately a PDF-to-image library. Proposals for PDF editing, text extraction, form filling, signing, or viewer UI are outside the project's scope.

Report A Bug

Search the existing GitHub issues before opening a new one. Include enough information to reproduce the problem:

  • PdfiumRaster version
  • .NET runtime and operating system
  • Runtime identifier and processor architecture
  • Input type used (path, stream, byte array, or Base64)
  • Render and encoding options
  • Exception type, message, and stack trace
  • A minimal PDF when it can be shared safely

Do not attach confidential PDFs. If a report may involve a security vulnerability, follow SECURITY.md instead of opening a public issue.

Propose A Change

Open an issue before investing in a large API or architectural change. Describe the use case and why the existing API does not cover it. Small fixes can go directly to a pull request.

Public APIs must remain compatible after release. Prefer a new overload over changing the behavior of an existing method.

Build And Test

The .NET 10 SDK is required for the current test and benchmark projects. The library itself targets netstandard2.1.

make restore
make build
make test
make coverage

NuGet lock files are committed for reproducible CI and release builds. After intentionally changing a package version, run make restore and include the resulting packages.lock.json updates in the same pull request.

make test runs the tracked test suite. To test a private or large annotation-heavy document, place it at tests/PdfiumRaster.Tests/TestAssets/annotations.pdf; that path is ignored by Git. Then run:

make test-local

Before submitting packaging or release changes, also run:

make pack
make inspect-package

make coverage collects Cobertura coverage for the library and enforces at least 80% line coverage. Property-based tests exercise managed input and rendering invariants with generated values. Random malformed PDFs must not be fuzzed inside the normal test host because a native PDFium failure can terminate that process; use a separately supervised worker with explicit time, memory, and crash limits for native-input fuzzing.

If a change affects rendering speed or memory use, run the relevant target documented in docs/PERFORMANCE.md. Benchmark results should include the machine, operating system, .NET version, input asset, and exact command.

Dependency Updates

Dependabot checks for NuGet package updates every Monday at 06:00 and GitHub Actions updates every Monday at 06:30. Both times use the Europe/Amsterdam time zone. The exact update groups and pull request limits are defined in .github/dependabot.yml.

Dependabot pull requests run the same cross-platform CI workflow as other pull requests, plus the dependency review workflow. Dependency review rejects newly introduced vulnerabilities of moderate or greater severity. Security updates are grouped separately from routine minor and patch updates where Dependabot supports grouping them.

Code Guidelines

  • Keep library code in src/PdfiumRaster and target netstandard2.1.
  • Keep nullable reference types enabled and validate public arguments.
  • Add useful XML documentation to every public type, member, enum value, and overload.
  • Keep production builds warning-free; compiler warnings are treated as errors by the library project.
  • State whether page values are zero-based indexes or 1-based numbers.
  • State units such as pixels, PDF points, and DPI, plus stream ownership and material memory behavior.
  • Keep all native PDFium calls in PdfiumNative and serialized through the shared lock.
  • Root callback delegates and unmanaged structures for the complete native lifetime.
  • Use central package versions in Directory.Packages.props.
  • Update README.md and docs/API.md when public behavior changes.

For large files, preserve the existing behavior: paths and seekable streams use random access without a full managed copy; buffering a non-seekable stream is acceptable because PDFium requires random access.

Pull Requests

Keep pull requests focused. Explain the user-visible change, implementation tradeoffs, and how it was verified. Add tests for new public behavior and native lifetime changes. Generated output, benchmark artifacts, IDE files, and local test PDFs must not be committed.