Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
37 lines (23 loc) · 2.37 KB

CONTRIBUTING.md

File metadata and controls

37 lines (23 loc) · 2.37 KB

Contributing

Acquiring the specification document

Because the specification document is not freely available, it cannot be included in this repository directly. The specification document is downloadable on two different places:

  1. To get the most recent version, head to https://www.pdfa-inc.org/product/iso-32000-2-pdf-2-0-bundle-sponsored-access/
  2. If you are okay with a slightly older version without the need to share personal information, you can download it using this url: https://opensource.adobe.com/dc-acrobat-sdk-docs/standards/pdfstandards/pdf/PDF32000_2008.pdf

Adding a sample to prevent regressions

In the tests/Samples/files directory, create a new directory with a descriptive title. If you don't know what title to use, you can use the issue number like this: issue-1234. Place the sample file in this directory, and make sure that the file is named file.pdf. To create the content.yml file with the expected output, run the following command:

composer update-content

Debugging file encryption keys

To retrieve information about passwords and file encryption keys, it's useful to debug against a working implementation. We can use qpdf for that like this:

qpdf --show-encryption --show-encryption-key --password=knownPassword file.pdf

Use of comments

Code should be self-documenting, and if something can be clarified by giving a method, variable or class a clearer name or writing code more explicitly that should be done instead of adding comments.

Content in comments should not replicate content in code. There is no way to guarantee that the comment gets updated when the code gets updated.

If there are edge cases a piece of code accounts for, there should be a test with that explicit edge case instead of a comment. This way, the test case can be considered living documentation, and it has to be considered when the code under test is updated.

There are some acceptable reasons to add comments:

  • Something is done in a specific way that is not intuitive. In this case, the considerations should be put in the comments.
  • A unit of code can be referenced by multiple names. A comment can clarify the alternative name.
    • For example: a parameter for characterSpace is named Tc. To clarify the name, this package uses characterSpace internally. A comment clarifying that this references Tc in the specification makes sense.