diff --git a/.changes/header.tpl.md b/.changes/header.tpl.md new file mode 100644 index 000000000..825c32f0d --- /dev/null +++ b/.changes/header.tpl.md @@ -0,0 +1 @@ +# Changelog diff --git a/.changes/unreleased/migrated-1.yaml b/.changes/unreleased/migrated-1.yaml new file mode 100644 index 000000000..4e2b16cc6 --- /dev/null +++ b/.changes/unreleased/migrated-1.yaml @@ -0,0 +1,3 @@ +kind: Changed +body: "`toString()` of credential-bearing structures (`B2AccountAuthorization`, `B2FileSseForRequest`, `B2WebhookConfiguration`, `B2WebhookCustomHeader`, and `B2HeadersImpl`) omits sensitive values; `B2WebhookCustomHeader` omits all header values." +time: 2026-11-16T00:00:00Z diff --git a/.changes/unreleased/migrated-2.yaml b/.changes/unreleased/migrated-2.yaml new file mode 100644 index 000000000..0770b706e --- /dev/null +++ b/.changes/unreleased/migrated-2.yaml @@ -0,0 +1,3 @@ +kind: Changed +body: "`B2EventNotificationRule` now orders and deduplicates rules by `maxEventsPerBatch`, so rules that differ only by batch size no longer collapse in sorted collections; it also uses direct webhook settings instead of the former string-based order (url, headers, then signing secret), so callers that persist or diff ordered rules may observe a different order." +time: 2026-11-16T00:00:00Z diff --git a/.changes/unreleased/migrated-3.yaml b/.changes/unreleased/migrated-3.yaml new file mode 100644 index 000000000..a3622dee1 --- /dev/null +++ b/.changes/unreleased/migrated-3.yaml @@ -0,0 +1,3 @@ +kind: Changed +body: "Security / behaviour change: the three-argument `B2EventNotification.parse` overloads now require a signature header and a signing secret; receivers should answer HTTP 401 on `B2SignatureVerificationException`.\n A missing or empty signature header throws `B2SignatureVerificationException`; a null or empty signing secret throws `IllegalArgumentException`." +time: 2026-11-16T00:00:00Z diff --git a/.changes/unreleased/migrated-4.yaml b/.changes/unreleased/migrated-4.yaml new file mode 100644 index 000000000..7705c8fa0 --- /dev/null +++ b/.changes/unreleased/migrated-4.yaml @@ -0,0 +1,3 @@ +kind: Changed +body: "Signature comparison is now constant-time." +time: 2026-11-16T00:00:00Z diff --git a/.changes/unreleased/migrated-5.yaml b/.changes/unreleased/migrated-5.yaml new file mode 100644 index 000000000..3f0d67c26 --- /dev/null +++ b/.changes/unreleased/migrated-5.yaml @@ -0,0 +1,3 @@ +kind: Added +body: "Added `B2EventNotification.parseUnverified`, which parses without checking a signature. The one-argument `parse` overloads are deprecated in its favor." +time: 2026-11-16T00:00:00Z diff --git a/.changes/unreleased/release-preparation.yaml b/.changes/unreleased/release-preparation.yaml new file mode 100644 index 000000000..2f79be178 --- /dev/null +++ b/.changes/unreleased/release-preparation.yaml @@ -0,0 +1,3 @@ +kind: Changed +body: Document release preparation and generate the changelog and Gradle version from Changie release notes. +time: 2026-11-17T00:00:00Z diff --git a/.changes/v0.0.6.md b/.changes/v0.0.6.md new file mode 100644 index 000000000..263a38ed1 --- /dev/null +++ b/.changes/v0.0.6.md @@ -0,0 +1,24 @@ +## [0.0.6] - 2017-08-17 +### Added +* These changes were driven by switching our internal b2-sdk uses to use the http client from the sdk instead of a +different, custom interface. + +[Unreleased]: https://github.com/Backblaze/b2-sdk-java/compare/v6.4.0...HEAD +[6.4.0]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v6.4.0 +[6.3.0]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v6.3.0 +[6.2.1]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v6.2.1 +[6.2.0]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v6.2.0 +[6.1.1]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v6.1.1 +[6.1.0]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v6.1.0 +[6.0.0]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v6.0.0 +[5.0.0]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v5.0.0 +[4.0.0]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v4.0.0 +[3.1.0]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v3.1.0 +[3.0.0]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v3.0.0 +[2.0.0]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v2.0.0 +[1.4.0]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v1.4.0 +[1.3.0]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v1.3.0 +[1.2.0]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v1.2.0 +[1.1.1]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v1.1.1 +[1.0.0]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v1.0.0 +[0.0.6]: https://github.com/Backblaze/b2-sdk-java/releases/tag/v-0.0.6-alpha diff --git a/.changes/v1.0.0.md b/.changes/v1.0.0.md new file mode 100644 index 000000000..78125779a --- /dev/null +++ b/.changes/v1.0.0.md @@ -0,0 +1,10 @@ +## [1.0.0] - 2017-09-08 +### Added +* We have been using the SDK in production for a while at Backblaze and we're feature complete (for now), so we're going 1.0! + + We hope you enjoy it. + + Please let us know how it works for you. :) + + thanks, + ab diff --git a/.changes/v1.1.1.md b/.changes/v1.1.1.md new file mode 100644 index 000000000..b3a01e4f1 --- /dev/null +++ b/.changes/v1.1.1.md @@ -0,0 +1,11 @@ +## [1.1.1] - 2017-11-01 +### Added +* B2FileVersion now has string constants for "actions" +* Download request objects now have an optional 'b2ContentDisposition' field. +* B2StorageClient now has `getDownloadByIdUrl()` and `getDownloadByNameUrl()` +* B2 command-line program now has an option to get_download_authorization +* List buckets now has an optional 'bucketTypes' field. + +### Fixed +* Percent encode file names when downloading by name +* Large file uploader now uses RetryPolicySupplier in all cases, instead of just part of the code. diff --git a/.changes/v1.2.0.md b/.changes/v1.2.0.md new file mode 100644 index 000000000..0d5b3a870 --- /dev/null +++ b/.changes/v1.2.0.md @@ -0,0 +1,18 @@ +## [1.2.0] - 2017-11-30 +### Added +* Adds support setting CorsRules on buckets. +* B2StorageClient now exposes the following methods. + You should read the comments about why you probably + want to let the SDK handle things for you instead + of calling them. ;) + - `getAccountAuthorization()` + - `getUploadUrl()` + - `getUploadPartUrl()` + +### Fixed +* Speeds up writing json (by doing custom UTF8 encoding instead of using the generic java versions). + (and a bug fix which changed the behavior of B2Json.toJson(...outputStream) to not close the stream.) +* While uploading a large file, the caller provides a ExecutorService. + if that service rejects a task we submit, we throw a + B2LocalException instead of letting the RejectedExecutionException + (a RuntimeException) percolate up. diff --git a/.changes/v1.3.0.md b/.changes/v1.3.0.md new file mode 100644 index 000000000..ea66ce2e3 --- /dev/null +++ b/.changes/v1.3.0.md @@ -0,0 +1,12 @@ +## [1.3.0] - 2018-05-04 +### Added +* Add `deleteAllFilesInBucket()` and `getFileInfoByName()`. (thanks, valenpo!) +* Add support for upcoming ApplicationKeys apis. (thanks, valenpo!) +* Expose `startLargeFile()` and `finishLargeFile()` +* Add support for "union types" in B2Json. +* Add default codes for exception classes so `B2Exception.create()` can be used for HEAD. + +### Fixed +* Explicitly set user-agent on HttpClient to keep HttpClient from doing a bunch of unneeded work. +* Improve use of clocks in unit tests to make the tests less order dependent. +* Make search for "file info" headers in B2Headers check header names case-insensitively! diff --git a/.changes/v1.4.0.md b/.changes/v1.4.0.md new file mode 100644 index 000000000..2b25dec66 --- /dev/null +++ b/.changes/v1.4.0.md @@ -0,0 +1,6 @@ +## [1.4.0] - 2018-05-23 +### Added +* Add BigInteger support to B2Json. + +### Fixed +* Percent decoding of file name returned from `getFileInfoByName()` diff --git a/.changes/v2.0.0.md b/.changes/v2.0.0.md new file mode 100644 index 000000000..db12f4868 --- /dev/null +++ b/.changes/v2.0.0.md @@ -0,0 +1,11 @@ +## [2.0.0] - 2018-10-17 +### Changed `[Incompatible]` +* The SDK now uses version 2 of the B2 APIs, which deals with restricted application keys differently +* B2Json type handler interface takes B2JsonOptions as a parameter, and not an int bitmask + +### Added +* B2Json support for versioned structures + +### Fixed +* Remembering account ID after authorizing with application key +* B2Json now serialized unions correctly diff --git a/.changes/v3.0.0.md b/.changes/v3.0.0.md new file mode 100644 index 000000000..20db9376a --- /dev/null +++ b/.changes/v3.0.0.md @@ -0,0 +1,5 @@ +## [3.0.0] - 2019-05-01 +### Added +* Renaming the application key terminology to the new convention +* Being able to call `b2FromJsonOrThrow()` to check if you can parse + a JSON String into a given object diff --git a/.changes/v3.1.0.md b/.changes/v3.1.0.md new file mode 100644 index 000000000..6fb978e79 --- /dev/null +++ b/.changes/v3.1.0.md @@ -0,0 +1,25 @@ +## [3.1.0] - 2019-05-16 +### Added +* Added `@B2Json.sensitive` annotation to redact fields when B2Json is + used with the new redactSensitive option set to true. +* Added `B2ContentSource.createContentSourceWithRangeOrNull()` which + is used by the large file uploader to give the content source the + opportunity to make a more efficient content source for a range of + the file. this is really useful if the content isn't coming from + memory or a local file because the default implementation reads + and discards data to get to the desired range. Added sample + UploadLargeFileFromUrl and UrlContentSource. +* Added support for using okhttp3 as the HTTP client instead of + Apache's HttpClient. there are limitations with this + implementation for uploading files that are about 2GB or + larger. See README.md for details. +* Added B2StorageClientFactory interface for creating + B2StorageClients without having to select a particular + implementation at build time. The static `createDefaultFactory()` + method can be used to create a B2StorageClient using either of the + two official web client implementations, whichever is in the + classpath at runtime. The sample programs use this now so they + can be used with either web client implementation. + +### Fixed +* Don't use default character set in B2Json; explicitly use UTF8. diff --git a/.changes/v4.0.0.md b/.changes/v4.0.0.md new file mode 100644 index 000000000..7b9c19c63 --- /dev/null +++ b/.changes/v4.0.0.md @@ -0,0 +1,24 @@ +## [4.0.0] - 2020-05-11 +### Added +* Removed the deprecated okhttp client +* Added 'readBuckets' and 'listAllBucketNames' application key capability names +* Added the "Expect: 100-continue" header to upload file/part requests +* Validates file info header name characters against RFC 7230 (https://tools.ietf.org/html/rfc7230#section-3.2) +* B2Json: +* Add general generics support to B2Json +* Allow generic types for top-level objects from select entry points +* Add support for parameterized classes that contain generic arrays +* Add support for CharSequence +* Add an omitNull parameter to @B2Json.optional +* Disabled URI normalization in Apache HttpClient +* Extended B2FileVersion and B2Part to include contentMd5 +* Added support to override additional download headers +* Added optional 'options' parameter in the B2Bucket and B2ApplicationKey constructor +* Added b2_copy_file support +* Added progress reporting in the B2LargeFileStorer +* Updated to version `4.5.9` of `org.apache.httpcomponents:httpclient` +* B2Bucket and B2ApplicationKey both have an `options` parameter in the constructor. These are optional. +* `B2StorageClient.DownloadByName` supports downloading files with looser naming requirements, e.g. names containing double slashes (`//`). + +### Fixed +* See the closed issues for a complete list diff --git a/.changes/v5.0.0.md b/.changes/v5.0.0.md new file mode 100644 index 000000000..47d6b865c --- /dev/null +++ b/.changes/v5.0.0.md @@ -0,0 +1,15 @@ +## [5.0.0] - 2021-05-10 +### Changed `[Incompatible]` +* Disabled automatic decompression of compressed content in HTTP client download library +* Added `updateFileRetention` and `updateLegalHold` to `B2StorageClient` +* Added `storeLargeFileFromLocalContentAsync` to `B2StorageClient` to support asynchronous large file uploads + +### Added +* Added Server-Side Encryption (SSE) support to relevant API requests/responses +* Added File Lock support to relevant API requests/responses +* Set gradle targetCompatibility to 1.8 +* Added support for java.util.SortedMap interface +* Support more than 64 fields per object + +### Fixed +* Fixed regular expression that had an unescaped '.' diff --git a/.changes/v5.1.0.md b/.changes/v5.1.0.md new file mode 100644 index 000000000..6bb61639a --- /dev/null +++ b/.changes/v5.1.0.md @@ -0,0 +1,6 @@ +## [5.1.0] - 2022-05-06 +### Added +* Added `s3ApiUrl` to `B2AccountAuthorization`. +* Updated to version `4.5.13` of `org.apache.httpcomponents:httpclient` +* Updated to version `4.13.2` of `junit:junit` +* Added Replication Configuration to Create Bucket and Update Bucket API requests/responses diff --git a/.changes/v6.0.0.md b/.changes/v6.0.0.md new file mode 100644 index 000000000..f3bda9288 --- /dev/null +++ b/.changes/v6.0.0.md @@ -0,0 +1,6 @@ +## [6.0.0] - 2022-06-03 +### Changed `[Incompatible]` +* Updated `includeExistingFiles` to be required on B2ReplicationRule + +### Added +* Updated to version `1.15` of `commons-codec`. diff --git a/.changes/v6.1.0.md b/.changes/v6.1.0.md new file mode 100644 index 000000000..587f73e21 --- /dev/null +++ b/.changes/v6.1.0.md @@ -0,0 +1,5 @@ +## [6.1.0] - 2022-09-19 +### Added +* Added support for custom upload timestamps +* Added support for Java 8's `-parameters` option so constructor parameters do not need to be reiterated in `B2Json.constructor#params` +* Added `fileLockEnabled` to `B2UpdateBucketRequest` to support enabling file lock on existing buckets diff --git a/.changes/v6.1.1.md b/.changes/v6.1.1.md new file mode 100644 index 000000000..98fdf832a --- /dev/null +++ b/.changes/v6.1.1.md @@ -0,0 +1,8 @@ +## [6.1.1] - 2022-11-10 +### Added +* Return a subtype of `B2Exception` on errors when the response body does not conform to `B2ErrorStructure`. + Returning a `B2Exception` subtype enables the `B2Retryer` to retry exceptions that may succeed on retry. + +### Fixed +* Fixed B2ListFilesIterableBase assuming a response with 0 results was the end. It now looks for + `nextFileName` being null to indicate the end. diff --git a/.changes/v6.2.0.md b/.changes/v6.2.0.md new file mode 100644 index 000000000..7e4c59056 --- /dev/null +++ b/.changes/v6.2.0.md @@ -0,0 +1,47 @@ +## [6.2.0] - 2024-04-15 +### Added +* Added support to specify B2Json union types using annotations. Annotation support for union types is required because + Java records do not support inheritance. Example usage: + ```java + @B2Json.union(typeField = "type") + @B2Json.unionSubtypes({ + @B2Json.unionSubtypes.type(name = "email", clazz = Email.class), + @B2Json.unionSubtypes.type(name = "sms", clazz = Sms.class) + }) + sealed interface Message permits Email, Sms { + String subject(); + } + + @B2Json.type + private record Email(@B2Json.required String subject, @B2Json.required String email) implements Message { + } + + @B2Json.type + private record Sms(@B2Json.required String subject, @B2Json.required String phoneNumber) implements Message { + } + ``` +* Added `@B2Json.type` annotation that can be used with Java records. Using `@B2Json.type` allows for the implicit + Java constructor of Java records to not require the `@B2Json.constructor` annotation. Example usage: + ```java + @B2Json.type + record Point(@B2Json.required int x, @B2Json.required int y) { } + ``` +* Added support for B2 Event Notifications +* Added B2Json `fromJson` methods that take a `java.io.Reader` as input for JSON +* Added B2StorageClient.storePartsForLargeFile +* Added support for daysFromStartingToCancelingUnfinishedLargeFiles to B2LifecycleRule +* Added the `serializedName` annotation to rename the serialized Json member name +* Added support for AtomicLongArray in B2Json +* Added support for custom upload timestamps + +### Changed +* Optimized `B2DateTimeUtil.formatFguidDateTime` +* Reduced memory allocation for small input when deserializing byte[] to JSON +* Reduced lock contention in B2Clock +* Updated B2Json `fromJson` methods to utilize a BufferedReader when deserializing JSON for performance improvement +* Reduced lock contention in B2AccountAuthorizationCache +* Reduced lock contention in B2Json +* Updated internal python for building to python3 + +### Fixed +* Fixed union types to ignore extra and discarded fields when deserializing JSON to Java objects diff --git a/.changes/v6.2.1.md b/.changes/v6.2.1.md new file mode 100644 index 000000000..b6bdbbc5b --- /dev/null +++ b/.changes/v6.2.1.md @@ -0,0 +1,3 @@ +## [6.2.1] - 2024-07-16 +### Added +* Added `eventId` field to `B2EventNotificationEvent`. diff --git a/.changes/v6.3.0.md b/.changes/v6.3.0.md new file mode 100644 index 000000000..42b10c3cd --- /dev/null +++ b/.changes/v6.3.0.md @@ -0,0 +1,7 @@ +## [6.3.0] - 2024-11-08 +### Added +* Fixed `B2StorageClient.deleteAllFilesInBucket` so it uses `fileVersions` instead of `fileNames`. +* Added `maxEventsPerBatch` field to `B2WebhookConfiguration`. + +### Changed +* Validate idle connections after 2 seconds of inactivity diff --git a/.changes/v6.4.0.md b/.changes/v6.4.0.md new file mode 100644 index 000000000..9a17e78a2 --- /dev/null +++ b/.changes/v6.4.0.md @@ -0,0 +1,4 @@ +## [6.4.0] - 2025-05-14 +### Added +* Add `readBucketLogging` and `writeBucketLogging` capabilities. +* Close idle connections after 4 seconds of inactivity. diff --git a/.changes/v6.5.0.md b/.changes/v6.5.0.md new file mode 100644 index 000000000..5c35ce2ba --- /dev/null +++ b/.changes/v6.5.0.md @@ -0,0 +1,2 @@ +## [6.5.0] - 2025-12-15 +* Add `readBucketLifecycleRules` and `writeBucketLifecycleRules` capabilities. diff --git a/.changie.yaml b/.changie.yaml new file mode 100644 index 000000000..c5a62b230 --- /dev/null +++ b/.changie.yaml @@ -0,0 +1,32 @@ +changesDir: .changes +unreleasedDir: unreleased +headerPath: header.tpl.md +changelogPath: CHANGELOG.md +versionExt: md +versionFormat: '## [{{.VersionNoPrefix}}] - {{.Time.Format "2006-01-02"}}' +kindFormat: '### {{.Kind}}' +changeFormat: '* {{.Body}}' +footerFormat: '[{{.VersionNoPrefix}}]: https://github.com/Backblaze/b2-sdk-java/releases/tag/{{.Version}}' +kinds: + - label: Added + auto: minor + - label: Changed + auto: minor + - label: Deprecated + auto: minor + - label: Removed + auto: major + - label: Fixed + auto: patch + - label: Security + auto: patch +newlines: + afterChangelogHeader: 0 + beforeChangelogVersion: 1 + endOfVersion: 1 + afterKind: 1 + beforeKind: 1 +replacements: + - path: gradle.properties + find: '^version=.*' + replace: 'version={{.VersionNoPrefix}}' diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml new file mode 100644 index 000000000..18a039614 --- /dev/null +++ b/.github/workflows/changelog.yml @@ -0,0 +1,42 @@ +# Copyright 2026, Backblaze Inc. All Rights Reserved. +# License https://www.backblaze.com/using_b2_code.html + +name: Changelog + +on: + pull_request: + branches: [master, api-v2, 7.x] + push: + branches: [master] + +permissions: + contents: read + +jobs: + changelog-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + fetch-depth: 0 + persist-credentials: false + - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5 + with: + go-version: '1.24.0' + cache: false + - name: Install Changie + run: go install github.com/miniscruff/changie@v1.24.0 + - name: Validate changelog + env: + BASE_SHA: ${{ github.event.pull_request.base.sha }} + PR_AUTHOR: ${{ github.event.pull_request.user.login }} + run: | + flags=() + if [ "$PR_AUTHOR" = 'dependabot[bot]' ]; then flags=(--dependabot); fi + if [ -n "$BASE_SHA" ]; then + python3 scripts/release.py changelog-check --base "$BASE_SHA" "${flags[@]}" + else + python3 scripts/release.py changelog-check + fi + - name: Test release metadata checks + run: python3 -m unittest discover -s scripts/tests -v diff --git a/.gitignore b/.gitignore index b63368639..6fd4dd8f7 100644 --- a/.gitignore +++ b/.gitignore @@ -12,5 +12,6 @@ out/ hs_err_pid* .DS_Store +__pycache__/ !gradle/wrapper/gradle-wrapper.jar diff --git a/CHANGELOG.md b/CHANGELOG.md index 1c43cf915..ef15c1585 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,17 +1,8 @@ # Changelog -## [Unreleased] -### Changed -* `toString()` of credential-bearing structures (`B2AccountAuthorization`, `B2FileSseForRequest`, `B2WebhookConfiguration`, `B2WebhookCustomHeader`, and `B2HeadersImpl`) omits sensitive values; `B2WebhookCustomHeader` omits all header values. -* `B2EventNotificationRule` now orders and deduplicates rules by `maxEventsPerBatch`, so rules that differ only by batch size no longer collapse in sorted collections; it also uses direct webhook settings instead of the former string-based order (url, headers, then signing secret), so callers that persist or diff ordered rules may observe a different order. -* Security / behaviour change: the three-argument `B2EventNotification.parse` overloads now require a signature header and a signing secret; receivers should answer HTTP 401 on `B2SignatureVerificationException`. - A missing or empty signature header throws `B2SignatureVerificationException`; a null or empty signing secret throws `IllegalArgumentException`. -* Signature comparison is now constant-time. - -### Added -* Added `B2EventNotification.parseUnverified`, which parses without checking a signature. The one-argument `parse` overloads are deprecated in its favor. ## [6.5.0] - 2025-12-15 -* Add `readBucketLifecycleRules` and `writeBucketLifecycleRules` capabilities. +* Add `readBucketLifecycleRules` and `writeBucketLifecycleRules` capabilities. + ## [6.4.0] - 2025-05-14 ### Added * Add `readBucketLogging` and `writeBucketLogging` capabilities. diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 000000000..375e02543 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,176 @@ +# Releasing the B2 SDK for Java + +A release is a reviewed version commit on `master`, an annotated, signed `vX.Y.Z` tag on that +commit, and the same version published to Maven Central. This process follows the release-prep +approach in [Blazer's release guide](https://github.com/Backblaze/blazer/blob/main/RELEASE.md). + +## Prerequisites + +- JDK 11 and the checked-in Gradle wrapper; the build also runs the JDK 17 test module. +- Python 3, Git, GitHub CLI (`gh auth status`), GnuPG or OpenSSH for tag signing. +- Changie v1.24.0, a standalone Go binary. Install with + `go install github.com/miniscruff/changie@v1.24.0` using Go 1.24 or newer, then put + `$(go env GOPATH)/bin` on `PATH`. This does not change the Java toolchain. +- Maven Central publishing credentials and artifact-signing secrets remain configured for + `.github/workflows/deploy.yml`: `SONATYPE_TOKEN_USERNAME`, `SONATYPE_TOKEN_PASSWORD`, + `GPG_SIGNING_KEY`, and `GPG_PASSPHRASE`. Tag signing and Maven artifact signing are separate. + +Do not run a publishing task locally as a verification step. A tag push starts the production +deployment, including closing and releasing the Sonatype staging repository. + +## Changelog and versioning + +Use semantic versioning: fixes use a patch release, compatible features a minor release, and +incompatible changes a major release. Choose the version explicitly; a `Changed` entry alone +does not determine whether the release is compatible. + +Each PR adds a fragment rather than editing `CHANGELOG.md`: + +```bash +changie new --kind Fixed --body 'Describe the observable change.' +python3 scripts/release.py changelog-check +python3 -m unittest discover -s scripts/tests -v +``` + +Kinds are Added, Changed, Deprecated, Removed, Fixed, and Security. Keep unpublished security +details out of public fragments. Existing release history is preserved in `.changes/v*.md`; +unreleased changes live in `.changes/unreleased/*.yaml`. `CHANGELOG.md` contains the generated +released history. `changie merge` also sets `version=` in `gradle.properties` from the latest +version notes. Do not edit the generated changelog or bump the Gradle version independently. +The `changelog-check` CI job verifies generated output, version consistency, and a fragment for +each PR (or a complete batch and version update for a release-prep PR). +Dependabot PRs that only modify existing workflow YAML files do not need a release fragment; +generated-output checks and the release-tooling tests still run. Source/dependency changes outside +workflow files and human-authored changes still need a fragment. + +## Milestones and release preparation + +1. Select the version and create its milestone before preparing the release. Assign every + intended issue and PR to it. Publicly track public work only; unpublished advisories remain + in GitHub Security Advisories. Deferred work moves to the next milestone with a written reason. + + ```bash + export VERSION=6.5.1 # choose the actual next version + export TAG="v$VERSION" + gh api --method POST repos/Backblaze/b2-sdk-java/milestones -f title="$TAG" + gh issue edit --milestone "$TAG" + gh pr edit --milestone "$TAG" + git fetch origin master --tags + git switch -c "release/$TAG" origin/master + ``` + +2. Confirm the release scope has merged and the relevant CI checks are green. Check the + repository Security tab: an open medium, high, or critical finding holds the release, + including findings without a patched dependency. Failures to read findings are unverified, + not clean. A maintainer must resolve or dismiss findings with a written reason before release. + +3. Batch the changelog and update the version in one operation: + + ```bash + changie batch "$TAG" --dry-run --allow-no-changes=false + changie batch "$TAG" --allow-no-changes=false + changie merge + python3 scripts/release.py changelog-check + python3 scripts/release.py notes "$TAG" > /tmp/b2-java-release-notes.md + git diff -- gradle.properties CHANGELOG.md .changes/ + ``` + + Review the generated `.changes/$TAG.md` and regenerate with `changie merge` after any edits. + A release-prep PR changes only `.changes/`, `CHANGELOG.md`, and `gradle.properties`. Keep + workflow or SDK behavior changes in separate PRs. + +4. Verify locally without publishing: + + ```bash + python3 -m unittest discover -s scripts/tests -v + ./gradlew build --no-daemon + RELEASE_BUILD=true ./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository \ + createBundle --dry-run --no-daemon \ + -PsonatypeUsername=dry-run -PsonatypePassword=dry-run + ``` + + The placeholder credentials are only for task-graph validation with `--dry-run`; this does + not contact Sonatype, sign artifacts, or prove that production secrets are usable. + Run the local health check below against a fresh loopback simulator as well. + +5. Commit and open a release-prep PR linked to its issue, assign its milestone, and request a + maintainer review. Include the release notes, build, health-check, and dry-run results. + A human merges it after required CI and review pass. Do not tag an unmerged PR. + +## Tag and deploy + +Tag the merged release-prep commit, which may differ from the latest tip of `master`: + +```bash +: "${TAG:?export the release tag, e.g. v6.5.1}" +VERSION="${TAG#v}" +git fetch origin master --tags +SHA=$(gh pr view --json mergeCommit --jq .mergeCommit.oid) +git merge-base --is-ancestor "$SHA" origin/master +git show "$SHA:gradle.properties" | grep -Fx "version=$VERSION" +git log -1 --oneline "$SHA" + +# GPG: use your full signing-key fingerprint. +git -c gpg.format=openpgp tag -s -u "$TAG" "$SHA" -m "$TAG" +git verify-tag "$TAG" + +# Alternatively, with a registered SSH signing key: +# git -c gpg.format=ssh -c user.signingkey="$HOME/.ssh/id_ed25519.pub" \ +# tag -s "$TAG" "$SHA" -m "$TAG" +# git -c gpg.format=ssh -c gpg.ssh.allowedSignersFile= verify-tag "$TAG" + +git push origin "$TAG" +``` + +The tag-triggered deploy workflow publishes using the existing Gradle command: + +```bash +./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository createBundle --no-daemon --stacktrace +``` + +Maven Central, GPG artifact signing, the Sonatype staging endpoint, and the release/close tasks +are unchanged by the changelog tooling. Never run this production command as a dry-run substitute. + +## Verify the published release + +1. Inspect the deployment run for the tag and confirm the Sonatype close/release step succeeded: + `gh run list --workflow deploy.yml --branch "$TAG"` and `gh run view --log-failed`. +2. Confirm the GitHub Release contains this version's changelog section and all three module bundles: + `gh release view "$TAG" --json tagName,body,assets`. +3. After Maven Central indexing completes, check each module and its signature: + + ```bash + for module in core httpclient samples; do + url="https://repo.maven.apache.org/maven2/com/backblaze/b2/b2-sdk-$module/$VERSION/b2-sdk-$module-$VERSION.pom" + curl --fail --show-error --location "$url" -o "/tmp/b2-sdk-$module-$VERSION.pom" + curl --fail --show-error --location "$url.asc" -o "/tmp/b2-sdk-$module-$VERSION.pom.asc" + gpg --verify "/tmp/b2-sdk-$module-$VERSION.pom.asc" "/tmp/b2-sdk-$module-$VERSION.pom" + done + ``` + + Verify using the established Maven artifact-signing public key, independently of tag keys. +4. Confirm there are no open issues/PRs left in the version milestone, then close it. Publish any + advisories coordinated with the release only after the fixed artifacts are available. + +## Local health check + +Use a local B2 simulator with the fixed test credentials and an empty `sdkharness-healthcheck` +bucket. This check authorizes, uploads, downloads, compares bytes, lists, and deletes; it refuses +non-loopback endpoints. It must print `SDKHARNESS_RESULT` with `health`, `golden-path`, and `PASS`. +Set `SDKHARNESS_SIMULATOR_URL` to the running simulator's IPv4 loopback URL, then run: + +```bash +: "${SDKHARNESS_SIMULATOR_URL:?set the local simulator URL, e.g. http://127.0.0.1:8180}" +./gradlew build --no-daemon +CP=$(./gradlew -q -I scripts/health-classpath.gradle :b2-sdk-httpclient:healthClasspath) +SDKHARNESS_TEST_LEVEL=health SDKHARNESS_SCENARIO=golden-path \ + B2_BUCKET_NAME=sdkharness-healthcheck SDKHARNESS_JAVA_CLASSPATH="$CP" \ + .sdkharness/tests/run-health +``` + +## Recovery + +Never move a published tag or reuse a Maven Central version. If a release fails, inspect staging +and Central before retrying: the existing deploy command closes and releases staging repositories. +Do not blindly rerun a partially completed publish. If artifacts are already published, ship a new +patch version. Reverting SDK code does not remove artifacts already used by consumers. diff --git a/scripts/health-classpath.gradle b/scripts/health-classpath.gradle new file mode 100644 index 000000000..c60a3f873 --- /dev/null +++ b/scripts/health-classpath.gradle @@ -0,0 +1,12 @@ +// Prints the SDK and dependency classpath after ./gradlew build; does not change publication tasks. +allprojects { + afterEvaluate { + if (path == ':b2-sdk-httpclient') { + tasks.register('healthClasspath') { + doLast { + println sourceSets.main.runtimeClasspath.asPath + } + } + } + } +} diff --git a/scripts/release.py b/scripts/release.py new file mode 100644 index 000000000..df0fad218 --- /dev/null +++ b/scripts/release.py @@ -0,0 +1,99 @@ +#!/usr/bin/env python3 +"""Release metadata checks. Uses the standard library and the pinned Changie binary.""" + +import argparse +import os +import pathlib +import re +import shutil +import subprocess +import sys +import tempfile + + +VERSION = r"[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?" + + +def project_version(root): + versions = re.findall(r"^version=(.+)$", (root / "gradle.properties").read_text(), re.M) + if len(versions) != 1 or not re.fullmatch(VERSION, versions[0]): + raise ValueError("gradle.properties must contain exactly one semantic version property") + return versions[0] + + +def release_notes(root, tag): + if not re.fullmatch("v" + VERSION, tag): + raise ValueError("expected a version tag such as v6.5.1") + if tag != "v" + project_version(root): + raise ValueError("tag does not match gradle.properties") + path = root / ".changes" / (tag + ".md") + if not path.is_file(): + raise ValueError("release notes are missing: " + path.name) + notes = path.read_text().strip() + heading = re.escape("## [" + tag[1:] + "]") + section = re.search(r"^" + heading + r"[^\n]*\n.*?(?=^## \[|\Z)", + (root / "CHANGELOG.md").read_text(), re.M | re.S) + if not section or notes != section.group().strip(): + raise ValueError("release notes and CHANGELOG.md disagree; run changie merge") + return notes + "\n" + + +def changelog_check(root, base, dependabot=False): + changie = os.environ.get("CHANGIE", "changie") + fragments = list((root / ".changes/unreleased").glob("*.yaml")) + with tempfile.TemporaryDirectory(prefix="b2-changelog-") as temporary: + target = pathlib.Path(temporary) + shutil.copy(root / ".changie.yaml", target) + shutil.copy(root / "gradle.properties", target) + shutil.copytree(root / ".changes", target / ".changes") + subprocess.run([changie, "merge"], cwd=target, check=True) + if (target / "CHANGELOG.md").read_bytes() != (root / "CHANGELOG.md").read_bytes(): + raise ValueError("CHANGELOG.md is generated; run changie merge") + if project_version(target) != project_version(root): + raise ValueError("gradle.properties must match the latest Changie version") + if fragments: + subprocess.run([changie, "batch", "patch", "--dry-run", "--allow-no-changes=false"], + cwd=target, check=True, stdout=subprocess.DEVNULL) + if base: + changes = subprocess.check_output( + ["git", "diff", "--name-status", base + "...HEAD"], cwd=root, text=True + ).splitlines() + workflow_only = changes and all( + line.startswith("M\t.github/workflows/") and line.endswith((".yml", ".yaml")) + for line in changes + ) + if dependabot and workflow_only: + print("changelog-check: validated automated workflow-only update; fragment not required") + return + added = [line.split("\t")[-1] for line in changes if line.startswith(("A\t", "M\t"))] + if not any(name.startswith(".changes/unreleased/") and name.endswith(".yaml") for name in added): + tag = "v" + project_version(root) + if ".changes/" + tag + ".md" not in added or "gradle.properties" not in added or fragments: + raise ValueError("add a Changie fragment, or batch all fragments in a release-prep PR") + release_notes(root, tag) + print("changelog-check: generated changelog, fragments, and version agree") + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--root", type=pathlib.Path, default=pathlib.Path(__file__).resolve().parents[1]) + commands = parser.add_subparsers(dest="command", required=True) + notes = commands.add_parser("notes") + notes.add_argument("tag") + changelog = commands.add_parser("changelog-check") + changelog.add_argument("--base") + changelog.add_argument("--dependabot", action="store_true") + args = parser.parse_args() + try: + if args.command == "notes": + print(release_notes(args.root, args.tag), end="") + elif args.command == "changelog-check": + changelog_check(args.root, args.base, args.dependabot) + except (ValueError, OSError, subprocess.CalledProcessError) as error: + print("HOLD: " + str(error), file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/tests/test_release.py b/scripts/tests/test_release.py new file mode 100644 index 000000000..d9ff34288 --- /dev/null +++ b/scripts/tests/test_release.py @@ -0,0 +1,169 @@ +"""Local contract tests for release preparation; no network or credentials required.""" + +import pathlib +import os +import shutil +import subprocess +import sys +import tempfile +import unittest + + +SCRIPT = pathlib.Path(__file__).resolve().parents[1] / "release.py" + + +class ReleaseNotesTest(unittest.TestCase): + def setUp(self): + self.temporary = tempfile.TemporaryDirectory() + self.addCleanup(self.temporary.cleanup) + self.root = pathlib.Path(self.temporary.name) + (self.root / ".changes").mkdir() + self.notes = "## [1.2.3] - 2026-01-02\n\n### Fixed\n\n- Keep this release only.\n" + (self.root / ".changes/v1.2.3.md").write_text(self.notes) + (self.root / "CHANGELOG.md").write_text( + "# Changelog\n\n" + self.notes + "\n## [1.2.2] - 2026-01-01\n\n- Older.\n" + ) + (self.root / "gradle.properties").write_text("version=1.2.3\ngroup=com.backblaze.b2\n") + + def run_notes(self, tag="v1.2.3"): + return subprocess.run( + [sys.executable, str(SCRIPT), "--root", str(self.root), "notes", tag], + capture_output=True, text=True, + ) + + def test_extracts_exact_release_section(self): + result = self.run_notes() + self.assertEqual(0, result.returncode, result.stderr) + self.assertEqual(self.notes, result.stdout) + self.assertNotIn("Older", result.stdout) + + def test_rejects_tag_version_mismatch(self): + result = self.run_notes("v1.2.4") + self.assertNotEqual(0, result.returncode) + self.assertIn("gradle.properties", result.stderr) + + def test_rejects_missing_notes(self): + (self.root / ".changes/v1.2.3.md").unlink() + result = self.run_notes() + self.assertNotEqual(0, result.returncode) + self.assertIn("release notes", result.stderr) + + def test_rejects_edited_generated_changelog(self): + (self.root / "CHANGELOG.md").write_text("# Changelog\n\n" + self.notes.replace("Keep", "Changed")) + result = self.run_notes() + self.assertNotEqual(0, result.returncode) + self.assertIn("disagree", result.stderr) + + def test_rejects_path_as_tag(self): + result = self.run_notes("../v1.2.3") + self.assertNotEqual(0, result.returncode) + self.assertIn("version tag", result.stderr) + + def test_rejects_duplicate_version_property(self): + (self.root / "gradle.properties").write_text("version=1.2.3\nversion=1.2.4\n") + result = self.run_notes() + self.assertNotEqual(0, result.returncode) + self.assertIn("exactly one", result.stderr) + + +class ChangelogTest(unittest.TestCase): + def setUp(self): + self.temporary = tempfile.TemporaryDirectory() + self.addCleanup(self.temporary.cleanup) + self.root = pathlib.Path(self.temporary.name) + repository = SCRIPT.parents[1] + for name in (".changie.yaml", "gradle.properties", "CHANGELOG.md"): + shutil.copy(repository / name, self.root) + shutil.copytree(repository / ".changes", self.root / ".changes") + (self.root / ".changes/unreleased/contract-test.yaml").write_text( + 'kind: Fixed\nbody: Exercise a complete release batch.\ntime: 2026-01-01T00:00:00Z\n' + ) + self.changie = os.environ.get("CHANGIE", "changie") + + def run_check(self, *arguments): + return subprocess.run( + [sys.executable, str(SCRIPT), "--root", str(self.root), "changelog-check", *arguments], + capture_output=True, text=True, + ) + + def test_current_generated_changelog_matches(self): + result = self.run_check() + self.assertEqual(0, result.returncode, result.stderr) + + def make_pull_request(self, path): + workflow = self.root / ".github/workflows/dependency.yml" + workflow.parent.mkdir(parents=True) + workflow.write_text("name: dependency\n") + for args in (("init", "-q"), ("config", "user.name", "Release Fixture"), + ("config", "user.email", "fixture@example.invalid"), ("add", "."), + ("-c", "commit.gpgSign=false", "commit", "-qm", "Base fixture")): + subprocess.run(["git", *args], cwd=self.root, check=True, capture_output=True) + base = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=self.root, text=True).strip() + changed = self.root / path + changed.write_text("updated fixture\n") + subprocess.run(["git", "add", "."], cwd=self.root, check=True, capture_output=True) + subprocess.run(["git", "-c", "commit.gpgSign=false", "commit", "-qm", "Update fixture"], + cwd=self.root, check=True, capture_output=True) + return base + + def test_dependabot_workflow_pin_update_needs_no_fragment(self): + base = self.make_pull_request(".github/workflows/dependency.yml") + result = self.run_check("--base", base, "--dependabot") + self.assertEqual(0, result.returncode, result.stderr) + + def test_human_workflow_update_still_requires_fragment(self): + base = self.make_pull_request(".github/workflows/dependency.yml") + result = self.run_check("--base", base) + self.assertNotEqual(0, result.returncode) + self.assertIn("fragment", result.stderr) + + def test_dependabot_source_change_still_requires_fragment(self): + base = self.make_pull_request("Source.java") + result = self.run_check("--base", base, "--dependabot") + self.assertNotEqual(0, result.returncode) + self.assertIn("fragment", result.stderr) + + def test_hand_edited_changelog_is_rejected_without_modifying_it(self): + path = self.root / "CHANGELOG.md" + edited = path.read_text() + "\nHand edited.\n" + path.write_text(edited) + result = self.run_check() + self.assertNotEqual(0, result.returncode) + self.assertIn("generated", result.stderr) + self.assertEqual(edited, path.read_text()) + + def test_batch_and_merge_update_gradle_version_and_release_notes(self): + current = next(line[8:] for line in (self.root / "gradle.properties").read_text().splitlines() + if line.startswith("version=")) + major, minor, patch = current.split("-")[0].split(".") + version = major + "." + minor + "." + str(int(patch) + 1) + for arguments in (("batch", "v" + version, "--allow-no-changes=false"), ("merge",)): + subprocess.run([self.changie, *arguments], cwd=self.root, check=True, capture_output=True) + self.assertIn("version=" + version + "\n", (self.root / "gradle.properties").read_text()) + self.assertTrue((self.root / (".changes/v" + version + ".md")).is_file()) + result = self.run_check() + self.assertEqual(0, result.returncode, result.stderr) + + +class ReleaseInstructionsTest(unittest.TestCase): + def test_tag_commands_work_with_only_tag_exported(self): + guide = (SCRIPT.parents[1] / "RELEASE.md").read_text() + block = guide.split("## Tag and deploy", 1)[1].split("```bash", 1)[1].split("```", 1)[0] + block = block.replace("", "123").replace("", "fixture-key") + with tempfile.TemporaryDirectory() as temporary: + root = pathlib.Path(temporary) + git = root / "git" + git.write_text("#!/bin/sh\nif [ \"$1\" = show ]; then printf 'version=1.2.3\\n'; fi\n") + git.chmod(0o755) + gh = root / "gh" + gh.write_text("#!/bin/sh\nprintf '0123456789012345678901234567890123456789\\n'\n") + gh.chmod(0o755) + environment = dict(os.environ, PATH=str(root) + os.pathsep + os.environ["PATH"], TAG="v1.2.3") + environment.pop("VERSION", None) + result = subprocess.run(["bash", "-euo", "pipefail", "-c", block], env=environment, + capture_output=True, text=True) + self.assertEqual(0, result.returncode, result.stdout + result.stderr) + + +if __name__ == "__main__": + unittest.main()