Merge pull request #222 from javaevolved/brunoborges-prevent-pattern-pr-conflicts

Prevent conflicts between pattern pull requests

Author: brunoborges

.github/copilot-instructions.md

@@ -51,7 +51,7 @@ Content files are YAML (preferred) or JSON under `content/{category}/{slug}.yaml
 | `related` | Exactly **3** entries as `category/slug` paths (cross-category OK) |
 | `tags` | Non-empty list of slugs registered in `html-generators/tags.properties` |
 | `docs` | At least **1** entry with `title` and `href` |
-| `prev` / `next` | `category/slug` path or `null` for first/last in the global chain |
+| `navigationOrder` | Non-negative integer; global order is `(navigationOrder, category/slug)` |
 | `jdkVersion` | The JDK version where the feature became **final** (not preview) |
 | `difficulty` | One of: `beginner`, `intermediate`, `advanced` |
 | `support.state` | One of: `available`, `preview`, `experimental` |
@@ -60,24 +60,24 @@ Content files are YAML (preferred) or JSON under `content/{category}/{slug}.yaml
 
 1. Create `content/{category}/new-slug.yaml` with all required fields (use `content/template.json` as reference) and generate its `id` with `uuidgen`.
 2. Add a non-empty `tags` list. Every tag slug must already exist in `html-generators/tags.properties`; add new `slug=Display Name` entries there in the same change.
-3. Update `prev`/`next` in the adjacent patterns to maintain the navigation chain.
+3. Set `navigationOrder` to place the pattern in the global sequence. Values are spaced by 1000; duplicate values are allowed and tie-break by pattern key.
 4. Create `proof/{category}/{PascalCaseSlug}.java` — JBang script wrapping the modern code.
 5. Create a partial translation at `translations/content/{locale}/{category}/{slug}.yaml` for every non-English locale registered in `html-generators/locales.properties`.
 6. Run `jbang html-generators/generate.java` and verify all localized output builds. Generated site files are ignored and must not be committed. The generator rejects missing, malformed, or duplicate UUIDs as well as missing, empty, malformed, and unregistered tags.
-7. Run `jbang html-generators/generatesocialqueue.java` without `--reshuffle`. Commit the appended `social/queue.txt` entry and `social/tweets.yaml` draft; do not change `social/state.yaml`.
-8. Run `jbang html-generators/validatepatternchanges.java --file content/{category}/{slug}.yaml` and the new proof. The validator enforces translations, proof, navigation, related targets, and social artifacts.
+7. Run `jbang html-generators/generatesocialqueue.java --file content/{category}/{slug}.yaml`. Commit the generated `social/tweets/{category}/{slug}.yaml`; do not change `social/queue.txt` or `social/state.yaml`.
+8. Run `jbang html-generators/validatepatternchanges.java --file content/{category}/{slug}.yaml` and the new proof. The validator enforces translations, proof, navigation order, related targets, and the tweet draft.
 
 ### Removing or reordering a pattern
 
-Update `prev`/`next` in adjacent patterns. Search for the slug in other patterns' `related` arrays and replace with an appropriate alternative.
+Update `navigationOrder` when reordering. Search for a removed slug in other patterns' `related` arrays and replace it with an appropriate alternative.
 
 ## Internationalization
 
 Full spec: `specs/i18n/i18n-spec.md`. Key rules:
 
 - All locales (including English) go through the same build pipeline.
 - UI strings: `translations/strings/{locale}.yaml`. Missing keys fall back to English with a build-time warning.
-- Content translations contain **only** translatable fields: `title`, `summary`, `explanation`, `oldApproach`, `modernApproach`, `whyModernWins`, `support.description`. Code, slugs, navigation, and docs are never translated.
+- Content translations contain **only** translatable fields: `title`, `summary`, `explanation`, `oldApproach`, `modernApproach`, `whyModernWins`, `support.description`. Code, slugs, navigation order, and docs are never translated.
 - `oldCode`/`modernCode` in translation files are **always overwritten** with English values at build time to prevent hallucinated code.
 - Locale registry: `html-generators/locales.properties` (format: `locale=Display Name`).
 - When adding a new UI string key, add it to `en.yaml` first, then to all other locale files. The generator warns on missing keys but doesn't fail.

.github/workflows/content-validation.yml

@@ -6,11 +6,12 @@ on:
       - '.github/workflows/content-validation.yml'
       - 'content/**'
       - 'proof/**'
-      - 'social/queue.txt'
-      - 'social/tweets.yaml'
+      - 'social/tweets/**'
       - 'translations/**'
       - 'templates/**'
       - 'html-generators/generate.java'
+      - 'html-generators/generatesocialqueue.java'
+      - 'html-generators/socialpost.java'
       - 'html-generators/validatepatternchanges.java'
       - 'html-generators/tags.properties'
       - 'html-generators/categories.properties'
@@ -42,5 +43,10 @@ jobs:
           --base "${{ github.event.pull_request.base.sha }}"
           --head "${{ github.event.pull_request.head.sha }}"
 
+      - name: Validate social posting flow
+        run: |
+          jbang html-generators/generatesocialqueue.java
+          jbang html-generators/socialpost.java --dry-run
+
       - name: Validate content and generate site
         run: jbang html-generators/generate.java

.github/workflows/social-post.yml

@@ -25,6 +25,9 @@ jobs:
 
       - uses: jbangdev/setup-jbang@main
 
+      - name: Reconcile pending queue
+        run: jbang html-generators/generatesocialqueue.java
+
       - name: Post to Twitter
         env:
           TWITTER_CONSUMER_KEY: ${{ secrets.TWITTER_APP_CONSUMER_KEY }}
@@ -37,7 +40,7 @@ jobs:
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add social/state.yaml social/queue.txt social/tweets.yaml
+          git add social/state.yaml social/queue.txt
           git diff --cached --quiet && exit 0
           git commit -m "chore: update social post state [skip ci]"
           git pull --rebase

CONTRIBUTING.md

@@ -7,9 +7,10 @@ Contributions are welcome! Content is managed as YAML files — never edit gener
 1. Fork the repo
 2. Create a new YAML file in the appropriate `content/<category>/` folder (e.g. `content/language/my-feature.yaml`)
 3. Copy [`content/template.json`](content/template.json) as a starting point for all required fields (see the [snippet schema](.github/copilot-instructions.md) for details)
-4. Update the `prev`/`next` fields in adjacent pattern files to maintain navigation
-5. Run `jbang html-generators/generate.java` to verify your changes build correctly
-6. Open a pull request
+4. Set `navigationOrder` to place the pattern in the global sequence. Values are spaced by 1000; duplicate values are allowed and are ordered by pattern key.
+5. Generate its tweet draft with `jbang html-generators/generatesocialqueue.java --file content/<category>/<slug>.yaml`
+6. Run `jbang html-generators/generate.java` to verify your changes build correctly
+7. Open a pull request
 
 Please ensure JDK version labels only reference the version where a feature became **final** (non-preview).
 
@@ -51,6 +52,6 @@ support:
   description: "Ampliamente disponible desde JDK 10 (marzo 2018)"
 ```
 
-Do **not** include `id`, `slug`, `category`, `difficulty`, `jdkVersion`, `oldCode`, `modernCode`, `prev`, `next`, `related`, or `docs` — these are always taken from the English source.
+Do **not** include `id`, `slug`, `category`, `navigationOrder`, `difficulty`, `jdkVersion`, `oldCode`, `modernCode`, `related`, or `docs` — these are always taken from the English source.
 
 **Important:** If your text contains colons (`:`), ensure the value is properly quoted in YAML to avoid parse errors. Always validate with `jbang html-generators/generate.java` before submitting.

content/collections/collection-bulk-operations.yaml

@@ -3,6 +3,7 @@ id: 6a0d1711-a495-490e-a830-95087e092b69
 slug: "collection-bulk-operations"
 title: "Collection bulk operations instead of mutation loops"
 category: "collections"
+navigationOrder: 39000
 difficulty: "beginner"
 jdkVersion: "8"
 oldLabel: "Iterator mutation loop"
@@ -32,8 +33,6 @@ whyModernWins:
 support:
   state: "available"
   description: "Available since JDK 8 (March 2014)"
-prev: "collections/stack-to-deque"
-next: "collections/comparator-factories"
 related:
 - "collections/reverse-list-iteration"
 - "collections/copying-collections-immutably"

content/collections/collectors-teeing.yaml

@@ -3,6 +3,7 @@ id: a04b95a4-d198-4e96-ac9b-870ec57fdeb9
 slug: "collectors-teeing"
 title: "Collectors.teeing()"
 category: "collections"
+navigationOrder: 32000
 difficulty: "intermediate"
 jdkVersion: "12"
 oldLabel: "Java 8"
@@ -40,8 +41,6 @@ whyModernWins:
 support:
   state: "available"
   description: "Widely available since JDK 12 (March 2019)"
-prev: "collections/sequenced-collections"
-next: "collections/stream-toarray-typed"
 related:
 - "collections/copying-collections-immutably"
 - "collections/unmodifiable-collectors"

content/collections/comparator-factories.yaml

@@ -3,6 +3,7 @@ id: a1ac8e52-14cf-49be-a22a-be72de7caa4e
 slug: "comparator-factories"
 title: "Comparator factories and fluent ordering"
 category: "collections"
+navigationOrder: 40000
 difficulty: "beginner"
 jdkVersion: "8"
 oldLabel: "Anonymous comparator"
@@ -35,8 +36,6 @@ whyModernWins:
 support:
   state: "available"
   description: "Available since JDK 8 (March 2014)"
-prev: "collections/collection-bulk-operations"
-next: null
 related:
 - "collections/collection-bulk-operations"
 - "collections/reverse-list-iteration"

content/collections/copying-collections-immutably.yaml

@@ -3,6 +3,7 @@ id: 34332f56-c837-4ddb-b00f-aca32bb68bef
 slug: "copying-collections-immutably"
 title: "Copying collections immutably"
 category: "collections"
+navigationOrder: 29000
 difficulty: "beginner"
 jdkVersion: "10"
 oldLabel: "Java 8"
@@ -34,8 +35,6 @@ whyModernWins:
 support:
   state: "available"
   description: "Widely available since JDK 10 (March 2018)"
-prev: "collections/immutable-set-creation"
-next: "collections/map-entry-factory"
 related:
 - "collections/immutable-set-creation"
 - "collections/map-entry-factory"

content/collections/immutable-list-creation.yaml

@@ -3,6 +3,7 @@ id: 1fa578db-e750-4adb-a88e-bdd2bbda14c4
 slug: "immutable-list-creation"
 title: "Immutable list creation"
 category: "collections"
+navigationOrder: 26000
 difficulty: "beginner"
 jdkVersion: "9"
 oldLabel: "Java 8"
@@ -36,8 +37,6 @@ whyModernWins:
 support:
   state: "available"
   description: "Widely available since JDK 9 (Sept 2017)"
-prev: "language/exhaustive-switch"
-next: "collections/immutable-map-creation"
 related:
 - "collections/immutable-map-creation"
 - "collections/immutable-set-creation"

content/collections/immutable-map-creation.yaml

@@ -3,6 +3,7 @@ id: d118236d-2cfb-4c8a-81b6-f870fc10c25d
 slug: "immutable-map-creation"
 title: "Immutable map creation"
 category: "collections"
+navigationOrder: 27000
 difficulty: "beginner"
 jdkVersion: "9"
 oldLabel: "Java 8"
@@ -34,8 +35,6 @@ whyModernWins:
 support:
   state: "available"
   description: "Widely available since JDK 9 (Sept 2017)"
-prev: "collections/immutable-list-creation"
-next: "collections/immutable-set-creation"
 related:
 - "collections/copying-collections-immutably"
 - "collections/sequenced-collections"