Contributing
If you are not familiar with PDF.js, then first take a look at the README's getting started section.
Below is an overview of how to contribute code to the PDF.js project. The basic workflow is as follows:
- Fork
- Create feature branch
- Make changes
- Run lint and testing
- Push changes to your fork/branch
- Create pull request
- Code review and automated testing
- Merge into master
- Git client
- GitHub account
- Node.js
- Gulp (via
npm install -g gulp-cli) - An ES6 compatible browser
If you develop on Windows, read Setting up pdf.js Development Environment for Windows. For font testing you will need Python.
Before you make any changes to the code you will probably want to jump down to the "Generating reference images" section to create the reference snapshot images so you can run the test framework and check for regressions.
If you are familiar with GitHub and creating feature branches you can skip down to the "Run lint and testing" section.
To fork the repository you need to have a GitHub account. Once you have an account you can click the fork button up top. Now that you have your fork you need to clone it (replace {username} with your GitHub username) using
git clone git://github.com/{username}/pdf.js.git
cd pdf.js
and pull additional libraries and tools:
git submodule init
git submodule update
npm install
It is useful to have the upstream repository registered as well using
git remote add upstream git://github.com/mozilla/pdf.js.git
and periodically fetch it using git fetch upstream.
We always work with feature branches. For example, to create and switch to branch use:
git checkout -b {branch_name} upstream/master
and replace {branch_name} with a meaningful name that describes your feature or change. For instance,
if you are working on adding support for Type3 fonts, a good branch name would be type3-font-support.
Now that you have a new branch you can edit/create/delete files. Follow the standard Git workflow to stage and locally commit your changes -- there are lots of guides that explain Git.
If the branch contains lot of small commits, you might be asked to squash the commits. You can use Git's rebase option or follow the instructions on the Squashing Commits page.
Run lint
To make sure that your code follows our Style Guide, run the following command from the PDF.js folder:
gulp lint
If there are errors, some of them can be fixed automatically by the linting tool. To do so, run the following command:
gulp lint --fix
Protip: If you are a Vim user, then install Syntastic, install ESLint globally using npm install -g eslint and add the following line to your .vimrc:
let g:syntastic_javascript_checkers=['eslint']
Now you have automatic linting of your changes to JavaScript files whenever you save.
Run testing
To ensure that your changes did not introduce any regressions you need to run the testing framework. We have three different kinds of tests:
- Unit tests (ensure that individual units of code work as expected)
- Font tests (special kind of unit tests that use
ttxfor font validation) - Browser tests (screenshot testing of rendered PDF files in the browser)
The browser tests are split into the following types of tests:
-
loadtest (checks if the PDF file can be loaded without crashing) -
eqtest (reference test that takes correctly rendered snapshots and compares them to snapshots from the current code) -
texttest (reference test that takes snapshots of the text layer overlay and compares them to snapshots from the current code) -
annotationstest (reference test that takes snapshots of the annotation layer overlay and compares them to snapshots from the current code) -
fbftest (forward-back-forward test)
Generating reference images
The reference tests require you to generate original snapshots for comparison. The snapshots should be generated before you make any changes. If you have already made some changes, either git stash your work or checkout the master branch. Now we can generate the reference images:
gulp makeref
You can then run the test suite from the PDF.js root folder after unstashing any changes or going back to your feature branch:
gulp test
If you wish to add a reference test for your patch, you can place the file (foo.pdf in this example) in the test/pdfs directory and run the following script from the PDF.js root folder to add it to the suite:
node test/add_test.js test/pdfs/foo.pdf
Note that this script only supports adding eq tests for all pages of the PDF file. If you need a different type or page range, you'll need to update the test/test_manifest.json file afterwards.
Running unit tests separately
Unit tests are run when gulp test is run, but they can also be run separately using:
gulp unittest
After linting and testing passes, push the changes to your branch on GitHub:
git push origin {branch_name}
Create a pull request on GitHub for your feature branch. The code will then be reviewed and tested further by our contributors and the test bots.
Note that the translations for PDF.js in the l10n folder are synchronized with the Nightly branch of Mozilla Firefox. This means that we will only accept pull requests that add strings currently missing in the Nightly branch, but keep in mind that the changes will be overwritten when we synchronize again.
In addition to the GitHub pull request workflow, it is recommended that you communicate with the PDF.js team, for example via the Matrix room. That will help to find a reviewer for your patch and speed up the review process. The reviewer will kick off further testing and do a code review.
You can speed up fetching a remote GitHub branch (possibly belonging to another user) using git try {username} {branch_name}. Add the following to the .git/config file to be able to do that:
[alias]
try = !sh -c 'IFS=\":\" read -ra ARGS <<< \"$0\" && git fetch https://github.com/${ARGS[0]}/pdf.js.git ${ARGS[1]} && git checkout FETCH_HEAD'
If all goes well, a collaborator will merge your changes into the main repository.