Marmelator/pdf.js.mirror
1
0
Fork 0
mirror of https://github.com/mozilla/pdf.js.git synced 2026-07-27 01:17:22 +02:00
Code Issues Packages Projects Releases Wiki Activity

Textual fixes

Tim van der Meij 2014-02-02 14:12:35 -08:00
parent eedff6105b
commit 94a5698d56
1 changed files with 34 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
Contributing.md

@ -1,30 +1,30 @@
If you're not familiar with pdf.js first see the readme getting started section. If you are not familiar with PDF.js, then first take a look at the README's getting started section.
## Contributing Code ## Contributing Code
An overview how to contribute code to the pdf.js project. The basic workflow: An overview how to contribute code to the PDF.js project. The basic workflow:
1. fork 1. Fork
1. feature branch 1. Feature branch
1. make changes 1. Make changes
1. run lint and testing 1. Run lint and testing
1. push changes to your fork/branch 1. Push changes to your fork/branch
1. create pull request 1. Create pull request
1. code review & automated testing 1. Code review and automated testing
1. merge into the master 1. Merge into master
### The Bare Necessities ### The Bare Necessities
* git client * Git client
* github account * GitHub account
* [python](http://www.python.org/download/) * [Python](http://www.python.org/download/)
* [node](http://nodejs.org/) * [Node.js](http://nodejs.org/)
* (for Windows, see [[Setting up pdf.js Development Environment for Windows]]) * (for Windows, see [[Setting up pdf.js Development Environment for Windows]])
**Before you make any changes to the code you'll probably want jump down to [Generating Reference Images](#ref-images) to create the reference snapshot images so you can run the test framework and check for regressions.** **Before you make any changes to the code you'll probably want jump down to [Generating Reference Images](#ref-images) to create the reference snapshot images so you can run the test framework and check for regressions.**
If you're familiar with github and doing feature branches you can skip down to [Run Lint and Testing](#lint)... If you're familiar with GitHub and creating feature branches you can skip down to [Run Lint and Testing](#lint)...
### 1) Fork ### 1) Fork
To fork the repository you'll need to sign up for a github account. Once you have an account just click the little fork button up top. Now that you have your fork you'll need to clone it (replace `<YOUR USERNAME>`): To fork the repository you'll need to sign up for a GitHub account. Once you have an account just click the little fork button up top. Now that you have your fork you'll need to clone it (replace `<YOUR USERNAME>`):
``` ```
git clone git://github.com/<YOUR USERNAME>/pdf.js.git git clone git://github.com/<YOUR USERNAME>/pdf.js.git
``` ```
@ -42,19 +42,19 @@ git checkout -b type3fontsupport upstream/master
``` ```
### 3) Changes ### 3) Changes
Now that you have new branch created you can edit/add/delete files. Follow the standard git workflow to stage and locally commit your changes -- there are lots of guides that explain git. Now that you have new branch created you can edit/add/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 rebase option or follow the [[Squashing Commits]] instructions. 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 [[Squashing Commits]] instructions.
### <a id="lint"></a> 4) Run Lint and Testing ### <a id="lint"></a> 4) Run Lint and Testing
**Run Lint** **Run Lint**
Make sure your code follows our style guides, run from the pdf.js folder: Make sure your code follows our style guides and run from the PDF.js folder:
``` ```
node make lint node make lint
``` ```
First time you run the command above, the jshint will be automatically installed in the pdf.js folder. The first time you run the command above, jshint will be automatically installed in the PDF.js folder.
***Protip***: If you are a Vim user, then install [syntastic](http://www.vim.org/scripts/script.php?script_id=2736) and add the following line to your `.vimrc`: ***Protip***: If you are a Vim user, then install [syntastic](http://www.vim.org/scripts/script.php?script_id=2736) and add the following line to your `.vimrc`:
@ -62,20 +62,20 @@ First time you run the command above, the jshint will be automatically installed
let g:syntastic_javascript_checker = "jshint" let g:syntastic_javascript_checker = "jshint"
``` ```
Now you have automatic linting of your changes to javascript files whenever you save. Now you have automatic linting of your changes to JavaScript files whenever you save.
**Run Testing** **Run Testing**
To ensure your changes didn't introduce any regressions you'll need to run the testing framework. There are four basic types of tests: To ensure your changes didn't introduce any regressions you need to run the testing framework. There are four basic types of tests:
* load - just checks if the pdf file can be loaded without crashing * load - just checks if the PDF file can be loaded without crashing
* eq - a reference test which takes correctly rendered snapshots and compares them to the snapshots created by the current code * eq - a reference test which takes correctly rendered snapshots and compares them to the snapshots created by the current code
* fbf - a forward back forward test * fbf - a forward back forward test
* unit tests - jasmine unit tests that are run separately from the above tests * unit tests - Jasmine unit tests that are run separately from the above tests
<a id="ref-images"></a>**Generating Reference Images** <a id="ref-images"></a>**Generating Reference Images**
The reference tests require you to generate the original snapshots for comparison. The snapshots should be generated before you make any changes. If you have already made some changes `git stash` your work. Then make sure you have setup a browser_manifest file. There are templates located in `test/resources/browser_manifests/`. Copy one of the templates (replace `<your os>` with mac, linux, or win). The reference tests require you to generate the original snapshots for comparison. The snapshots should be generated before you make any changes. If you have already made some changes, `git stash` your work. Then make sure you have setup a `browser_manifest` file. There are templates located in `test/resources/browser_manifests/`. Copy one of the templates (replace `<your os>` with Mac, Linux or Windows).
``` ```
cp test/resources/browser_manifests/browser_manifest.json.<your os> test/resources/browser_manifests/browser_manifest.json cp test/resources/browser_manifests/browser_manifest.json.<your os> test/resources/browser_manifests/browser_manifest.json
@ -88,7 +88,7 @@ Now we can generate the reference images:
cd test/ cd test/
python test.py -m --browserManifestFile=resources/browser_manifests/browser_manifest.json python test.py -m --browserManifestFile=resources/browser_manifests/browser_manifest.json
``` ```
You can then run the test suite from the pdf.js root folder: You can then run the test suite from the PDF.js root folder:
``` ```
node make test node make test
@ -96,27 +96,27 @@ node make test
**Running Unit Tests Separately** **Running Unit Tests Separately**
Unit tests are run when `node make test` is run but they can also be run separately two different ways: Unit tests are run when `node make test` is run, but they can also be run separately two different ways:
1. In browser - A web server has to be setup to host the pdf.js files. Tests will be executed by opening the _\<url-to-pdf.js\>_/test/unit/unit_test.html page. If the web server is created by using `node make server` command, the URL will be http://localhost:8888/test/unit/unit_test.html. 1. In browser - A web server has to be setup to host the PDF.js files. Tests will be executed by opening the _\<url-to-pdf.js\>_/test/unit/unit_test.html page. If the web server is created by using `node make server` command, the URL will be http://localhost:8888/test/unit/unit_test.html.
2. Command Line - `node make unittest` which will run all the test using the regression test framework. 2. Command Line - `node make unittest` which will run all the test using the regression test framework.
### 5) Push Changes ### 5) Push Changes
After lint and all tests pass, push changes to your fork/branch on github: After lint and all tests pass, push the changes to your fork/branch on GitHub:
``` ```
git push origin type3fontsupport git push origin type3fontsupport
``` ```
### 6) Pull Request ### 6) Pull Request
Create a pull request on github for your feature branch. The code will then be reviewed and tested further by our pdfbot. Create a pull request on GitHub for your feature branch. The code will then be reviewed and tested further by our bot.
### 7) Code Review & Further Testing ### 7) Code Review and Further Testing
In addition to the github pull request workflow, it's highly recommended that you setup some form of communication with pdf.js team via #pdfjs IRC channel at irc.mozilla.org or e-mail. That will help to find a reviewer for your patch and speed up the review process. In addition to the GitHub pull request workflow, it's highly recommended that you setup some form of communication with the PDF.js team via the #pdfjs IRC channel at irc.mozilla.org or e-mail. That will help to find a reviewer for your patch and speed up the review process.
A collaborator will kick off further testing and do a code review. A collaborator will kick off further testing and do a code review.
### 8) Merging to Master ### 8) Merging to master
If all goes well a collaborator will merge all your changes into the main repo. If all goes well, a collaborator will merge all your changes into the main repository.
## Useful artifacts ## Useful artifacts