## New Features

* Upgrade to [`image-spec v1.1.1`](https://github.com/opencontainers/image-spec/releases/tag/v1.1.1) and [`distribution-spec v1.1.1`](https://github.com/opencontainers/distribution-spec/releases/tag/v1.1.1)
* Support context cancellation in [`file.Store.Add()`](https://pkg.go.dev/oras.land/oras-go/v2@v2.6.0/content/file#Store.Add)
* Introduce [`credentials.NewMemoryStoreFromDockerConfig`](https://pkg.go.dev/oras.land/oras-go/v2@v2.6.0/registry/remote/credentials#NewMemoryStoreFromDockerConfig) to load Docker config bytes into an in-memory credentials store
* Add `PreservePermissions` option to [file store](https://pkg.go.dev/oras.land/oras-go/v2@v2.6.0/content/file#Store) to retain original permissions when extracting tar archives
* Introduce [`oras.CopyError`](https://pkg.go.dev/oras.land/oras-go/v2@v2.6.0#CopyError) to identify error sources in copy operations 

## Bug Fixes

* Fix #640: Unclear error message from `oci.NewFromTar`
* Fix #865: Symbolic links are not automatically overwritten when extracted from tar archive to File store
* Fix #851: Dot‑prefixed paths in tar archives were not recognized by `ReadOnlyOCIStore`
* Fix #880: The `index.json` generated by the OCI store lacked a `mediaType` field
* Fix #895: The `Docker-Content-Digest` header was not verified in `Repository.Blobs().Fetch()`
* Fix #916: Incorrect use of `atomic.Value` in the `syncutil.Go` utility function causes panics
* Fix #923: Pushing descriptors with invalid digests to memory or file store caused panics
* Other minor bug fixes

## Documentation

* Add documentation for artifact modeling  
* Add documentation for targets and content store  
* Add quickstart tutorial  
* Improve examples  
* Other minor improvements  

## Other Changes

* Upgrade the Go support window to `[1.23, 1.24]`
* Increase test coverage to 80%
* Update dependencies
* Minor optimization

## Detailed Commits
* fix: cancel goroutine before the next one is created by @wangxiaoxuan273 in https://github.com/oras-project/oras-go/pull/739
* build(deps): bump apache/skywalking-eyes from 0.5.0 to 0.6.0 by @dependabot in https://github.com/oras-project/oras-go/pull/740
* bump(ci): update codecov to v4 by @wangxiaoxuan273 in https://github.com/oras-project/oras-go/pull/741
* docs: update migration guide and copy doc by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/752
* test: fix file closing issue on windows by @shizhMSFT in https://github.com/oras-project/oras-go/pull/764
* docs: document PackManifestOptions to make PackManifest reproducible by @wangxiaoxuan273 in https://github.com/oras-project/oras-go/pull/749
* build: enforce diff code coverage of 80% by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/769
* fix: add missing operation to fs path error by @qweeah in https://github.com/oras-project/oras-go/pull/799
* build(deps): bump golang.org/x/sync from 0.7.0 to 0.8.0 by @dependabot in https://github.com/oras-project/oras-go/pull/801
* feat: support context cancellation in file store by @lucasrod16 in https://github.com/oras-project/oras-go/pull/803
* build(go): shift Go support window to [1.22, 1.23] by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/820
* refactor: fix seed for retry policy by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/821
* fix: check close error in `oci/storage.go` during ingestion by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/830
* chore(workflow): add stale bot by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/837
* docs: update doc for ReferrerListPageSize by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/842
* build(deps): bump golang.org/x/sync from 0.8.0 to 0.9.0 by @dependabot in https://github.com/oras-project/oras-go/pull/844
* build(deps): bump codecov/codecov-action from 4 to 5 by @dependabot in https://github.com/oras-project/oras-go/pull/847
* build(deps): bump golang.org/x/sync from 0.9.0 to 0.10.0 by @dependabot in https://github.com/oras-project/oras-go/pull/854
* test: fix test cases in content/file/utils_test.go by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/869
* fix: overwrite symlinks when extracting tarballs by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/867
* feat: introduce `credentials.NewMemoryStoreFromDockerConfig` by @programmer04 in https://github.com/oras-project/oras-go/pull/850
* fix: handle dot-prefixed path for tarfs by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/875
* test: increase unit test coverage to 80% by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/876
* build(deps): bump golang.org/x/sync from 0.10.0 to 0.11.0 by @dependabot in https://github.com/oras-project/oras-go/pull/885
* build(deps): bump apache/skywalking-eyes from 0.6.0 to 0.7.0 by @dependabot in https://github.com/oras-project/oras-go/pull/887
* build(go): shift Go support window to [1.23, 1.24] by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/893
* fix: add media type in the generated index.json file by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/894
* fix: check the `Docker-Content-Digest` header in `Repository.Blobs().Fetch()` by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/897
* feat: option to have File store preserve permissions when extracting by @sammy-da in https://github.com/oras-project/oras-go/pull/891
* build(deps): bump github.com/opencontainers/image-spec from 1.1.0 to 1.1.1 by @dependabot in https://github.com/oras-project/oras-go/pull/906
* chore: update to `image-spec v1.1.1` by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/909
* docs: add concepts of modeling artifacts by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/912
* docs: add concepts of targets by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/917
* build(deps): bump golang.org/x/sync from 0.11.0 to 0.12.0 by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/919
* fix: fix concurrency bugs causing panics and race conditions in `internal/syncutil` by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/921
* fix: fix panics caused by bad digests by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/926
* docs: update example tests by @wangxiaoxuan273 in https://github.com/oras-project/oras-go/pull/932
* build(deps): bump golang.org/x/sync from 0.12.0 to 0.13.0 by @dependabot in https://github.com/oras-project/oras-go/pull/937
* feat: introduce `CopyError` to identify error source in copy operations by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/933
* docs: improve docs for OCI store by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/941
* docs: add more practical examples by @wangxiaoxuan273 in https://github.com/oras-project/oras-go/pull/940
* test: add unit tests for validateMediaType by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/946
* docs: add quick start for oras-go by @wangxiaoxuan273 in https://github.com/oras-project/oras-go/pull/939
* docs: updated broken links by @wangxiaoxuan273 in https://github.com/oras-project/oras-go/pull/951
* docs: improve README.md by @Wwwsylvia in https://github.com/oras-project/oras-go/pull/950
* build(deps): bump golang.org/x/sync from 0.13.0 to 0.14.0 by @dependabot in https://github.com/oras-project/oras-go/pull/955

## New Contributors
* @lucasrod16 made their first contribution in https://github.com/oras-project/oras-go/pull/803
* @programmer04 made their first contribution in https://github.com/oras-project/oras-go/pull/850
* @sammy-da made their first contribution in https://github.com/oras-project/oras-go/pull/891

**Full Changelog**: https://github.com/oras-project/oras-go/compare/v2.5.0...v2.6.0

> [!TIP]
> Upgrade to `v2.5.0` for optimal performance when compiled with Go `1.22` or later.

> [!WARNING]
> `v2.5.0` does not compile with Go `1.20.x` or earlier.

## New Features

* Upgrade to [`image-spec v1.1.0`](https://github.com/opencontainers/image-spec/releases/tag/v1.1.0) and [`distributio-spec v1.1.0`](https://github.com/opencontainers/distribution-spec/releases/tag/v1.1.0)
  * Introduce `oras.PackManifestVersion1_1` for packing [OCI Image Manifest](https://github.com/opencontainers/image-spec/blob/v1.1.0/manifest.md) defined in `image-spec v1.1.0`

## Deprecation

* `oras.PackManifestVersion1_1_RC4` is deprecated and not recommended for future use. Use `oras.PackManifestVersion1_1` instead.

## Bug Fixes

* Fix #698: [`registry.ParseReference`](https://pkg.go.dev/oras.land/oras-go/v2/registry#ParseReference) returns false positive when registry is empty
* Fix #727: Subsequent calls to [`credentials.DynamicStore.Put`](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/credentials#DynamicStore.Put) will not set the detected credential store after the first failed attempt
* Fix #730: [`file.Store`](https://pkg.go.dev/oras.land/oras-go/v2/content/file#Store) has race conditions when restoring content with the same name

## Other Changes

* Update the Go support window to `[1.21, 1.22]`
* Update unit tests and examples
* Improve performance



## Detailed Commits
* build(deps): bump github.com/opencontainers/image-spec from 1.1.0-rc6 to 1.1.0 by @dependabot in https://github.com/oras-project/oras-go/pull/708
* feat: upgrade to distribution-spec v1.1.0 by @wangxiaoxuan273 in https://github.com/oras-project/oras-go/pull/720
* build: bump go version by @dextrot in https://github.com/oras-project/oras-go/pull/715
* test: add a new case for UnwrapNopCloser by @shizhMSFT in https://github.com/oras-project/oras-go/pull/725
* perf: use new built-in methods introduced before go 1.22 by @shizhMSFT in https://github.com/oras-project/oras-go/pull/726
* fix: check empty registry name by @shizhMSFT in https://github.com/oras-project/oras-go/pull/729
* fix(DynamicStore): retry `setCredsStore` on next `PUT` by @shizhMSFT in https://github.com/oras-project/oras-go/pull/728
* fix(file.Store): fix race condition on restoring the same named content by @shizhMSFT in https://github.com/oras-project/oras-go/pull/731

## New Contributors
* @dextrot made their first contribution in https://github.com/oras-project/oras-go/pull/715

**Full Changelog**: https://github.com/oras-project/oras-go/compare/v2.4.0...v2.5.0