| 1 | # Contributing to pdfkit
|
| 2 |
|
| 3 | ## Table of Contents
|
| 4 |
|
| 5 | - [Contributing to pdfkit](#contributing-to-pdfkit)
|
| 6 | - [Table of Contents](#table-of-contents)
|
| 7 | - [Code Organization](#code-organization)
|
| 8 | - [Setting Up the project locally](#setting-up-the-project-locally)
|
| 9 | - [Running and writing tests](#running-and-writing-tests)
|
| 10 | - [Submitting a Pull Request](#submitting-a-pull-request)
|
| 11 |
|
| 12 |
|
| 13 | ## Code Organization
|
| 14 |
|
| 15 | pdfkit is organized in the following folders:
|
| 16 |
|
| 17 | - `lib`: The actual source code.
|
| 18 | - `js`: The built / distributable code.
|
| 19 | - `docs`: Code and artifacts to generate documentation.
|
| 20 | - `demo`: Node and browser demos.
|
| 21 | - `tests/unit`: Tests behavior of specific classes / methods.
|
| 22 | - `tests/integration`: Compare the pdf output against a reference.
|
| 23 |
|
| 24 | **Working on your first Pull Request?** You can learn how from this _free_ series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)
|
| 25 |
|
| 26 | ## Setting Up the project locally
|
| 27 |
|
| 28 | To install the project you need to have `node`
|
| 29 |
|
| 30 | 1. [Fork](https://help.github.com/articles/fork-a-repo/) the project, clone your fork:
|
| 31 |
|
| 32 | ```
|
| 33 | # Clone your fork
|
| 34 | git clone https://github.com/<your-username>/pdfkit.git
|
| 35 |
|
| 36 | # Navigate to the newly cloned directory
|
| 37 | cd pdfkit
|
| 38 | ```
|
| 39 |
|
| 40 | 2. `npm install` to install dependencies
|
| 41 | 3. `npm run build` to build the library
|
| 42 | 4. `npm run demo` to run the demo (check demo/out.pdf)
|
| 43 | 5. `npm run demo-browser` to run the browser demo (check demo/browser.html)
|
| 44 |
|
| 45 | > Tip: Keep your `master` branch pointing at the original repository and make
|
| 46 | > pull requests from branches on your fork. To do this, run:
|
| 47 | >
|
| 48 | > ```
|
| 49 | > git remote add upstream https://github.com/foliojs/pdfkit.git
|
| 50 | > git fetch upstream
|
| 51 | > git branch --set-upstream-to=upstream/master master
|
| 52 | > ```
|
| 53 | >
|
| 54 | > This will add the original repository as a "remote" called "upstream,"
|
| 55 | > then fetch the git information from that remote, then set your local `master`
|
| 56 | > branch to use the upstream master branch whenever you run `git pull`.
|
| 57 | > Then you can make all of your pull request branches based on this `master`
|
| 58 | > branch. Whenever you want to update your version of `master`, do a regular
|
| 59 | > `git pull`.
|
| 60 |
|
| 61 | ## Running and writing tests
|
| 62 |
|
| 63 | Tests are run using [Jest](http://jestjs.io/) and are categorized as integration and unit tests.
|
| 64 |
|
| 65 | Integration tests check the pdf output against a reference stored as snapshots. While is served well to avoid regressions it has some disadvantages like small (correct) changes requiring to update all snapshots
|
| 66 |
|
| 67 | Unit tests checks behavior os specific classes / methods isolatedly. It covers relatively small portion of code but is preferred way of writing new tests going forward
|
| 68 |
|
| 69 | Tests commands
|
| 70 | * `npm run test`: Run all tests
|
| 71 | * `npm run test:unit`: Run unit tests
|
| 72 | * `npm run test:integration`: Run integration tests
|
| 73 |
|
| 74 | To write new tests, look for the *.spec.js files at `test/unit` and `test/integration` as examples
|
| 75 |
|
| 76 |
|
| 77 | ## Submitting a Pull Request
|
| 78 |
|
| 79 | Please go through existing issues and pull requests to check if somebody else is already working on it.
|
| 80 |
|
| 81 | Also, make sure to run the tests and lint the code before you commit your changes.
|
| 82 |
|
| 83 | **Preferentially, tests should be added to check the changed behavior even if is a bug fix. Unit tests are preferred over integration ones**
|