diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f0d8e455a46..baf483ebdfb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -344,14 +344,22 @@ Some guidelines (see [lib/nokogiri/xml/node.rb](lib/nokogiri/xml/node.rb) and [e - name all the aliases of a method - indicate block/yield usage of a method - Briefly explain the purpose of the method, what it returns, and what side effects it has -- Use a `[Parameters]` definition to note the expected types of all the parameters as a bulleted list -- Use a `[Returns]` definition to note the return type -- Use a `[Yields]` definition to note the block parameters -- Use a `⚠` character to warn the user about tricky usage -- Use a `💡` character to call attention to important notes -- `See also:` should be used to call out related methods -- `Since` should be used to indicate the version in which the code was introduced -- Prefer to **show** nuanced behavior in code examples, rather than try to explain it in prose. +- Method signatures + - Use a `[Parameters]` definition to note the expected types of all the parameters as a bulleted list + - Use a `[Returns]` definition to note the return type + - Use a `[Yields]` definition to note the block parameters + - use RBS syntax whenever possible to declare variable types +- Callouts + - Use a `🛡` character for security-related notes + - Use a `⚠` character to warn the user about tricky usage + - Use a `💡` character to call attention to other important notes +- Examples + - Prefer to **show** nuanced behavior in code examples, rather than try to explain it in prose. + - Use the line `*Example:* ` to name examples and visually separate them + - Indent two extra columns to get code-block formatting +- Metadata + - `See also:` should be used to call out related methods + - `Since` should be used to indicate the version in which the code was introduced ### Code @@ -502,17 +510,20 @@ The `Rakefile` used to be a big fat mess. It's now decomposed into a small set o ## Making a release -A quick checklist: - -- [ ] make sure CI is green! -- [ ] update `CHANGELOG.md` and `lib/nokogiri/version/constant.rb` -- [ ] create a git tag -- [ ] run `scripts/build-gems` and make sure it completes and all the tests pass -- [ ] `for g in gems/*.gem ; do gem push $g ; done` -- [ ] create a release at https://github.com/sparklemotion/nokogiri/releases and provide sha2 checksums -- if security-related, +A quick checklist for releasing Nokogiri: + +- Prechecks + - [ ] make sure CI is green! + - [ ] update `CHANGELOG.md` and `lib/nokogiri/version/constant.rb` + - [ ] commit and create a git tag + - [ ] run `scripts/build-gems` and make sure it completes and all the tests pass +- Release + - [ ] `git push && git push --tags` + - [ ] `for g in gems/*.gem ; do gem push $g ; done` + - [ ] create a release at https://github.com/sparklemotion/nokogiri/releases and provide sha2 checksums +- If the release has security fixes ... - [ ] publish a GHSA - [ ] email ruby-security-ann@googlegroups.com and ruby-talk@ruby-lang.org - - [ ] submit a PR to https://github.com/rubysec/ruby-advisory-db -- [ ] update nokogiri.org -- [ ] bump `lib/nokogiri/version/constant.rb` to a prerelease version like `v1.14.0.dev` +- Post-release + - [ ] update nokogiri.org + - [ ] bump `lib/nokogiri/version/constant.rb` to a prerelease version like `v1.14.0.dev` diff --git a/ext/nokogiri/xml_relax_ng.c b/ext/nokogiri/xml_relax_ng.c index 40670ef0bb3..87ce6506d19 100644 --- a/ext/nokogiri/xml_relax_ng.c +++ b/ext/nokogiri/xml_relax_ng.c @@ -3,7 +3,7 @@ VALUE cNokogiriXmlRelaxNG; static void -xml_relax_ng_deallocate(void *data) +_noko_xml_relax_ng_deallocate(void *data) { xmlRelaxNGPtr schema = data; xmlRelaxNGFree(schema); @@ -12,7 +12,7 @@ xml_relax_ng_deallocate(void *data) static const rb_data_type_t xml_relax_ng_type = { .wrap_struct_name = "xmlRelaxNG", .function = { - .dfree = xml_relax_ng_deallocate, + .dfree = _noko_xml_relax_ng_deallocate, }, .flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED, }; @@ -51,7 +51,7 @@ noko_xml_relax_ng__validate_document(VALUE self, VALUE document) } static VALUE -xml_relax_ng_parse_schema( +_noko_xml_relax_ng_parse_schema( VALUE rb_class, xmlRelaxNGParserCtxtPtr c_parser_context, VALUE rb_parse_options @@ -105,10 +105,10 @@ xml_relax_ng_parse_schema( * from_document(document) → Nokogiri::XML::RelaxNG * from_document(document, parse_options) → Nokogiri::XML::RelaxNG * - * Create a Schema from an already-parsed RELAX NG schema definition document. + * Parse a RELAX NG schema definition from a Document to create a new Schema. * * [Parameters] - * - +document+ (XML::Document) A XML::Document object representing the parsed RELAX NG + * - +document+ (XML::Document) RELAX NG schema definition * - +parse_options+ (Nokogiri::XML::ParseOptions) ⚠ Unused * * [Returns] Nokogiri::XML::RelaxNG @@ -131,7 +131,7 @@ noko_xml_relax_ng_s_from_document(int argc, VALUE *argv, VALUE rb_class) c_parser_context = xmlRelaxNGNewDocParserCtxt(c_document); - return xml_relax_ng_parse_schema(rb_class, c_parser_context, rb_parse_options); + return _noko_xml_relax_ng_parse_schema(rb_class, c_parser_context, rb_parse_options); } void diff --git a/lib/nokogiri/xml/relax_ng.rb b/lib/nokogiri/xml/relax_ng.rb index dbe6c0e24e3..6cfb1c5839c 100644 --- a/lib/nokogiri/xml/relax_ng.rb +++ b/lib/nokogiri/xml/relax_ng.rb @@ -4,81 +4,63 @@ module Nokogiri module XML class << self # :call-seq: - # RelaxNg(input) → Nokogiri::XML::RelaxNG - # RelaxNg(input, parse_options) → Nokogiri::XML::RelaxNG + # RelaxNG(input) → Nokogiri::XML::RelaxNG + # RelaxNG(input, options:) → Nokogiri::XML::RelaxNG # - # Parse a RELAX NG schema definition and create a new Schema object. This is a convenience - # method for Nokogiri::XML::RelaxNG.new - # - # See related: Nokogiri::XML::RelaxNG.new - # - # [Parameters] - # - +input+ (String, IO) RELAX NG schema definition - # - +parse_options+ (Nokogiri::XML::ParseOptions) - # Defaults to ParseOptions::DEFAULT_SCHEMA - # - # [Returns] Nokogiri::XML::RelaxNG - # - def RelaxNG(input, parse_options = ParseOptions::DEFAULT_SCHEMA) - RelaxNG.new(input, parse_options) + # Convenience method for calling Nokogiri::XML::RelaxNG.read_memory + def RelaxNG(...) + RelaxNG.new(...) end end - # Nokogiri::XML::RelaxNG is used for validating XML against a RELAX NG schema definition. + # Nokogiri::XML::RelaxNG is used for validating \XML against a RELAX NG schema definition. # - # *Example:* Determine whether an XML document is valid. + # 🛡 Do not use this class for untrusted schema documents. RELAX NG input is always + # treated as *trusted*, meaning that the underlying parsing libraries will access network + # resources. This is counter to Nokogiri's "untrusted by default" security policy, but is an + # unfortunate limitation of the underlying libraries. # - # schema = Nokogiri::XML::RelaxNG(File.read(RELAX_NG_FILE)) - # doc = Nokogiri::XML(File.read(XML_FILE)) + # *Example:* Determine whether an \XML document is valid. + # + # schema = Nokogiri::XML::RelaxNG.read_memory(File.read(RELAX_NG_FILE)) + # doc = Nokogiri::XML::Document.parse(File.read(XML_FILE)) # schema.valid?(doc) # Boolean # - # *Example:* Validate an XML document against a RelaxNG schema, and capture any errors that are found. + # *Example:* Validate an \XML document against a \RelaxNG schema, and capture any errors that are found. # - # schema = Nokogiri::XML::RelaxNG(File.open(RELAX_NG_FILE)) - # doc = Nokogiri::XML(File.open(XML_FILE)) + # schema = Nokogiri::XML::RelaxNG.read_memory(File.open(RELAX_NG_FILE)) + # doc = Nokogiri::XML::Document.parse(File.open(XML_FILE)) # errors = schema.validate(doc) # Array # - # ⚠ RELAX NG input is always treated as *trusted*, meaning that the underlying parsing libraries - # *will access network resources*. This is counter to Nokogiri's "untrusted by default" security - # policy, but is an unfortunate limitation of the underlying libraries. Please do not use this - # class for untrusted schema documents. class RelaxNG < Nokogiri::XML::Schema # :call-seq: # new(input) → Nokogiri::XML::RelaxNG - # new(input, parse_options) → Nokogiri::XML::RelaxNG - # - # Parse a RELAX NG schema definition and create a new Schema object. + # new(input, options:) → Nokogiri::XML::RelaxNG # - # [Parameters] - # - +input+ (String, IO) RELAX NG schema definition - # - +parse_options+ (Nokogiri::XML::ParseOptions) - # Defaults to ParseOptions::DEFAULT_SCHEMA ⚠ Unused - # - # [Returns] Nokogiri::XML::RelaxNG - # - # ⚠ +parse_options+ is currently unused by this method and is present only as a placeholder for - # future functionality. - def self.new(input, parse_options = ParseOptions::DEFAULT_SCHEMA) - read_memory(input, parse_options) + # Convenience method for calling Nokogiri::XML::RelaxNG.read_memory + def self.new(...) + read_memory(...) end # :call-seq: # read_memory(input) → Nokogiri::XML::RelaxNG - # read_memory(input, parse_options) → Nokogiri::XML::RelaxNG + # read_memory(input, options:) → Nokogiri::XML::RelaxNG # - # Parse a RELAX NG schema definition and create a new Schema object. + # Parse a RELAX NG schema definition from a String to create a new Schema. # # [Parameters] # - +input+ (String) RELAX NG schema definition - # - +parse_options+ (Nokogiri::XML::ParseOptions) - # Defaults to ParseOptions::DEFAULT_SCHEMA ⚠ Unused + # - +options:+ (Nokogiri::XML::ParseOptions) + # Defaults to ParseOptions::DEFAULT_SCHEMA ⚠ Unused # # [Returns] Nokogiri::XML::RelaxNG # # ⚠ +parse_options+ is currently unused by this method and is present only as a placeholder for # future functionality. - def self.read_memory(input, parse_options = ParseOptions::DEFAULT_SCHEMA) - from_document(Nokogiri::XML::Document.parse(input), parse_options) + # + # Also see convenience method Nokogiri::XML::RelaxNG() + def self.read_memory(input, parse_options_ = ParseOptions::DEFAULT_SCHEMA, options: parse_options_) + from_document(Nokogiri::XML::Document.parse(input), options) end end end