Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
359 lines (253 loc) · 9.75 KB

CONTRIBUTING.md

File metadata and controls

359 lines (253 loc) · 9.75 KB
Raw

Contributing to ng2-pdfjs-viewer

Thank you for your interest in contributing to ng2-pdfjs-viewer! This document provides guidelines and information for contributors.

🤝 How to Contribute

Reporting Issues

  • 🐛 Bug Reports: Use GitHub Issues with the "bug" label
  • 💡 Feature Requests: Use GitHub Discussions for feature ideas
  • 📚 Documentation: Help improve our docs and examples

Pull Requests

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests if applicable
  5. Run the test suite (npm test)
  6. Commit your changes (git commit -m 'Add amazing feature')
  7. Push to the branch (git push origin feature/amazing-feature)
  8. Open a Pull Request

🛠️ Development Setup

Prerequisites

  • Node.js 18.0+
  • Angular CLI 20.0+
  • Git

Installation

# Clone the repository
git clone https://github.com/intbot/ng2-pdfjs-viewer.git
cd ng2-pdfjs-viewer

# Install dependencies
npm install

# Install playground dependencies
cd playground
npm install
cd ..

Getting the App Working

Important: Due to Angular's build cache, you may need to clear the cache before running the app:

# Clear Angular cache (Windows PowerShell)
Remove-Item -Recurse -Force "playground\.angular"

# Or manually delete the .angular folder in playground directory

Development Commands

# Build the library
npm run build

# Run the sample app
npm run start

# Run the complete test workflow (build → publish → update → install → run)
./test.bat

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

Testing Workflow

The project uses a comprehensive test workflow via test.bat:

  1. Build the library
  2. Publish to local npm registry
  3. Link the build into the playground (yalc)
  4. Install dependencies
  5. Run the playground

This ensures you're testing the actual built library, not just the source code.

Testing

# Run unit tests
npm test

# Run e2e tests
npm run e2e

# Run tests with coverage
npm run test:coverage

📝 Code Style

TypeScript

  • Use TypeScript strict mode
  • Follow Angular style guide
  • Use meaningful variable and function names
  • Add JSDoc comments for public APIs

HTML

  • Use semantic HTML elements
  • Follow Angular template best practices
  • Use Angular Material components when possible

CSS/SCSS

  • Use CSS custom properties for theming
  • Follow BEM methodology for class naming
  • Use responsive design principles
  • Avoid !important unless necessary

Git

  • Use conventional commit messages
  • Keep commits focused and atomic
  • Write descriptive commit messages

🏗️ Architecture

Project Structure

ng2-pdfjs-viewer/
├── lib/                          # Library source code
│   ├── src/                      # TypeScript source
│   │   ├── ng2-pdfjs-viewer.component.ts
│   │   ├── interfaces/
│   │   ├── managers/
│   │   └── utils/
│   ├── pdfjs/                    # PDF.js integration
│   │   └── web/
│   │       └── postmessage-wrapper.js
│   └── dist/                     # Built library
├── playground/                  # Demo app — feature explorer (Angular 22)
│   └── src/app/
│       ├── shell/               # App shell + command palette
│       ├── pages/               # One page per feature
│       └── core/                # Feature registry + services
├── README.md                     # Main documentation
├── CHANGELOG.md                  # Version history
└── CONTRIBUTING.md               # This file

Key Components

  • ng2-pdfjs-viewer.component.ts: Main Angular component
  • postmessage-wrapper.js: PDF.js integration layer
  • ActionQueueManager.ts: Action dispatching system
  • PropertyTransformers.ts: Data transformation utilities

🧪 Testing Guidelines

Unit Tests

  • Test all public methods and properties
  • Test error conditions and edge cases
  • Mock external dependencies
  • Aim for 80%+ code coverage

Integration Tests

  • Test component integration with PDF.js
  • Test event handling and communication
  • Test different PDF sources (URL, Blob, Uint8Array)

E2E Tests

  • Test complete user workflows
  • Test on different browsers
  • Test responsive behavior

📚 Documentation

Code Documentation

  • Add JSDoc comments for all public APIs
  • Include usage examples in comments
  • Document complex algorithms and logic

README Updates

  • Update feature lists when adding new features
  • Add usage examples for new functionality
  • Update installation and setup instructions

API Documentation

  • Document all input properties
  • Document all output events
  • Document all public methods
  • Include type information

Writing style

Docs and README copy should read like a maintainer wrote them — concrete and specific. CI enforces a house style on every PR: check-docs-voice.mjs scans the Markdown/MDX a PR adds and the PR's own title and body, and blocks filler and marketing-speak. A pre-commit hook runs the same check locally so you catch it before pushing — enable it once per clone:

git config core.hooksPath .githooks

It runs node scripts/check-docs-voice.mjs --staged on staged Markdown/MDX. The rules:

  • Lead with a concrete fact, number, or behavior, not an adjective.
  • Cut filler superlatives (seamless, effortless, blazing-fast, cutting-edge, world-class). Brand words (comprehensive, feature-rich, AI-enabled, mobile-first) are fine to use.
  • Keep a real voice: name trade-offs, state honest limits, write in first person where it fits.
  • Vary sentence length and structure; don't repeat an identical title-then-one-sentence shape.
  • Skip generic openers like Welcome to the … or In this guide we'll. Keep the code examples.

Run it on specific files anytime: node scripts/check-docs-voice.mjs README.md docs-website/docs/intro.md.

🚀 Release Process

Version Bumping

  • Use semantic versioning (MAJOR.MINOR.PATCH)
  • Update version in lib/package.json
  • Update CHANGELOG.md with new features
  • Create git tag for release

Publishing

Publishing is automated: pushing a v* tag triggers .github/workflows/main.yml, which builds lib/ and publishes to npm using trusted publishing (OIDC) with a provenance attestation — no long-lived npm token is stored in the repo.

# Cut a release (from lib/) — builds, commits, tags, and pushes the tag
cd lib
npm version patch   # or minor / major

For a local dry run you can still npm run build && npm run package in lib/ to produce the tarball without publishing.

One-time setup: npm trusted publisher (maintainer only)

Before the OIDC publish works, the ng2-pdfjs-viewer package must trust this repo's workflow:

  1. On npmjs.com → the ng2-pdfjs-viewer package → Settings → Trusted Publisher.
  2. Add a GitHub Actions publisher: organization intbot, repository ng2-pdfjs-viewer, workflow filename main.yml.
  3. Once configured, the legacy NPM_TOKEN repository secret can be deleted.

Provenance is generated automatically because this is a public repository.

Repository security & Dependabot

This repo ships only the lib/ package — it has zero runtime dependencies. The playground and demo app (playground/) and the docs site (docs-website/) are not published.

To keep the repository's security signal honest, Dependabot alerts for those non-shipped projects are auto-dismissed by a repository-level auto-triage rule that matches their manifest paths. This is configured once in Settings → Code security → Dependabot → Auto-triage rules (action: auto-dismiss; manifest path: playground/**, docs-website/**); the built-in "dismiss low-impact dev-scoped" preset is also enabled. Dependabot version-update PRs are scoped to /lib and the GitHub Actions workflows via .github/dependabot.yml. See SECURITY.md for the rationale.

🐛 Bug Reports

When reporting bugs, please include:

  1. Environment Information

    • Angular version
    • Node.js version
    • Browser and version
    • Operating system

  2. Reproduction Steps

    • Clear steps to reproduce the issue
    • Expected behavior
    • Actual behavior

  3. Code Example

    • Minimal code that reproduces the issue
    • Error messages or console output

  4. Additional Context

    • Screenshots if applicable
    • Related issues or discussions

💡 Feature Requests

When requesting features, please include:

  1. Use Case

    • Why is this feature needed?
    • How would it be used?

  2. Proposed Solution

    • How should it work?
    • Any design considerations?

  3. Alternatives

    • Have you considered other approaches?
    • Any workarounds currently available?

📋 Pull Request Template

## Description

Brief description of changes

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing

- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist

- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

🤔 Questions?

📄 License

By contributing to ng2-pdfjs-viewer, you agree that your contributions will be licensed under the Apache License 2.0.

Thank you for contributing to ng2-pdfjs-viewer! 🎉