diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e0ed498..1a4c123 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,9 +2,9 @@ name: CI on: push: - branches: [master] + branches: [master, develop] pull_request: - branches: [master] + branches: [master, develop] jobs: test: diff --git a/CHANGELOG.md b/CHANGELOG.md index c2e0097..a659d18 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -## [Unreleased] — towards 1.0.0 +## [1.0.0] - 2026-11-10 — EditorJS 2.31 parity ### Lossless round-trip with current EditorJS (2.31) * **Block ids and tunes are preserved.** `id` and `tunes` are read into the new `BlockDocument.metadata` (`BlockMetadata`) and written back on serialize. `EditorController.blockIds` now holds the EditorJS ids (kept from the document, generated in EditorJS's own 10-character format for new blocks) and the new `EditorController.blockTunes` exposes each block's tunes. Both follow their block through update, move and undo/redo. @@ -36,6 +36,15 @@ * **Every label, tooltip, hint and message can be translated or reworded.** New `EditorConfig.strings` takes an `EditorStrings`, which holds all 104 texts the editor and the viewer show on their own, with English defaults; override only the ones you need. Texts that include a value (a heading level, a file size) are functions. Until now all text was hard-coded in English. * **Spanish and French are bundled.** `EditorTranslations.es` and `EditorTranslations.fr` are complete translations; `EditorTranslations.forLanguage(code)` picks one from a language code or locale tag and falls back to English. The README explains how to add another language, in an app or in the package. +### Requirements and dependencies +* **The minimum is now declared as Flutter 3.27 (Dart 3.6).** Earlier releases declared Flutter 3.10 but already used `Color.withValues`, which arrived in 3.27, so on an older Flutter the package installed and then failed to compile. Nothing changes for apps that could build it. +* **`html` is capped below 0.15.7.** `html` 0.15.7 removed a function that `flutter_html` 3.0.0 calls, so an app that resolved to it failed to compile. The package now depends on `html: ">=0.15.5 <0.15.7"` until `flutter_html` supports the newer version. An app that needs `html` 0.15.7 or later for another package will get a version conflict. +* `flutter_html`: `^3.0.0-beta.2` → `^3.0.0`. The pre-release versions are no longer accepted. + +### CI and workflow +* CI also runs on pushes and pull requests to `develop`. +* `CLAUDE.md` and the README describe the git flow the project uses: work branches from `develop`, releases from `release/` into `master`. + ### Parser hardening * A field of the wrong type no longer throws out of `EditorJSView` / `EditorController.fromJson`. Every built-in mapper now reads through tolerant helpers; previously `linkTool.meta: []`, a non-string list `style`, a non-string paragraph `text` and a non-integer document `time` each raised a `TypeError`. * `time` accepts integers, doubles and numeric strings; header `level` accepts doubles. diff --git a/CLAUDE.md b/CLAUDE.md index d12e2f4..ffe3ff6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,7 +36,7 @@ fvm flutter test test/editorjs_flutter_test.dart ## Architecture -The package follows **Clean Architecture** with three strict layers. Dependencies only flow inward (presentation → data → domain). No new external dependencies — only `flutter_html`, `image_picker`, `url_launcher`, and Flutter's built-in `ChangeNotifier`. +The package follows **Clean Architecture** with three strict layers. Dependencies only flow inward (presentation → data → domain). No new external dependencies — only `flutter_html`, `image_picker`, `url_launcher`, and Flutter's built-in `ChangeNotifier`. (`html` is listed in `pubspec.yaml` only to cap the version `flutter_html` resolves to; the package does not import it.) ``` lib/src/ @@ -176,27 +176,33 @@ When building new features, always work bottom-up: ## Git Workflow -**This repo has branch protection. Direct commits to `master` are not allowed.** +**This repo follows git flow. Direct commits to `master` or `develop` are not allowed.** + +- `master` holds released versions only. +- `develop` is the integration branch: every feature, fix and chore is merged here first. +- `release/` is cut from `develop` when a version is ready, and is merged into `master`. ### Before starting any coding task -1. Ensure `master` is up to date and create a new branch: +1. Ensure `develop` is up to date and create a new branch from it: ```bash - git checkout master + git checkout develop git pull git checkout -b / ``` + Always branch from `develop`, never from another work branch: one branch and one PR per task. 2. Use these branch name prefixes: - `feat/` — new feature or block type - `fix/` — bug fix - `refactor/` — internal restructuring with no behaviour change - `chore/` — dependency bumps, tooling, docs + - `release/` — release branch, named after the version (`release/1.0.0`) ### Before finishing any coding task 1. Run `fvm flutter analyze` — must report **no issues** before marking work done. 2. Generate a `PR_DESCRIPTION.md` file at the repo root (see template below). -3. All changes go to `master` via Pull Request only — never push directly. +3. All changes go to `develop` via Pull Request only — never push directly. Only a release branch is merged into `master`. 4. Delete `PR_DESCRIPTION.md` after the PR is merged. ### PR_DESCRIPTION.md template @@ -227,15 +233,23 @@ When building new features, always work bottom-up: - [ ] Demo app tested manually on at least one platform ``` +### Releasing + +1. Cut `release/` from `develop`. +2. On that branch, set the version in `pubspec.yaml`, turn the `[Unreleased]` section of `CHANGELOG.md` into the entry for the version, and update the version references in `README.md` and in this file. Apart from that, only fixes found while preparing the release go on this branch. +3. Open a PR from the release branch into `master`. CI must pass. +4. After the merge, merge `master` back into `develop`. + --- ## Versioning -Current version: `0.5.0` (in `pubspec.yaml`). +Current version: `1.0.0` (in `pubspec.yaml`). -When making changes, always update `CHANGELOG.md` with a new entry at the top following the existing format: -- Bump the patch version for bug fixes -- Bump the minor version for new features or breaking API changes +The package follows semantic versioning. When making changes, add a note to the `## [Unreleased]` section at the top of `CHANGELOG.md` (create it if it is missing), following the existing format. Do not change the version on a work branch; it is set on the release branch: +- Patch version for bug fixes +- Minor version for new features +- Major version for breaking changes to the public API - Keep `pubspec.yaml` version in sync with `CHANGELOG.md` ## Known Issues / Backlog diff --git a/README.md b/README.md index 643566c..7db4c25 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,12 @@ A viewer and editor compatible with the [EditorJS](https://editorjs.io/) JSON sc [![CI](https://github.com/DEV1-Softworks/editorjs-flutter/actions/workflows/ci.yml/badge.svg)](https://github.com/DEV1-Softworks/editorjs-flutter/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/DEV1-Softworks/editorjs-flutter/branch/master/graph/badge.svg)](https://codecov.io/gh/DEV1-Softworks/editorjs-flutter) -# DISCLAIMER -This package is in active development (pre-1.0). The public API is stable and the Clean Architecture foundation is solid, but some editor features are still being refined. Suitable for early production use with the understanding that minor API changes may occur in future minor versions. +# Status +Version 1.0 is the first stable release. It reads and writes the JSON of EditorJS 2.31, including the `@editorjs/list` 2.x format, and saving a document keeps everything that was loaded: block ids, tunes, and blocks from plugins this package does not know. -Requires **Flutter 3.10+** and **Dart 3.0+**. +From 1.0 on the package follows [semantic versioning](https://dart.dev/tools/pub/versioning): the public API changes incompatibly only in a new major version. + +Requires **Flutter 3.27+** (Dart 3.6+). # Installation @@ -17,11 +19,13 @@ Add the following to your `pubspec.yaml` dependencies: ```yaml dependencies: - editorjs_flutter: ^0.5.0-beta.1 + editorjs_flutter: ^1.0.0 ``` Then run `flutter pub get`. +The package limits `html` to versions below 0.15.7, because `flutter_html` 3.0.0 does not compile with 0.15.7. If `pub get` reports a conflict on `html`, another of your dependencies requires the newer version. + # Usage ## Viewer @@ -347,7 +351,7 @@ AI tools (including Claude Code) are permitted to assist with contributions to t The following rules apply when using Claude Code (`claude` CLI) on this repository: -1. **Branch before coding.** Claude Code must create and checkout a new branch from `master` before writing any code. Branch names must follow the `feat/`, `fix/`, `refactor/`, or `chore/` prefix convention. Direct commits to `master` are never allowed. +1. **Branch before coding.** Claude Code must create and checkout a new branch from `develop` before writing any code, one branch per task and never on top of another work branch. Branch names must follow the `feat/`, `fix/`, `refactor/`, or `chore/` prefix convention (`release/` for a release). Direct commits to `master` or `develop` are never allowed. `CLAUDE.md` describes the full workflow. 2. **Generate a PR description before finishing.** At the end of every coding session, Claude Code must produce a `PR_DESCRIPTION.md` file at the repo root summarising the changes (title, type of change, summary, breaking changes, migration notes, test plan checklist). This file is ephemeral — delete it after the PR is merged. 3. **No autonomous commits.** Claude Code must never commit or push changes without explicit human instruction. Every commit requires a human to review the diff and approve it first. 4. **No force pushes.** Claude Code must never run `git push --force` or any destructive git operation (`reset --hard`, `branch -D`, etc.) without explicit human confirmation. diff --git a/example/pubspec.lock b/example/pubspec.lock index 5540466..b62d24d 100644 --- a/example/pubspec.lock +++ b/example/pubspec.lock @@ -47,7 +47,7 @@ packages: path: ".." relative: true source: path - version: "0.5.0" + version: "1.0.0" file_selector_linux: dependency: transitive description: diff --git a/pubspec.lock b/pubspec.lock index c9d0db1..49a7caa 100644 --- a/pubspec.lock +++ b/pubspec.lock @@ -145,7 +145,7 @@ packages: source: sdk version: "0.0.0" html: - dependency: transitive + dependency: "direct main" description: name: html sha256: "6d1264f2dffa1b1101c25a91dff0dc2daee4c18e87cd8538729773c073dbf602" diff --git a/pubspec.yaml b/pubspec.yaml index fe31eb9..b3f5c77 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,6 +1,6 @@ name: editorjs_flutter description: "Flutter viewer and editor widgets for the EditorJS JSON schema. Supports 14 built-in block types with a Clean Architecture extension point for custom blocks." -version: 0.5.0-beta.1 +version: 1.0.0 homepage: https://labs.dev1.mx/editorjs-flutter repository: https://github.com/DEV1-Softworks/editorjs-flutter issue_tracker: https://github.com/DEV1-Softworks/editorjs-flutter/issues @@ -11,13 +11,17 @@ topics: - content environment: - sdk: ">=3.0.0 <4.0.0" - flutter: ">=3.10.0" + sdk: ">=3.6.0 <4.0.0" + flutter: ">=3.27.0" dependencies: flutter: sdk: flutter - flutter_html: ^3.0.0-beta.2 + flutter_html: ^3.0.0 + # Not used directly. flutter_html 3.0.0 calls a function that html 0.15.7 + # removed, so an app that resolves to 0.15.7 fails to compile. Remove this + # cap once flutter_html supports it. + html: ">=0.15.5 <0.15.7" image_picker: ^1.0.0 url_launcher: ^6.2.0