path: root/CONTRIBUTING-CODE.adoc

= Contributing Code
// Settings:
:experimental:
:idprefix:
:idseparator: -
ifndef::env-github[:icons: font]
ifdef::env-github,env-browser[]
:toc: macro
:toclevels: 1
endif::[]
ifdef::env-github[]
:!toc-title:
:caution-caption: :fire:
:important-caption: :exclamation:
:note-caption: :paperclip:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]
// Aliases:
:project-name: Asciidoctor PDF
:project-handle: asciidoctor-pdf
// URLs:
:url-asciidoctor: http://asciidoctor.org
:url-project: https://github.com/asciidoctor/asciidoctor-pdf
:url-project-repo: {url-project}
:url-project-issues: {url-project-repo}/issues
:url-project-list: https://discuss.asciidoctor.org
:url-rvm: http://rvm.io

This guide provides all the information you need to become a successful Asciidoctor PDF developer and code contributor!
You'll learn how to retrieve the code from GitHub, execute the tests, build and install the gem, and run the application with your local modifications.

toc::[]

== Guidelines

To contribute code, fork the project on GitHub, hack away, and send a pull request with your proposed changes.
*All pull requests must include a) tests that verify the code change and b) an entry in the CHANGELOG.adoc file to document what changed.*
If a pull request is missing tests or a CHANGELOG entry, *it will not be merged*.

Feel free to use the {url-project-issues}[issue tracker] or {url-project-list}[Asciidoctor mailing list] to provide feedback or suggestions in other ways.

Follow the instructions below to learn how to clone the source and run it from your local copy.

== Development

=== Retrieve the Source Code

You can retrieve the source of {project-name} in one of two ways:

. Clone the git repository
. Download a zip archive of the repository

==== Option 1: Fetch Using Git

If you want to clone the git repository, simply copy the {url-project-repo}[GitHub repository URL] and pass it to the `git clone` command:

 $ git clone https://github.com/asciidoctor/asciidoctor-pdf

Next, change to the project directory:

 $ cd asciidoctor-pdf

==== Option 2: Download the Archive

If you want to download a zip archive, click the btn:[Download Zip] button on the right-hand side of the repository page on GitHub.
Once the download finishes, extract the archive, open a console and change to that directory.

TIP: Instead of working out of the {project-handle} directory, you can simply add the absolute path of the [path]_bin_ directory to your `PATH` environment variable.

We'll leverage the project configuration to install the necessary dependencies.

=== Install Dependencies

We recommend using {url-rvm}[RVM] to manage the installation of Ruby you'll use to build and develop the project.

 $ rvm use 2.6

The dependencies needed to use {project-name} are defined in the [.path]_Gemfile_ at the root of the project.
We can use Bundler to install the dependencies for us.

To check you have Bundler available, use the `bundle` command to query the installed version:

 $ bundle --version

If it's not installed, use the `gem` command to install it.

 $ gem install bundler

Then use the `bundle` command with the `--path` option to install the project dependencies into the project:

 $ bundle --path=.bundle/gems

NOTE: You must call `bundle` from the project directory so that it can find the [.path]_Gemfile_.

=== Run the Tests

Tests are written using RSpec.
To run the tests, simply invoke rspec via bundler.

 $ bundle exec rspec

To disable the visual integration tests, pass the `` option:

 $ bundle exec rspec -t ~visual

If a visual integration test fails, you can instruct the test suite to keep the files in the [.path]_spec/output_ directory by setting the `DEBUG` environment variable:

 $ DEBUG=true bundle exec rspec -t visual

If you want to see the name of each test as it is run, add the `-fd` option:

 $ bundle exec rspec -fd

You can also use the provided Rake task (note the name difference):

 $ bundle exec rake spec

Running tests using `rspec` directly gives you the advantage of being able to specify additional options.

To run a single test, you can filter by the name of the test.
For example, to run all tests that pertain to failures, use:

 $ bundle exec rspec -e fail

To run all tests that have `wip` in the name, use:

 $ bundle exec rspec -e wip

You can also run all tests in a given file by passing the file's path to rspec:

 $ bundle exec rspec spec/toc_spec.rb

For a full list of options that rspec provides, run `rspec -h`.

=== Run the Application (optional)

Like with Bundler, you have to run the application from the project directory.
Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script using Ruby:

 $ bundle exec asciidoctor-pdf -v

If you see the version of {project-name} printed, you're ready to use {project-name}!

You can use the application to convert a document as follows:

 $ bundle exec asciidoctor-pdf /path/to/sample.adoc

=== Install the Application (optional)

If you want to install the application globally so you can run it anywhere, use the following `rake` task:

 $ bundle exec rake install

This task will package the gem and install it into your system gems.

If you want to install the gem using a separate command, first use the following `rake` task to build it:

 $ rm -rf pkg
   bundle exec rake build

This task packages the application as a gem and writes it to the [.path]_pkg_ directory.
A message will be printed to the console telling you the exact filename.
You can now use the `gem install` command to install it.

 $ gem install pkg/*.gem

You'll want to pay attention to which Ruby installation you are installing the gem into.
If successful, the `asciidoctor-pdf` executable will be available on your PATH.

endif::[]

=== Test a Pull Request

To test a pull request (PR), you first need to fetch the branch that contains the change and switch to it.
The steps below are covered in detail in the https://help.github.com/articles/checking-out-pull-requests-locally[GitHub help].

Let's assume you want to test PR 955.
Here's how you fetch and switch to it:

 $ git fetch origin pull/955/head:pr-955-review
   git checkout pr-955-review

IMPORTANT: Make sure you replace the number with the number of the PR you want to test.

In case any dependencies have changed, you should run the `bundle` command again:

 $ bundle

Now you can run the application as modified by the PR:

 $ bundle exec asciidoctor-pdf /path/to/sample.adoc

To switch back to master, just type:

 $ git checkout master

=== Generate Code Coverage Report

To generate a code coverage report when running tests using simplecov, set the `COVERAGE` environment variable as follows when running the tests:

 $ COVERAGE=true bundle exec rake spec

You'll see a total coverage score as well as a link to the HTML report in the output.
The HTML report helps you understand which lines and branches were missed, if any.

Despite being fast, the downside of using simplecov is that it misses code branches.
You can use deep-cover instead of simplecov to generate a more thorough report.
To do so, set the `COVERAGE` environment variable to `deep` when running the tests:

 $ COVERAGE=deep bundle exec rake spec

You'll see a total coverage score, a detailed coverage report, and a link to HTML report in the output.
The HTML report helps you understand which lines and branches were missed, if any.

////
As an alternative to deep cover's native HTML reporter, you can also use istanbul / nyc.
First, you'll need to have the `nyc` command available on your system:

 $ npm install -g nyc

Next, in addition to the `COVERAGE` environment variable, also set the `DEEP_COVER_REPORTER` environment variable as follows when running the tests:

 $ COVERAGE=deep DEEP_COVER_REPORTER=istanbul bundle exec rake spec

You'll see a total coverage score, a detailed coverage report, and a link to HTML report in the output.
The HTML report helps you understand which lines and branches were missed, if any.
////

=== Rebuild the Formatter Text Parser

The formatted text is first converted to a pseudo-HTML language, then converted from there into Prawn text fragments using a https://github.com/cjheath/treetop[treetop] parser.
treetop is a Ruby-based parsing DSL based on parsing expression grammars.
This strategy allows the converter to manipulate the formatted text without needing the know the internal details of how Prawn arranges text fragments.
It also allows Asciidoctor to behave in a consistent manner, since some of the inline parsing in Asciidoctor assumes that the converter is generating an SGML-based language like HTML or DocBook.

The parsing expression grammar is defined in the source file [.path]_lib/asciidoctor/pdf/formatted_text/parser.treetop_.
If you make a change to this file, you must regenerate the parser, which is defined in the source file _lib/asciidoctor/pdf/formatted_text/parser.rb_.
(Don't modify the generated parser directly).

Use the following command to regenerate the parser:

 bundle exec tt lib/asciidoctor/pdf/formatted_text/parser.treetop

You then need to commit both files.