diff --git a/Contributing.md b/Contributing.md index 1a42064..d669c26 100644 --- a/Contributing.md +++ b/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 -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. feature branch -1. make changes -1. run lint and testing -1. push changes to your fork/branch -1. create pull request -1. code review & automated testing -1. merge into the master +1. Fork +1. Feature branch +1. Make changes +1. Run lint and testing +1. Push changes to your fork/branch +1. Create pull request +1. Code review and automated testing +1. Merge into master ### The Bare Necessities -* git client -* github account -* [python](http://www.python.org/download/) -* [node](http://nodejs.org/) +* Git client +* GitHub account +* [Python](http://www.python.org/download/) +* [Node.js](http://nodejs.org/) * (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.** -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 -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 ``): +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 ``): ``` git clone git://github.com//pdf.js.git ``` @@ -42,19 +42,19 @@ git checkout -b type3fontsupport upstream/master ``` ### 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. ### 4) Run Lint and Testing **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 ``` -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`: @@ -62,20 +62,20 @@ First time you run the command above, the jshint will be automatically installed 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** -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 * 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 **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 `` 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 `` with Mac, Linux or Windows). ``` cp test/resources/browser_manifests/browser_manifest.json. test/resources/browser_manifests/browser_manifest.json @@ -88,7 +88,7 @@ Now we can generate the reference images: cd test/ 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 @@ -96,27 +96,27 @@ node make test **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 _\_/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 _\_/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. ### 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 ``` ### 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 -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. +### 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 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. -### 8) Merging to Master -If all goes well a collaborator will merge all your changes into the main repo. +### 8) Merging to master +If all goes well, a collaborator will merge all your changes into the main repository. ## Useful artifacts