Is upgrading from v2 to v3 safe?

[luisjoserivera]

Hi,
I've been looking for change logs without success.
No way to know if v3 api has breaking changes

[blueimp]

Hi @luisjoserivera,

most of the API has been unchanged, so it's safe to upgrade for the large majority of use cases.

The breaking changes are around EXIF handling.

While I don't keep a manual changelog, I generally try to write useful commit messages, so the commit history is the closest thing to a formal changelog.

The following is the output of git log --pretty=%B v2.31.0...v3.0.0:

3.0.0

Remove the meta dependency from the fetch plugin.

Add url to load/error event handler params.

Fix ObjectURL revoke tests for Edge Legacy and IE.

Refactor EXIF and IPTC parsing.

Map EXIF private IFD tags into separate objects (Exif, GPSInfo, Interoperability).
Store IPTC tag offsets as data.iptcOffsets.
Add `getName` method to tag maps to retrieve the tag name for a given tag code.
Add new options to include/exclude tags from parsing (includeExifTags, excludeExifTags, includeIptcTags, excludeIptcTags).
Exclude EXIF MakerNote and IPTC ObjectPreviewData by default.
Add link to thumbnail image for the demo.

Store Exif Thumbnail as Blob instead of ObjectURL.

Please also see #91 for a previous requests for a separate changelog.

Here are examples on how to account for the changes in EXIF handling:

Displaying EXIF Thumbnails in v3+:

loadImage(
  fileOrBlobOrUrl,
  function (img, data) {
    var thumbBlob = data.exif && data.exif.get('Thumbnail')
    if (thumbBlob) {
      loadImage(thumbBlob, function (thumbImage) {
        document.body.appendChild(thumbImage)
      })
    }
  },
  { meta: true }
)

Displaying all parsed (TIFF and) Exif tags in v3+ (only the exif data structure changed, from a flat map to a multi-dimensional map with Private IFD tag values containing their own maps):

loadImage(
  fileOrBlobOrUrl,
  function (img, data) {
    if (data.exif) {
      // A map of all parsed tags with their mapped names/text as keys/values:
      // Private IFD tags contain objects with their own map.
      console.log(data.exif.getAll())
      // A specific tag value:
      console.log(data.exif.get('Orientation'))
    }
  },
  { meta: true }
)

Displaying Non-TIFF EXIF tags in v3+:

loadImage(
  fileOrBlobOrUrl,
  function (img, data) {
    var exifTags = data.exif && data.exif.get('Exif')
    if (exifTags) {
      // A map of all parsed Exif tags with their mapped names/text as keys/values:
      console.log(exifTags.getAll())
      // A specific Exif tag value:
      console.log(exifTags.get('UserComment'))
    }
  },
  { meta: true }
)

Displaying EXIF GPS Info in v3+:

loadImage(
  fileOrBlobOrUrl,
  function (img, data) {
    var gpsInfo = data.exif && data.exif.get('GPSInfo')
    if (gpsInfo) {
      // A map of all parsed GPS Info tags with their mapped names/text as keys/values:
      console.log(gpsInfo.getAll())
      // A specific GPS Info tag value:
      console.log(gpsInfo.get('GPSLatitude'))
    }
  },
  { meta: true }
)

[derwaldgeist]

I was wondering the same. Would be great if these breaking changes were mentioned in the docs.