docs: update CONTRIBUTING.md and README.md to clarify code generation workflow and emphasize not editing generated files directly. Enhance generate.dart to auto-format generated Dart files, ensuring CI compatibility and reducing diffs

Author: gabbopalma

CONTRIBUTING.md

@@ -17,3 +17,36 @@ interested in making contributions:
 4. If there are any changes that developers should be aware of, please update
    the [changelog](https://github.com/maplibre/flutter-maplibre-gl/blob/master/CHANGELOG.md)
    once your pull request has been merged to the `main` branch.
+
+## Code Generation & Formatting
+
+Some parts of the public API (layer & source property helpers, expression utilities, etc.) are **generated**.
+
+Do not edit generated Dart / Java / Swift files manually. Instead:
+
+1. Make or adjust templates / generator logic under `scripts/` (main entry: `scripts/lib/generate.dart`).
+
+2. Activate Melos and run a clean bootstrap:
+   ```bash
+   dart pub global activate melos && melos clean && melos bootstrap
+   ```
+3. Run the generator:
+   ```bash
+   melos run generate
+   ```
+4. (Optional) Run the workspace formatter (Dart files generated are already batch‑formatted automatically):
+   ```bash
+   melos format-all
+   ```
+5. Review changes:
+   ```bash
+   git diff
+   ```
+6. Stage & commit if everything looks correct.
+
+Notes:
+- The generator itself batch‑formats newly created Dart files using `dart format` so CI should not introduce extra diffs.
+- Running `melos format-all` afterward is still fine (idempotent) and catches accidental manual edits elsewhere.
+- Never hand‑edit generated files: your edits will be overwritten the next time the generator runs.
+
+If you add new style specification fields, extend the mapping logic in `scripts/lib/conversions.dart` and/or templates under `scripts/templates/`.

maplibre_gl/README.md

@@ -319,18 +319,14 @@ but it seems like the expression still works well.
 ## Contributing
 
 Setup [melos](https://melos.invertase.dev/~melos-latest/getting-started) and run
-the
-
-```bash
-melos bootstrap
-```
-
-command in the plugin root directory. Run the example app and familiarize
-yourself with the plugin directory structure.
+the `melos bootstrap` command in the plugin root directory.\
+Run the example app and familiarize yourself with the plugin directory structure.
 
 [Feedback](https://github.com/maplibre/flutter-maplibre-gl/issues), contributing
 pull requests
 and [bug reports](https://github.com/maplibre/flutter-maplibre-gl/issues) are
 very welcome - check
 the [CONTRIBUTING.md](https://github.com/maplibre/flutter-maplibre-gl/blob/main/CONTRIBUTING.md)
 guidelines.
+
+**Generated code**: Some API surface (layer/source property helpers, expression utilities) is produced via a generator under `scripts/`. Do not modify generated files directly—see the Code Generation & Formatting section in `CONTRIBUTING.md` for the workflow (`melos run generate` then `melos format-all`).

scripts/lib/generate.dart

@@ -7,7 +7,8 @@
 // Key goals:
 //  - Keep hand‑written logic small; most surface area is generated.
 //  - Ensure deterministic output (stable ordering helps minimal diffs).
-//  - Apply formatting immediately so CI "format-all" never fails after generation.
+//  - Generated Dart files are batch‑formatted at the end using `dart format`
+//    so that a subsequent CI `melos format-all` step produces no diffs.
 //
 // Notes:
 //  - Do NOT edit the generated files manually; instead adjust templates or
@@ -101,15 +102,33 @@ Future<void> main() async {
     "maplibre_gl_platform_interface/lib/src/source_properties.dart",
   ];
 
+  final generatedDartFiles = <String>[];
   for (final template in templates) {
-    await render(renderContext, template);
+    final path = await render(renderContext, template);
+    if (path.endsWith('.dart')) {
+      generatedDartFiles.add(path);
+    }
+  }
+
+  // Auto-format only the Dart files we just generated so that a subsequent
+  // CI `melos format-all` step does not introduce extra diffs.
+  if (generatedDartFiles.isNotEmpty) {
+    final result = await Process.run(
+      'dart',
+      ['format', ...generatedDartFiles],
+      runInShell: true,
+    );
+    if (result.exitCode != 0) {
+      stderr.writeln('Warning: dart format failed: ${result.stderr}');
+    }
   }
 }
 
 /// Render a single template file.
 /// [path] is the relative workspace path to the output (and indirectly the
 /// template at scripts/templates/$filename.template).
-Future<void> render(
+/// Returns the absolute path of the written file.
+Future<String> render(
   Map<String, List> renderContext,
   String path,
 ) async {
@@ -128,28 +147,8 @@ Future<void> render(
   final outputFile = File('$outputPath/$filename');
 
   final rendered = template.renderString(renderContext);
-
   await outputFile.writeAsString(rendered);
-
-  // For Dart targets, run the official formatter to ensure perfect parity
-  // with `dart format` (used by melos format-all in CI). Doing this instead
-  // of using the dart_style API avoids subtle version / option drift.
-  if (filename.endsWith('.dart')) {
-    try {
-      final result = await Process.run(
-        'dart',
-        ['format', outputFile.path],
-        runInShell: true,
-      );
-      if (result.exitCode != 0) {
-        stderr.writeln(
-          'Warning: dart format failed for ${outputFile.path}: ${result.stderr}',
-        );
-      }
-    } catch (e) {
-      stderr.writeln('Warning: spawning dart format failed for $filename: $e');
-    }
-  }
+  return outputFile.path;
 }
 
 /// Build the (paint/layout) style properties list for a given style.json key.