Skip to content

Latest commit

 

History

History
129 lines (97 loc) · 4.74 KB

CONTRIBUTING.adoc

File metadata and controls

129 lines (97 loc) · 4.74 KB
Raw

Contributing

Submitting an Issue

We use the issue tracker on GitHub associated with this project to track bugs and features. Before submitting a bug report or feature request, check to make sure it hasn’t already been submitted. When submitting a bug report, please include a Gist that includes any details that may help reproduce the bug, including your gem version, Ruby version, and operating system.

Most importantly, since Asciidoctor is a text processor, reproducing most bugs requires that we have some snippet of text on which Asciidoctor exhibits the bad behavior.

An ideal bug report would include a pull request with failing specs.

Submitting a Pull Request

  1. Fork the repository.

  2. Run bundle install to install dependencies.

  3. Create a topic branch.

  4. Add tests for your unimplemented feature or bug fix. (See Writing and Executing Tests)

  5. Run bundle exec rake to run the tests. If your tests pass, return to step 3.

  6. Implement your feature or bug fix.

  7. Run bundle exec rake to run the tests. If your tests fail, return to step 5.

  8. Add documentation for your feature or bug fix.

  9. If your changes are not 100% documented, go back to step 7.

  10. Add, commit, and push your changes.

  11. Submit a pull request.

For ideas about how to use pull requests, see the post Useful GitHub Patterns.

Writing and Executing Tests

Tests live inside the test directory and are named <topic>_test.rb. For instance, tests for the different types of blocks can be found in the file test/blocks_test.rb.

Within a test file, individual test cases are organized inside of contexts. A context is type of logical container that groups related tests together.

Each test case follows the same structure:

test 'description of test' do
  # test logic
end

At the moment, the tests are quite primitive. Here’s how a typical test operates:

  1. Defines sample AsciiDoc source

  2. Renders the document to HTML or DocBook

  3. Uses XPath and CSS expressions to verify expected output

Here’s how we might test the open block syntax:

test 'should render content bounded by two consecutive hyphens as an open block' do
  input = <<-EOS
--
This is an open block.
--
  EOS
  result = render_embedded_string input
  assert_css '.openblock', result, 1
  assert_css '.openblock p', result, 1
  assert_xpath '/div[@class="openblock"]//p[text()="This is an open block."]', result, 1
end

As you can see, several helpers are used to facilitate the test scenario. The render_embedded_string invokes Asciidoctor’s render method with the header and footer option disabled. This method is ideal for unit-level tests. If you need to test the whole document, use render_string instead. The assert_css and assert_xpath assertion methods take a CSS or XPath selector, respectively, the rendered result and the number of expected matches. You can also use built-in assertions in Ruby’s test library.

To run all the tests, simply execute rake:

$ rake
Note
 The tests should only take a few seconds to run using Ruby 2.1.

If you want to run a single test file, you can use ruby:

$ ruby test/blocks_test.rb

To test a single test case, first add the string "wip" to the beginning of the description. For example:

test 'wip should render ...' do
  ...
end

Then, run ruby again, but this time pass a selector argument so it finds matching tests:

$ ruby test/blocks_test.rb -n /wip/

You can also turn on verbose mode if you want to see more output:

$ ruby test/blocks_test.rb -n /wip/ -v

Once you are done with your test, make sure to remove wip from the description and run all the tests again using rake.

We plan on switching to a more elegant testing framework in the future, such as RSpec or Cucumber, in order to make the tests more clear and robust.

Supporting Additional Ruby Versions

If you would like this library to support another Ruby version, you may volunteer to be a maintainer. Being a maintainer entails making sure all tests run and pass on that implementation. When something breaks on your implementation, you will be expected to provide patches in a timely fashion. If critical issues for a particular implementation exist at the time of a major release, support for that Ruby version may be dropped.