Contributing¶ ↑
// settings: :idprefix: :idseparator: - :source-language: ruby :language: {source-language} ifdef::env-github,env-browser[:outfilesuffix: .adoc] // URIs: :uri-repo: github.com/asciidoctor/asciidoctor :uri-help-base: help.github.com/articles :uri-issues: {uri-repo}/issues :uri-fork-help: {uri-help-base}/fork-a-repo :uri-branch-help: {uri-fork-help}#create-branches :uri-pr-help: {uri-help-base}/using-pull-requests :uri-gist: gist.github.com
License Agreement¶ ↑
By contributing changes to this repository, you agree to license your contributions under the <<LICENSE#,MIT license>>. This ensures your contributions have the same license as the project and that the community is free to use your contributions. You also assert that you are the original author of the work that you are contributing unless otherwise stated.
Submitting an Issue¶ ↑
We use the uri-issues}[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 {uri-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¶ ↑
. {uri-fork-help}[Fork the repository]. . Run `NOKOGIRI_USE_SYSTEM_LIBRARIES=1 bundle` to install development dependencies.
- If the `bundle` command is not available, run `gem install bundler` to install it.
. {uri-branch-help}[Create a topic branch] (preferably using the pattern `issue-XYZ`, where `XYZ` is the issue number). . Add tests for your unimplemented feature or bug fix. (See <<writing-and-executing-tests>>) . Run `bundle exec rake` to run the tests. If your tests pass, return to step 4. . Implement your feature or bug fix. . Run `bundle exec rake` to run the tests. If your tests fail, return to step 6. . Add documentation for your feature or bug fix. . If your changes are not 100% documented, go back to step 8. . Add, commit, and push your changes. . {uri-pr-help}[Submit a pull request].
For ideas about how to use pull requests, see the post blog.quickpeople.co.uk/2013/07/10/useful-github-patterns[Useful GitHub Patterns].
Background Knowledge¶ ↑
As Asciidoctor is built using Ruby some basic knowledge of Ruby, RubyGems and Minitest is beneficial. The following resources provide a good starting point for contributors who may not be completely comfortable with these tools:
-
www.ruby-lang.org/en/documentation/quickstart/[Ruby in 20 minutes]
-
www.ruby-lang.org/en/documentation/ruby-from-other-languages/[Ruby from other languages]
-
guides.rubygems.org/what-is-a-gem/[What is a Gem?]
-
blog.teamtreehouse.com/short-introduction-minitest[How to use Minitest]
-
www.rubyinside.com/a-minitestspec-tutorial-elegant-spec-style-testing-that-comes-with-ruby-5354.html[Minitest spec tutorial]
-
github.com/seattlerb/minitest/blob/master/README.rdoc[Minitest Project Documentation]
While these resources don't cover everything needed they serve as a good starting off point for beginners.
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:
- source
test 'description of test' do
# test logic
end
At the moment, the tests are quite primitive. Here's how a typical test operates:
. Defines sample AsciiDoc source . Renders the document to HTML or DocBook . Uses XPath and CSS expressions to verify expected output
Here's how we might test the open block syntax:
- source
test 'should render content bounded by two consecutive hyphens as an open block' do
input = <<-EOS