|
1 | 1 | # ORAS Go library |
2 | 2 |
|
| 3 | +[](https://github.com/oras-project/oras-go/actions/workflows/build.yml?query=workflow%3Abuild+event%3Apush+branch%3Amain) |
| 4 | +[](https://codecov.io/gh/oras-project/oras-go) |
| 5 | +[](https://goreportcard.com/report/oras.land/oras-go/v2) |
| 6 | +[](https://pkg.go.dev/oras.land/oras-go/v2) |
| 7 | + |
3 | 8 | <p align="left"> |
4 | | -<a href="https://oras.land/"><img src="https://oras.land/img/oras.svg" alt="banner" width="100px"></a> |
| 9 | +<a href="https://oras.land/"><img src="https://oras.land/img/oras.svg" alt="ORAS logo" width="100px"></a> |
5 | 10 | </p> |
6 | 11 |
|
7 | | -## Project status |
| 12 | +`oras-go` is a Go library for managing OCI artifacts, compliant with the [OCI Image Format Specification](https://github.com/opencontainers/image-spec) and the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec). It provides unified APIs for pushing, pulling, and managing artifacts across OCI-compliant registries, local file systems, and in-memory stores. |
8 | 13 |
|
9 | | -### Versioning |
| 14 | +> [!Note] |
| 15 | +> The `main` branch follows [Go's Security Policy](https://github.com/golang/go/security/policy) and supports the two latest versions of Go (currently `1.23` and `1.24`). |
10 | 16 |
|
11 | | -The ORAS Go library follows [Semantic Versioning](https://semver.org/), where breaking changes are reserved for MAJOR releases, and MINOR and PATCH releases must be 100% backwards compatible. |
| 17 | +## Getting Started |
12 | 18 |
|
13 | | -### v2: stable |
| 19 | +### Concepts |
14 | 20 |
|
15 | | -[](https://github.com/oras-project/oras-go/actions/workflows/build.yml?query=workflow%3Abuild+event%3Apush+branch%3Amain) |
16 | | -[](https://codecov.io/gh/oras-project/oras-go) |
17 | | -[](https://goreportcard.com/report/oras.land/oras-go/v2) |
18 | | -[](https://pkg.go.dev/oras.land/oras-go/v2) |
| 21 | +Gain insights into the fundamental concepts: |
19 | 22 |
|
20 | | -The version `2` is actively developed in the [`main`](https://github.com/oras-project/oras-go/tree/main) branch with all new features. |
| 23 | +- [Modeling Artifacts](docs/Modeling-Artifacts.md) |
| 24 | +- [Targets and Content Stores](docs/Targets.md) |
21 | 25 |
|
22 | | -> [!Note] |
23 | | -> The `main` branch follows [Go's Security Policy](https://github.com/golang/go/security/policy) and supports the two latest versions of Go (currently `1.21` and `1.22`). |
| 26 | +### Quickstart |
| 27 | + |
| 28 | +Follow the step-by-step tutorial to use `oras-go` v2: |
| 29 | + |
| 30 | +- [Quickstart: Managing OCI Artifacts with `oras-go` v2](docs/tutorial/quickstart.md) |
| 31 | + |
| 32 | +### Examples |
| 33 | + |
| 34 | +Check out sample code for common use cases: |
24 | 35 |
|
25 | | -Examples for common use cases can be found below: |
| 36 | +- [Artifact copying](https://pkg.go.dev/oras.land/oras-go/v2#pkg-examples) |
| 37 | +- [Registry operations](https://pkg.go.dev/oras.land/oras-go/v2/registry#pkg-examples) |
| 38 | +- [Repository operations](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote#pkg-examples) |
| 39 | +- [Authentication](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/auth#pkg-examples) |
| 40 | +- [Credentials management](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/credentials#pkg-examples) |
26 | 41 |
|
27 | | -- [Copy examples](https://pkg.go.dev/oras.land/oras-go/v2#pkg-examples) |
28 | | -- [Registry interaction examples](https://pkg.go.dev/oras.land/oras-go/v2/registry#pkg-examples) |
29 | | -- [Repository interaction examples](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote#pkg-examples) |
30 | | -- [Authentication examples](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/auth#pkg-examples) |
| 42 | +Find more API examples at [pkg.go.dev](https://pkg.go.dev/oras.land/oras-go/v2). |
31 | 43 |
|
32 | | -If you are seeking latest changes, you should use the [`main`](https://github.com/oras-project/oras-go/tree/main) branch (or a specific commit hash) over a tagged version when including the ORAS Go library in your project's `go.mod`. |
33 | | -The Go Reference for the `main` branch is available [here](https://pkg.go.dev/oras.land/oras-go/v2@main). |
34 | 44 |
|
35 | | -To migrate from `v1` to `v2`, see [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md). |
| 45 | +## Versioning |
36 | 46 |
|
37 | | -### v1: stable |
| 47 | +This project follows [Semantic Versioning](https://semver.org/) (`MAJOR`.`MINOR`.`PATCH`), with `MAJOR` for breaking changes, `MINOR` for backward-compatible features, and `PATCH` for backward-compatible fixes. |
| 48 | + |
| 49 | +## Previous Major Versions |
| 50 | + |
| 51 | +### v1 (maintenance) |
38 | 52 |
|
39 | 53 | [](https://github.com/oras-project/oras-go/actions/workflows/build.yml?query=workflow%3Abuild+event%3Apush+branch%3Av1) |
40 | 54 | [](https://goreportcard.com/report/oras.land/oras-go) |
41 | 55 | [](https://pkg.go.dev/oras.land/oras-go) |
42 | 56 |
|
43 | | -As there are various stable projects depending on the ORAS Go library `v1`, the |
44 | | -[`v1`](https://github.com/oras-project/oras-go/tree/v1) branch |
45 | | -is maintained for API stability, dependency updates, and security patches. |
46 | | -All `v1.*` releases are based upon this branch. |
47 | | - |
48 | | -Since `v1` is in a maintenance state, you are highly encouraged |
49 | | -to use releases with major version `2` for new features. |
50 | | - |
51 | | -## Docs |
| 57 | +The [`v1`](https://github.com/oras-project/oras-go/tree/v1) branch is maintained for dependency updates and security fixes only. All feature development happens in the [`main`](https://github.com/oras-project/oras-go/tree/main) branch. |
52 | 58 |
|
53 | | -- [oras.land/client_libraries/go](https://oras.land/docs/Client_Libraries/go): Documentation for the ORAS Go library |
54 | | -- [Reviewing guide](https://github.com/oras-project/community/blob/main/REVIEWING.md): All reviewers must read the reviewing guide and agree to follow the project review guidelines. |
| 59 | +To migrate from `v1` to `v2`, see [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md). |
55 | 60 |
|
56 | | -## Code of Conduct |
| 61 | +## Community |
57 | 62 |
|
58 | | -This project has adopted the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for further details. |
| 63 | +- Code of Conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) |
| 64 | +- Security Policy: [SECURITY.md](SECURITY.md) |
| 65 | +- Reviewing Guide: [Reviewing Guide](https://github.com/oras-project/community/blob/main/REVIEWING.md) |
| 66 | +- Slack: [`#oras`](https://cloud-native.slack.com/archives/CJ1KHJM5Z) channel on CNCF Slack |
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4&size=40){kind=avatar}
0 commit comments