Getting Help and Reporting Issues¶
So you're having a great time slicing and dicing your XML with Nokogiri, and suddenly something happens that you don't quite understand. O NOES, the good times are over.
What do you do?
Step 1: Is it a security vulnerability?¶
Step 2: Mail nokogiri-talk, grasshopper.¶
The best thing to do if you've got a question, or are unsure how to diagnose a possible issue, want to complain, or just ask for advice on how to solve a problem, is to email the nokogiri-talk list.
The nokogiri-talk list has hundreds of subscribers who are all using nokogiri and who are happy to lend a hand, offer advice, and bail you out of tricky situations.
In addition, other people may have the same issue or complaint, and so preserving the question and responses in the mailing list archive is a gift to future Nokogiri users just like you!
Please do not mail the maintainers at their personal addresses.
But I emailed the list and my question hasn't been posted yet!¶
The nokogiri-talk google group is set for "first-post moderation" for non-members, meaning that the first time you email the list, your post will be held for review. Once your post is accepted, there won't be any delay on future emails.
You can avoid first-post moderation by joining the google group (as described above).
Step 3: Bug reporting¶
If you're sure you've got a bug and don't need to talk about it, that's great! We always want to make Nokogiri better, so if you've got a bug, we want to hear about it.
We track bugs on Github Issues, which notifies the maintainers every time a new ticket is created.
What's In a Bug Report?¶
Whoa, do we have strong opinions on this topic. The two most important things that a bug report needs to contain are:
- Example code that reproduces the observed behavior.
- An explanation of what the expected behavior is.
If possible, please include a complete, self-contained script that reproduces the behavior you're seeing. Please try to remove external dependencies like Rails or other libraries that may be wrapping Nokogiri.
Here's an example of how you might structure such a script:
#! /usr/bin/env ruby require 'nokogiri' require 'minitest/autorun' class Test < MiniTest::Spec describe "Node#css" do it "should find a div using chained classes" do html = <<~HEREDOC <html> <body> <div class="foo"> one</div> <div class="bar">two</div> <div class="foo bar">three</div> HEREDOC doc = Nokogiri::HTML::Document.parse(html) assert_equal 1, doc.css("div.foo.bar").length assert_equal "three", doc.at_css("div.foo.bar").text end end end
If you haven't included a test, please provide whatever code you can, the inputs if any, along with the output that you're seeing. We need to reproduce what you're seeing to be able to help.
To sum up the rules:
- Report security vulnerabilities through HackerOne.
- Mail nokogiri-talk to ask for help or discuss whether something is a bug.
- If you're absolutely sure you've got a bug AND you can reproduce it, then create a new bug report on Github Issues with your repro code and description of expected behavior.
Thanks so much for reading this page! You're a good person, and Nokogiri loves you.