chore: Update contributing documentation

This also fixes a couple of misnamed test files and improves test
coverage slightly.

Signed-off-by: Austin Ziegler <austin@zieglers.ca>

Author: halostatue

CONTRIBUTING.md

@@ -11,7 +11,9 @@ contributions. There are a few DOs and DON'Ts that should be followed:
   - Use thoughtfully-named topic branches for contributions. Rebase your commits
     into logical chunks as necessary.
 
-  - Use [quality commit messages][qcm].
+  - Use [quality commit messages][qcm] for each commit (minitar uses a rebase
+    merge strategy). Ensure that each commit includes the required Developer
+    Certificate of Origin [sign-off][sign-off].
 
   - Add your name or GitHub handle to `CONTRIBUTORS.md` and a record in the
     `CHANGELOG.md` as a separate commit from your main change. (Follow the style
@@ -49,7 +51,10 @@ without such declaration, the pull request **will be declined**.
 Any contribution (bug, feature request, or pull request) that uses unreviewed
 LLM output will be rejected.
 
-## Test Dependencies
+For an example of how this should be done, see [#151][pr-151] and its
+[associated commits][pr-151-commits].
+
+## Test
 
 minitar uses Ryan Davis's [Hoe][Hoe] to manage the release process, and it adds
 a number of rake tasks. You will mostly be interested in `rake`, which runs
@@ -62,6 +67,186 @@ the development dependencies.
 
 You can run tests with code coverage analysis by running `rake coverage`.
 
+### Test Helpers
+
+Minitar includes a number of custom test assertions, constants, and test utility
+methods that are useful for writing tests. These are maintained through modules
+defined in `test/support`.
+
+#### Fixture Utilities
+
+Minitar uses fixture tarballs in various tests, referenced by their base name
+(`test/fixtures/tar_input.tar.gz` becomes `tar_input`, etc.). There are two
+utility methods:
+
+- `Fixture(name)`: This returns the `Pathname` object for the full path of the
+  named fixture tarball or `nil` if the named fixture does not exist.
+
+- `open_fixture(name)`: This retrieves the named fixture and opens it. If the
+  fixture ends with `.gz` or `.tgz`, it will be opened with a
+  `Zlib::GZipReader`. A block may be provided to ensure that the fixture is
+  automatically closed.
+
+#### Header Assertions and Utilities
+
+Tar headers need to be built and compared in an exacting way, even for tests.
+
+There are two assertions:
+
+- `assert_headers_equal(expected, actual)`: This compares headers by field order
+  verifying that each field in `actual` is supposed to match the corresponding
+  field in `expected`.
+
+  `expected` must be a string representation of the expected header and this
+  assertion calls `#to_s` on the `actual` value so that both `PosixHeader` and
+  `PaxHeader` instances are converted to string representations for comparison.
+
+- `assert_modes_equal(expected, actual, filename)`: This compares the expected
+  octal mode string of `expected` against `actual` for a given `filename`. The
+  modes must be integer values. This assertion is skipped on Windows.
+
+There are several other helper methods available for working with headers:
+
+- `build_tar_file_header(name, prefix, mode, length)`: This builds a header for
+  a file `prefix/name` with `mode` and `length` bytes. `name` is limited to 100
+  bytes and `prefix` is limited to 155 bytes.
+
+- `build_tar_dir_header(name, prefix, mode)`: This builds a header for a
+  directory `prefix/name` with `mode`. `name` is limited to 100 bytes and
+  `prefix` is limited to 155 bytes.
+
+- `build_tar_symlink_header(name, prefix, mode, target)`: This builds a header
+  for a symbolic link of `prefix/name` to `target` where the symbolic link has
+  `mode`. `name` is limited to 100 bytes and `prefix` is limited to 155 bytes.
+
+- `build_tar_pax_header(name, prefix, bytes)`: This builds a header block for a
+  PAX extension at `name/prefix` with `content_size` bytes.
+
+- `build_header(type, name, prefix, size, mode, link = "")`: This builds an
+  otherwise unspecified header type. If you find yourself using this, it is
+  recommended to add a new `build_*_header` helper method.
+
+#### Tarball Helpers
+
+Minitar has several complex assertions and utilities to work with both in-memory
+and on-disk tarballs. These work using two concepts, file hashes (`file_hash`)
+and workspaces (`workspace`).
+
+##### File Hashes (`file_hash`)
+
+Many of these consume or produce a `file_hash`, which is a hash of
+`{filename => content}` where the tarball will be produced with such that each
+entry in the `file_hash` becomes a file named `filename` with the data
+`content`.
+
+As an example, `Minitar::TestHelpers` has a `MIXED_FILENAME_SCENARIOS` constant
+that is a `file_hash`:
+
+```ruby
+MIXED_FILENAME_SCENARIOS = {
+  "short.txt" => "short content",
+  "medium_length_filename_under_100_chars.txt" => "medium content",
+  "dir1/medium_filename.js" => "medium nested content",
+  "#{"x" * 120}.txt" => "long content",
+  "nested/dir/#{"y" * 110}.css" => "long nested content"
+}.freeze
+```
+
+This will produce a tarball that looks like:
+
+```
+short.txt
+medium_length_filename_under_100_chars.txt
+dir1/medium_filename.js
+x[118 more 'x' characters...]x
+nested/dir/y[108 more y' characters...]y.css
+```
+
+Each file will contain the text as the content.
+
+If the `content` is `nil`, this will be ignored for in-memory tarballs, but will
+be created as empty directory entries for on-disk tarballs.
+
+##### Workspace (`workspace`)
+
+A workspace is a temporary directory used for on-disk tests. It is created with
+the `workspace` utility method (see below) and must be passed a block where all
+setup and tests will be run.
+
+At most one `workspace` may be used per test method.
+
+##### Assertions
+
+There are five assertions:
+
+- `assert_tar_structure_preserved(original_files, extracted_files)`: This is
+  used primarily with string tarballs. Given two `file_hash`es representing
+  tarball contents (the original files passed to `create_tar_string` and the
+  extracted files returned from `extract_tar_string`), it ensures that all files
+  from the original contents are present and that no additional files have been
+  added in the process.
+
+- `assert_files_extracted_in_workspace`: Can only be run in a `workspace` and
+  the test tarball must have been both created and extracted. This ensures that
+  all of the files and/or directories expected have been extracted and that the
+  contents of files match. File modes are ignored for this assertion.
+
+- `refute_file_path_duplication_in_workspace`: Can only be run in a `workspace`
+  and the test tarball must have been both created and extracted. This is used
+  to prevent regression of [#62][issue-62] with explicit file tests. This only
+  needs to be called after unpacking with Minitar methods.
+
+- `assert_extracted_files_match_source_files_in_workspace`: Can only be run in a
+  `workspace` and the test tarball must have been both created and extracted.
+  This ensures that there are no files missing or added in the `target`
+  directory that should are not also be in the `source` directory. This does no
+  contents comparison.
+
+- `assert_file_modes_match_in_workspace`: Can only be run in a `workspace` and
+  the test tarball must have been both created and extracted. This ensures that
+  all files have the same modes between source and target. This is skipped on
+  Windows.
+
+##### In-Memory Tarball Utilities
+
+- `create_tar_string`: Given a `file_hash`, this creates a string containing the
+  output of `Minitar::Output.open` and `Minitar.pack_as_file`.
+
+- `extract_tar_string`: Given the string output of `create_tar_string` (or any
+  uncompressed tarball string), uses `Minitar::Input.open` to read the files
+  into a hash of `{filename => content}`.
+
+- `roundtrip_tar_string`: calls `create_tar_string` on a `file_hash` and
+  immediately calls `extract_tar_string`, returning a processed `file_hash`.
+
+##### On-Disk Workspace Tarball Utilities
+
+- `workspace`: Prepares a temporary directory for working with tarballs on disk
+  inside the block that must be provided. If given a hash of files, calls
+  `prepare_files`. The workspace directory will be removed after the block
+  finishes executing.
+
+  A workspace has a `source` directory, a `target` directory`, and the`tarball`
+  which will be created from the prepared files.
+
+  All other utility methods _must_ be run inside of a `workspace` block.
+
+- `prepare_workspace`: creates a file structure in the workspace source
+  directory given the `{filename => content}` hash. For on-disk file structures,
+  `{directory_name => nil}` can be used to create empty directories. Directory
+  names will be created automatically for nested filenames.
+
+- `gnu_tar_create_in_workspace`, `gnu_tar_extract_in_workspace`, and
+  `gnu_tar_list_in_workspace` work with the workspace tarball using GNU tar
+  (either `tar` or `gtar`). GNU tar tests will be skipped if GNU tar is not
+  available.
+
+- `minitar_pack_in_workspace`, `minitar_unpack_in_workspace` use `Minitar.pack`
+  and `Minitar.unpack`, respectively, to work with the workspace tarball.
+
+- `minitar_writer_create_in_workspace` uses `Minitar::Writer` to create the
+  workspace tarball.
+
 ## Workflow
 
 Here's the most direct way to get your work merged into the project:
@@ -79,6 +264,10 @@ Here's the most direct way to get your work merged into the project:
 
 [dco]: licences/dco.txt
 [hoe]: https://github.com/seattlerb/hoe
+[issue-62]: https://github.com/halostatue/minitar/issues/62
 [minitest]: https://github.com/seattlerb/minitest
+[pr-151-commits]: https://github.com/halostatue/minitar/pull/151/commits
+[pr-151]: https://github.com/halostatue/minitar/pull/151
 [qcm]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+[sign-off]: LICENCE.md#developer-certificate-of-origin
 [standardrb]: https://github.com/standardrb/standard

LICENCE.md

@@ -1,6 +1,6 @@
 # Licence
 
-- SPDX-License-Identifier: [Ruby][ruby-license] OR [BSD-2-Clause]
+- SPDX-License-Identifier: [Ruby][ruby-license] OR [BSD-2-Clause][bsd-2-clause]
 
 minitar is free software that may be redistributed and/or modified under the
 terms of Ruby’s licence or the Simplified BSD licence.

Manifest.txt

@@ -12,6 +12,7 @@ docs/ruby.txt
 lib/minitar.rb
 lib/minitar/input.rb
 lib/minitar/output.rb
+lib/minitar/pax_header.rb
 lib/minitar/posix_header.rb
 lib/minitar/reader.rb
 lib/minitar/version.rb
@@ -20,11 +21,12 @@ licenses/bsdl.txt
 licenses/dco.txt
 licenses/ruby.txt
 test/fixtures/issue_46.tar.gz
-test/fixtures/issue_52.tar.gz
+test/fixtures/issue_62.tar.gz
 test/fixtures/tar_input.tgz
 test/fixtures/test_input_non_strict_octal.tgz
 test/fixtures/test_input_relative.tgz
 test/fixtures/test_input_space_octal.tgz
+test/fixtures/test_minitar.tar.gz
 test/minitest_helper.rb
 test/support/minitar_test_helpers.rb
 test/support/minitar_test_helpers/fixtures.rb
@@ -34,8 +36,10 @@ test/test_filename_boundary_conditions.rb
 test/test_gnu_tar_compatibility.rb
 test/test_integration_pack_unpack_cycle.rb
 test/test_issue_46.rb
-test/test_issue_52.rb
+test/test_issue_62.rb
 test/test_minitar.rb
+test/test_pax_header.rb
+test/test_pax_support.rb
 test/test_tar_header.rb
 test/test_tar_input.rb
 test/test_tar_output.rb

lib/minitar.rb

@@ -77,9 +77,9 @@ def open(dest, mode = "r", &)
     when "r", "rb"
       Minitar::Input.open(dest, &)
     when "w", "wb"
-      Minitar::Output.open(dest, &block)
+      Minitar::Output.open(dest, &)
     else
-      raise "Unknown open mode for Minitar.open."
+      raise ArgumentError, "Unknown open mode for Minitar.open."
     end
   end
 

minitar.gemspec

@@ -9,11 +9,11 @@ Gem::Specification.new do |s|
   s.metadata = { "bug_tracker_uri" => "https://github.com/halostatue/minitar/issues", "changelog_uri" => "https://github.com/halostatue/minitar/blob/main/CHANGELOG.md", "rubygems_mfa_required" => "true", "source_code_uri" => "https://github.com/halostatue/minitar" } if s.respond_to? :metadata=
   s.require_paths = ["lib".freeze]
   s.authors = ["Austin Ziegler".freeze]
-  s.date = "2025-09-07"
+  s.date = "2025-09-08"
   s.description = "The minitar library is a pure-Ruby library that operates on POSIX tar(1) archive files.  minitar (previously called Archive::Tar::Minitar) is based heavily on code originally written by Mauricio Julio Fern\u00E1ndez Pradier for the rpa-base project.".freeze
   s.email = ["halostatue@gmail.com".freeze]
   s.extra_rdoc_files = ["CHANGELOG.md".freeze, "CODE_OF_CONDUCT.md".freeze, "CONTRIBUTING.md".freeze, "CONTRIBUTORS.md".freeze, "LICENCE.md".freeze, "Manifest.txt".freeze, "README.md".freeze, "SECURITY.md".freeze, "docs/bsdl.txt".freeze, "docs/ruby.txt".freeze, "licenses/bsdl.txt".freeze, "licenses/dco.txt".freeze, "licenses/ruby.txt".freeze]
-  s.files = ["CHANGELOG.md".freeze, "CODE_OF_CONDUCT.md".freeze, "CONTRIBUTING.md".freeze, "CONTRIBUTORS.md".freeze, "LICENCE.md".freeze, "Manifest.txt".freeze, "README.md".freeze, "Rakefile".freeze, "SECURITY.md".freeze, "docs/bsdl.txt".freeze, "docs/ruby.txt".freeze, "lib/minitar.rb".freeze, "lib/minitar/input.rb".freeze, "lib/minitar/output.rb".freeze, "lib/minitar/posix_header.rb".freeze, "lib/minitar/reader.rb".freeze, "lib/minitar/version.rb".freeze, "lib/minitar/writer.rb".freeze, "licenses/bsdl.txt".freeze, "licenses/dco.txt".freeze, "licenses/ruby.txt".freeze, "test/fixtures/issue_46.tar.gz".freeze, "test/fixtures/issue_52.tar.gz".freeze, "test/fixtures/tar_input.tgz".freeze, "test/fixtures/test_input_non_strict_octal.tgz".freeze, "test/fixtures/test_input_relative.tgz".freeze, "test/fixtures/test_input_space_octal.tgz".freeze, "test/minitest_helper.rb".freeze, "test/support/minitar_test_helpers.rb".freeze, "test/support/minitar_test_helpers/fixtures.rb".freeze, "test/support/minitar_test_helpers/header.rb".freeze, "test/support/minitar_test_helpers/tarball.rb".freeze, "test/test_filename_boundary_conditions.rb".freeze, "test/test_gnu_tar_compatibility.rb".freeze, "test/test_integration_pack_unpack_cycle.rb".freeze, "test/test_issue_46.rb".freeze, "test/test_issue_52.rb".freeze, "test/test_minitar.rb".freeze, "test/test_tar_header.rb".freeze, "test/test_tar_input.rb".freeze, "test/test_tar_output.rb".freeze, "test/test_tar_reader.rb".freeze, "test/test_tar_writer.rb".freeze]
+  s.files = ["CHANGELOG.md".freeze, "CODE_OF_CONDUCT.md".freeze, "CONTRIBUTING.md".freeze, "CONTRIBUTORS.md".freeze, "LICENCE.md".freeze, "Manifest.txt".freeze, "README.md".freeze, "Rakefile".freeze, "SECURITY.md".freeze, "docs/bsdl.txt".freeze, "docs/ruby.txt".freeze, "lib/minitar.rb".freeze, "lib/minitar/input.rb".freeze, "lib/minitar/output.rb".freeze, "lib/minitar/pax_header.rb".freeze, "lib/minitar/posix_header.rb".freeze, "lib/minitar/reader.rb".freeze, "lib/minitar/version.rb".freeze, "lib/minitar/writer.rb".freeze, "licenses/bsdl.txt".freeze, "licenses/dco.txt".freeze, "licenses/ruby.txt".freeze, "test/fixtures/issue_46.tar.gz".freeze, "test/fixtures/issue_62.tar.gz".freeze, "test/fixtures/tar_input.tgz".freeze, "test/fixtures/test_input_non_strict_octal.tgz".freeze, "test/fixtures/test_input_relative.tgz".freeze, "test/fixtures/test_input_space_octal.tgz".freeze, "test/fixtures/test_minitar.tar.gz".freeze, "test/minitest_helper.rb".freeze, "test/support/minitar_test_helpers.rb".freeze, "test/support/minitar_test_helpers/fixtures.rb".freeze, "test/support/minitar_test_helpers/header.rb".freeze, "test/support/minitar_test_helpers/tarball.rb".freeze, "test/test_filename_boundary_conditions.rb".freeze, "test/test_gnu_tar_compatibility.rb".freeze, "test/test_integration_pack_unpack_cycle.rb".freeze, "test/test_issue_46.rb".freeze, "test/test_issue_62.rb".freeze, "test/test_minitar.rb".freeze, "test/test_pax_header.rb".freeze, "test/test_pax_support.rb".freeze, "test/test_tar_header.rb".freeze, "test/test_tar_input.rb".freeze, "test/test_tar_output.rb".freeze, "test/test_tar_reader.rb".freeze, "test/test_tar_writer.rb".freeze]
   s.homepage = "https://github.com/halostatue/minitar".freeze
   s.licenses = ["Ruby".freeze, "BSD-2-Clause".freeze]
   s.rdoc_options = ["--main".freeze, "README.md".freeze]

test/fixtures/issue_52.tar.gz renamed to test/fixtures/issue_62.tar.gz

@@ -22,33 +22,33 @@ def assert_headers_equal(expected, actual)
     end
   end
 
-  def assert_modes_equal(expected, actual, name)
+  def assert_modes_equal(expected, actual, filename)
     return if Minitar.windows?
 
-    assert_equal mode_string(expected), mode_string(actual), "Mode for #{name} does not match"
+    assert_equal mode_string(expected), mode_string(actual), "Mode for #{filename} does not match"
   end
 
-  def build_raw_header(type, fname, dname, length, mode, link_name = "") =
+  def build_raw_header(type, name, prefix, size, mode, link_name = "") =
     [
-      fname, mode, z(octal(nil, 7)), z(octal(nil, 7)), length, z(octal(0, 11)),
+      name, mode, z(octal(nil, 7)), z(octal(nil, 7)), size, z(octal(0, 11)),
       BLANK_CHECKSUM, type, asciiz(link_name, 100), USTAR, DOUBLE_ZERO, asciiz("", 32),
-      asciiz("", 32), z(octal(nil, 7)), z(octal(nil, 7)), dname
+      asciiz("", 32), z(octal(nil, 7)), z(octal(nil, 7)), prefix
     ].join.bytes.to_a.pack("C100C8C8C8C12C12C8CC100C6C2C32C32C8C8C155").then {
       "#{_1}#{"\0" * (512 - _1.bytesize)}"
     }.tap { assert_equal 512, _1.bytesize }
 
-  def build_header(type, fname, dname, length, mode, link_name = "") =
+  def build_header(type, name, prefix, size, mode, link_name = "") =
     build_raw_header(
       type,
-      asciiz(fname, 100),
-      asciiz(dname, 155),
-      z(octal(length, 11)),
+      asciiz(name, 100),
+      asciiz(prefix, 155),
+      z(octal(size, 11)),
       z(octal(mode, 7)),
       asciiz(link_name, 100)
     )
 
-  def build_tar_file_header(fname, dname, mode, length) =
-    build_header("0", fname, dname, length, mode).then {
+  def build_tar_file_header(name, prefix, mode, size) =
+    build_header("0", name, prefix, size, mode).then {
       update_header_checksum(_1)
     }
 
@@ -80,7 +80,7 @@ def update_header_checksum(header) =
 
   def octal(n, pad_size) = n.nil? ? "\0" * pad_size : "%0#{pad_size}o" % n
 
-  def asciiz(str, length) = "#{str}#{"\0" * (length - str.bytesize)}"
+  def asciiz(str, size) = "#{str}#{"\0" * (size - str.bytesize)}"
 
   def sp(s) = "#{s} "
 

test/fixtures/test_minitar.tar.gz

@@ -21,7 +21,7 @@ module Minitar::TestHelpers::Tarball
 
   # Given the +original_files+ file hash (input to +create_tar_string+) and the
   # +extracted_files+ file has (output from +extract_tar_string+), ensures that the tar
-  # structure is preserved, including checking for possible regression of issue 52.
+  # structure is preserved, including checking for possible regression of issue 62.
   #
   # Such a regression would result in a directory like <tt>>/b/c.txt</tt> looking like
   # <tt>a/b/a/b/c.txt</tt> (but only for long filenames).
@@ -46,7 +46,7 @@ def assert_tar_structure_preserved(original_files, extracted_files)
       duplicated_paths = extracted_paths.select { |path| path == bad_pattern }
 
       refute duplicated_paths.any?,
-        "Regression of #52, path duplication on extraction! " \
+        "Regression of #62, path duplication on extraction! " \
         "Original: #{filename}, " \
         "Bad pattern found: #{bad_pattern}, " \
         "All extracted paths: #{extracted_paths}"
@@ -58,6 +58,7 @@ def create_tar_string(file_hash) =
     StringIO.new.tap { |io|
       Minitar::Output.open(io) do |output|
         file_hash.each do |filename, content|
+          next if content.nil?
           Minitar.pack_as_file(filename, content.to_s.dup, output)
         end
       end