From 47a057abb5f156ca98107c64e423d8c781bb738d Mon Sep 17 00:00:00 2001 From: Rick van Dijk Date: Wed, 23 Sep 2026 10:45:49 -0700 Subject: [PATCH] Move docs and CI to main-only branching with a version bump per PR Prepares octo_image for the main-only branching model already used by flutter_cache_manager and flutter_cached_network_image (FPL-29). main is not yet the default branch or protected; that happens as a follow-up settings change once this PR is merged and CI is green against main. - build.yaml: trigger on push/pull_request against main instead of develop - AGENTS.md, CONTRIBUTING.md: branch from and target main, add the per-PR version bump and CHANGELOG entry step (skipped for docs-only and CI-only changes, as this PR is), update the Releases section to tagging-only with no release-prep PR - PULL_REQUEST_TEMPLATE.md: rebase item now says main, add the version-bump checklist item - README.md: pin the demo GIF to the v2.1.0 tag instead of develop, so the link survives the branch move Co-Authored-By: Claude Sonnet 5 --- .github/PULL_REQUEST_TEMPLATE.md | 3 +- .github/workflows/build.yaml | 6 ++-- AGENTS.md | 54 +++++++++++++++++++------------- CONTRIBUTING.md | 9 ++++-- README.md | 2 +- 5 files changed, 44 insertions(+), 30 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index b001d7c..e6c754a 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -21,4 +21,5 @@ - [ ] All projects build - [ ] Follows style guide lines - [ ] Relevant documentation was updated -- [ ] Rebased onto current develop +- [ ] Rebased onto current main +- [ ] Version bumped in pubspec.yaml and dated CHANGELOG.md entry added (skip for docs-only and CI-only changes) diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index c76c1eb..66dec24 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -1,16 +1,16 @@ name: build # Controls when the action will run. Triggers the workflow on push or pull request -# events but only for the develop branch +# events but only for the main branch on: workflow_dispatch: push: tags: - "v[0-9]+.[0-9]+.[0-9]+*" - branches: [develop, main] + branches: [main] pull_request: - branches: [develop] + branches: [main] # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: diff --git a/AGENTS.md b/AGENTS.md index 820669b..0bd36c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,11 +108,11 @@ Baseflow's open-source forking workflow: git remote add upstream git@github.com:Baseflow/octo_image.git ``` -4. Branch from latest `develop`: +4. Branch from latest `main`: ```bash git fetch upstream -git checkout upstream/develop -b +git checkout upstream/main -b ``` Expected remotes after setup: @@ -162,24 +162,26 @@ Not covered directly: `FadeWidget`, `ImageHandler`, gapless playback ## Pull request workflow -**`develop` is the branch of record.** Fork from `upstream/develop`, open every -PR against `develop`, and rebase onto `develop` before submitting. `main` and -`master` are leftovers from an earlier branch layout: they are not maintained, -and must not be branched from or targeted. A move to a main-only model, matching -Baseflow's other cache packages, is planned; until it lands, `develop` is the -one to use. +**`main` is the branch of record.** Fork from `upstream/main`, open every PR +against `main`, and rebase onto `main` before submitting. `develop` and +`master` are gone, and a ruleset blocks re-creating `develop`. This repo uses the **forking workflow**: contributors work on their own fork and open PRs to the main repository. Maintainers review and merge; do not push directly to `Baseflow/octo_image`. -1. Apply changes on a branch based on `upstream/develop`. -2. Verify locally: +1. Apply changes on a branch based on `upstream/main`. +2. Bump `version:` in `pubspec.yaml` following semver, and add a matching + `## [x.y.z] - YYYY-MM-DD` `CHANGELOG.md` entry describing the change + (format: see [Releases](#releases)). Date it with the day you open the PR; + a maintainer will correct it if it slips before tagging. Docs-only and + CI-only PRs don't bump. +3. Verify locally: - `dart format .` - `flutter analyze` - `flutter test` -3. Push to your fork: `git push origin ` -4. Open a PR against `Baseflow/octo_image` and fill out the full +4. Push to your fork: `git push origin ` +5. Open a PR against `main` on `Baseflow/octo_image` and fill out the full [PR template](.github/PULL_REQUEST_TEMPLATE.md). Keep public API changes additive and non-breaking where possible; breaking @@ -192,7 +194,7 @@ actual section headings verbatim — `What kind of change does this PR introduce?`, `What is the current behavior?`, `What is the new behavior (if this is a feature change)?`, `Does this PR introduce a breaking change?`, `Recommendations for testing`, `Links to relevant issues/docs`, and the -`Checklist before submitting` with its exact four items. Do not substitute a +`Checklist before submitting` with its exact five items. Do not substitute a different structure even for small or maintainer-authored PRs. Fill out the [PR template](.github/PULL_REQUEST_TEMPLATE.md), but keep each @@ -213,24 +215,32 @@ The repository's own template checklist: - [ ] All projects build - [ ] Follows style guide lines - [ ] Relevant documentation was updated -- [ ] Rebased onto current `develop` +- [ ] Rebased onto current `main` +- [ ] Version bumped in `pubspec.yaml` and dated `CHANGELOG.md` entry added + (skip for docs-only and CI-only changes) ## Releases One package, one tag scheme. Only maintainers cut releases. -1. Open a release PR against `develop`: add an entry under a new dated - `## [x.y.z] - YYYY-MM-DD` heading in `CHANGELOG.md`, in the style already in - use (see below), and bump `version:` in `pubspec.yaml`. +1. Confirm `main` is ready. Under the version-per-PR rule, every merged PR + already bumped `version:` in `pubspec.yaml` and added its `CHANGELOG.md` + entry (see [Pull request workflow](#pull-request-workflow)) — there is no + separate release-prep PR to land first. 2. Verify: `dart format --set-exit-if-changed .`, `flutter analyze`, `flutter test`, and `dart pub publish --dry-run`. -3. Merge once CI is green, then tag the resulting commit `vX.Y.Z`. -4. Push the tag. **Pushing the tag is what publishes**: `build.yaml` runs - `dart pub publish` via pub.dev OIDC trusted publishing, gated on - `github.ref_type == 'tag'`. Never run `dart pub publish` by hand, and never - bump a version without a tag to match. +3. Tag the merge commit on `main` `vX.Y.Z`. Push. + +**Pushing the tag is what publishes**: `build.yaml` runs `dart pub publish` +via pub.dev OIDC trusted publishing, gated on `github.ref_type == 'tag'`. It +does not bump versions and does not edit changelogs. Never run +`dart pub publish` by hand, and never bump a version without a tag to match. `CHANGELOG.md` today uses `## [x.y.z] - YYYY-MM-DD` headings with `*` bullets and no `## [Unreleased]` section. Match that format; introducing an `[Unreleased]` section is a separate decision and not something to do as part of an unrelated change. + +Published versions are immutable, so keep branch names out of URLs in +`pubspec.yaml` and in docs: a branch-specific link becomes a permanent dead +link once that branch is gone. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4329d7f..bbcb16e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,10 +24,13 @@ We really appreciate contributions via GitHub pull requests. To contribute, take the following steps: -- Make sure you are up to date with the latest code on `develop`: +- Make sure you are up to date with the latest code on `main`: - `git fetch upstream` - - `git checkout upstream/develop -b ` + - `git checkout upstream/main -b ` - Apply your changes +- Bump the `version:` in `pubspec.yaml` (following semver) and add a matching + `## [x.y.z] - YYYY-MM-DD` entry to `CHANGELOG.md` describing what changed. + Docs-only and CI-only changes don't bump. - Verify your changes and fix potential warnings/errors: - Check formatting: `dart format .` - Run static analysis: `flutter analyze` @@ -37,6 +40,6 @@ We really appreciate contributions via GitHub pull requests. To contribute, take Send us your pull request: -- Go to `https://github.com/Baseflow/octo_image` and click the "Compare & pull request" button. +- Go to `https://github.com/Baseflow/octo_image` and click the "Compare & pull request" button, targeting `main`. Please make sure you solved all warnings and errors reported by the static code analysis and that you fill in the full pull request template. Failing to do so will result in us asking you to fix it. diff --git a/README.md b/README.md index c982127..08e4f7a 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ An image library for showing placeholders, error widgets and transform your imag Recommended using with [CachedNetworkImage](https://pub.dev/packages/cached_network_image) version 2.2.0 or newer. - + ## Getting Started The OctoImage widget needs an [ImageProvider](#imageProviders) to show the image.