Cut the v0.6.0 release #3533

Activity

1. ESultanik

   added this to the v0.6.0 milestone on Sep 11, 2026
2. ESultanik

   marked this as blocked by 14 issues on Sep 11, 2026

   • DoS Issues #3529
   • Spurious nested application/zip match on the end of central directory magic field #3470
   • Three generated Kaitai parsers fail to import due to reserved keywords and an unescaped docstring #3462
   • A !:strength factor followed by a comment is silently discarded #3476
   • Unguarded byte-provenance dereferences in pdf.py can silently truncate the match tree #3464
   • Nothing detects drift between polyfile/magic_defs and the file submodule #3479
   • test_file_corpus has a dead ASCII text branch and an unexplained hancom hwp branch #3501
   • An untyped indirect offset defaults to big endian, where libmagic uses host byte order #3499
   • A BOM-prefixed JSON document is reported as JSON, where file reports Unicode text #3500
   • detect_text_encoding does not trim trailing NULs, so NUL-padded text is reported as binary #3506
   • Fix matcher structure defects #3530
   • detect_text_encoding has no EBCDIC branch, so EBCDIC text is reported as binary #3507
   • A relative offset after a search resolves from the consumed extent, not the declared length #3503
   • CLI and documentation defects #3531
3. 1 remaining item

   Load more
4. ESultanik

   marked this as blocked by 10 issues on Sep 11, 2026

   • [Feature Request/Improvement] Alternate JSON Output w/o b64contents #3399
   • A UTF-8 byte order mark is missing from the text encoding description #3537
   • Cross-reference row cells are never parsed: parse_object receives the Submatch, not the cell #3542
   • A search test matches when fewer bytes remain than its value declares #3552
   • A negated string test no longer matches a buffer shorter than its value #3557
   • A flagged search tries one start offset too many #3558
   • The full word (f) flag anchors both sides, so no shipped f definition can match #3559
   • The W (compact whitespace) flag requires the value's own whitespace byte #3562
   • An empty file reports nothing, where file reports empty and inode/x-empty #3566
   • STRING_FLAG_BITS omits the b flag, so a binary-pass string test sorts as though it were unflagged #3568
5. ESultanik commented on Sep 11, 2026

   

   ESultanik

   on Sep 11, 2026

   CollaboratorAuthor

   More actions

   Methodology for the release notes: audit the history, do not reconstruct it

   Build polyfile_0.6.0.md from a complete audit of every commit message and pull request
   description since the v0.5.6 tag, rather than from a summary or from the milestone's issue list.
   The milestone captures what was planned; the history captures what actually shipped, including work
   that arrived outside the milestone.

   Scope

   Measured 2026-09-11:

   	count
   commits since v0.5.6	225
   merge commits (pull requests)	73
   pull requests merged in the window	70

   v0.5.6 was tagged 2026-02-11, so the window is seven months.

   git log --oneline v0.5.6..master                 # every commit
   git log --merges --oneline v0.5.6..master        # the pull requests
   gh pr list --state merged --limit 200 --json number,title,mergedAt,body

   Read the pull request bodies, not only the titles. This project writes long ones with measured
   evidence, and the observable behavior change is usually stated there rather than in the subject line.

   What the audit has to surface

   The v0.5.6 notes are the model for structure — Performance Improvements, Bug Fixes, New Features,
   Magic Definitions, Breaking Changes, Dependencies. Drop a section with nothing in it.

   Breaking Changes needs the most care. This release changes observable output in many ways, and
   anyone parsing PolyFile's output is affected. Known examples, which the audit must confirm and
   extend rather than treat as complete:

   • --format file is accepted where it was rejected, and json no longer appears twice in the
     choices (--format file is rejected, json is duplicated in the choices, and the help example uses the wrong flag #3497)
   • the try_all_offsets parameter is removed from Matcher and Analyzer (try_all_offsets is accepted and ignored, and the CLI flag for it is commented out #3465)
   • an untyped indirect offset reads in host byte order rather than big endian (An untyped indirect offset defaults to big endian, where libmagic uses host byte order #3499)
   • a BOM-prefixed JSON document reports both JSON and Unicode text (A BOM-prefixed JSON document is reported as JSON, where file reports Unicode text #3500)
   • EBCDIC text and NUL-padded text are classified as text rather than binary (detect_text_encoding does not trim trailing NULs, so NUL-padded text is reported as binary #3506, detect_text_encoding has no EBCDIC branch, so EBCDIC text is reported as binary #3507)
   • a UTF-8 byte order mark is named in the encoding description (A UTF-8 byte order mark is missing from the text encoding description #3537)
   • an empty file reports empty / inode/x-empty where it previously reported nothing, and
     --format html no longer crashes on one (An empty file reports nothing, where file reports empty and inode/x-empty #3566)
   • string and search tests refuse a value longer than the buffer, and a flagged search stops one
     start offset earlier (A string test matches when fewer bytes remain than its value declares #3504, A search test matches when fewer bytes remain than its value declares #3552, A negated string test no longer matches a buffer shorter than its value #3557, A flagged search tries one start offset too many #3558)
   • the f flag makes 60 previously unfirable definitions match, so shebang scripts gain descriptions
     such as POSIX shell script (The full word (f) flag anchors both sides, so no shipped f definition can match #3559)

   Two larger bodies of work also need describing at the right altitude, as themes rather than issue
   lists: the libmagic 5.48 fidelity effort, which ended with all 88 corpus stems matching file and
   KNOWN_FAILURES empty, and the packaging move from setup.py to pyproject.toml with the in-tree
   PEP 517 backend (#3513).

   Also in scope

   • Bump version in pyproject.toml from 0.5.6 to 0.6.0. That single line is the whole bump;
     polyfile/polyfile.py reads __version__ from package metadata.
   • Add uv.lock to .gitignore. It is untracked and unignored today, so it shows as dirty in every
     worktree and gh pr create warns about it on every branch.
   • Verify the distribution: uv build, then uvx twine check dist/*.

   Publishing stays out of scope. .github/workflows/pythonpublish.yml runs on release: published
   and uploads through PyPI Trusted Publishing, so the release itself is cut from the GitHub UI after
   this merges.
6. ESultanik

   marked this as blocked by 2 issues on Sep 12, 2026

   • A search with no range sorts as though it declared a range of 100 #3580
   • JSON output contains Python object reprs with heap addresses, so it differs between runs #3581
7. ESultanik commented on Sep 12, 2026

   

   ESultanik

   on Sep 12, 2026

   CollaboratorAuthor

   More actions

   Authorization for this issue, from @ESultanik

   Direct push to master is authorized for this issue only, and only if the sole code change is the
   version bump. No pull request is needed for that.

   The release commit may contain exactly these:

   1. pyproject.toml — version = "0.5.6" → version = "0.6.0". This is the whole code change;
      polyfile/polyfile.py reads __version__ from package metadata.
   2. polyfile_0.6.0.md — the new release notes.
   3. .gitignore — add uv.lock, authorized separately earlier in the same discussion. It is
      untracked and unignored today, so it shows dirty in every worktree and gh pr create warns on
      every branch.

   If anything else needs changing, stop and open a pull request instead. A stale document found
   while auditing, a failing build, a packaging fix — none of those are covered. The authorization is
   narrow by design: it exists because a version bump plus release notes has nothing to review that
   reading the notes would not already show.

   The release itself is a draft

   Create it as a draft GitHub release against tag v0.6.0. Do not publish it.

   gh release create v0.6.0 --draft --title "PolyFile 0.6.0" --notes-file polyfile_0.6.0.md

   Publishing is what @ESultanik does after reviewing the draft. This matters mechanically, not just
   procedurally: .github/workflows/pythonpublish.yml triggers on release: published and uploads to
   PyPI through Trusted Publishing. A published release ships to PyPI immediately and cannot be
   recalled. A draft holds the notes and the tag target without triggering anything.
8. ESultanik

   added a commit that references this issue on Sep 12, 2026

   Bump the version to 0.6.0 and add the release notes

   ...

   625d51d