Release Doc2FAQ v0.5.0 — Source & Review (Java 21–26)

.github/workflows/ci.yml

@@ -2,27 +2,64 @@ name: Verify Doc2FAQ
 
 on:
   push:
+    branches:
+      - main
   pull_request:
 
 permissions:
   contents: read
 
 jobs:
   build-and-test:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    name: Java ${{ matrix.java }} compatibility
+    strategy:
+      fail-fast: false
+      max-parallel: 2
+      matrix:
+        java: ['21', '22', '23', '24', '25', '26']
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-java@v4
+      - uses: actions/checkout@v7
+      - uses: actions/setup-java@v6
         with:
           distribution: temurin
-          java-version: '21'
+          java-version: ${{ matrix.java }}
           cache: maven
       - name: Build and test
-        run: mvn -B -ntp verify
+        run: mvn -B -ntp clean verify
+
+      - name: Smoke test packaged Java app
+        run: bash scripts/smoke-packaged-jar.sh target/doc2faq-0.5.0.jar
 
       - name: Test browser export safety
+        if: matrix.java == '21'
         run: node --test src/test/js/*.test.cjs
 
-      - name: Build static browser demo
-        run: node scripts/build-web-demo.mjs
+      - name: Build Doc2FAQ homepage and static browser demo
+        if: matrix.java == '21'
+        run: |
+          node scripts/build-website.mjs
+          test -f website-dist/index.html
+          test -f website-dist/styles.css
+          test -f website-dist/demo/index.html
+          test -f website-dist/demo/retro.css
+          node scripts/verify-website-build.mjs
+
+  # The main-branch ruleset requires a check named "build-and-test".
+  # Keep that stable status only after every Java matrix job succeeds.
+  required-status:
+    name: build-and-test
+    runs-on: ubuntu-24.04
+    needs: [build-and-test]
+    if: ${{ always() }}
+    steps:
+      - name: Require all Java compatibility jobs to pass
+        env:
+          MATRIX_RESULT: ${{ needs['build-and-test'].result }}
+        run: |
+          if [ "$MATRIX_RESULT" != "success" ]; then
+            echo "Java 21–26 compatibility checks did not all pass: $MATRIX_RESULT"
+            exit 1
+          fi
+          echo "All Java 21–26 compatibility checks passed."

.github/workflows/publish-v0.5.0.yml

@@ -0,0 +1,121 @@
+name: Publish Doc2FAQ v0.5.0
+
+# First run automatically when this workflow lands on main. Manual reruns
+# remain available, but the existing-release check prevents duplicate tags.
+on:
+  push:
+    branches: [main]
+    paths:
+      - .github/workflows/publish-v0.5.0.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: doc2faq-v0.5.0-release
+  cancel-in-progress: false
+
+jobs:
+  compatibility:
+    name: Release Java ${{ matrix.java }} compatibility
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      max-parallel: 2
+      matrix:
+        java: ['21', '22', '23', '24', '25', '26']
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-java@v6
+        with:
+          distribution: temurin
+          java-version: ${{ matrix.java }}
+          cache: maven
+      - name: Build, test, and smoke-test the packaged application
+        run: |
+          mvn -B -ntp clean verify
+          bash scripts/smoke-packaged-jar.sh target/doc2faq-0.5.0.jar
+
+  publish:
+    if: github.repository == 'OKAN-SOFTWARE/Doc2FAQ' && github.ref == 'refs/heads/main'
+    # GitHub waits for every Java matrix entry; any failure skips publication.
+    needs: [compatibility]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-java@v6
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: maven
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Refuse to replace an existing v0.5.0 release or tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh release view v0.5.0 >/dev/null 2>&1; then
+            echo "v0.5.0 is already published. Refusing to overwrite it."
+            exit 1
+          fi
+          if [ -n "$(git tag -l v0.5.0)" ]; then
+            echo "The v0.5.0 tag already exists. Review it before publishing."
+            exit 1
+          fi
+
+      - name: Build and verify the release JAR
+        run: |
+          mvn -B -ntp clean verify
+          bash scripts/smoke-packaged-jar.sh target/doc2faq-0.5.0.jar
+
+      - name: Verify browser demo and Doc2FAQ homepage
+        run: |
+          node --test src/test/js/*.test.cjs
+          node scripts/build-website.mjs
+          node scripts/verify-website-build.mjs
+
+      - name: Package the Windows and standalone downloads
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p release/staging/Doc2FAQ-0.5.0
+          cp target/doc2faq-0.5.0.jar release/doc2faq-0.5.0.jar
+          cp release/doc2faq-0.5.0.jar release/staging/Doc2FAQ-0.5.0/
+          cp packaging/Start-Doc2FAQ.cmd packaging/WINDOWS-QUICK-START.md release/staging/Doc2FAQ-0.5.0/
+          # Windows cmd.exe expects CRLF-terminated batch files.
+          sed -i 's/$/\r/' release/staging/Doc2FAQ-0.5.0/Start-Doc2FAQ.cmd
+          (
+            cd release/staging
+            zip -q -r ../Doc2FAQ-0.5.0-Windows.zip Doc2FAQ-0.5.0
+          )
+          unzip -t release/Doc2FAQ-0.5.0-Windows.zip
+          unzip -p release/Doc2FAQ-0.5.0-Windows.zip Doc2FAQ-0.5.0/doc2faq-0.5.0.jar | cmp - release/doc2faq-0.5.0.jar
+          (
+            cd release
+            sha256sum doc2faq-0.5.0.jar Doc2FAQ-0.5.0-Windows.zip > SHA256SUMS.txt
+            sha256sum -c SHA256SUMS.txt
+          )
+
+      - name: Publish exactly the tested commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create v0.5.0 \
+            --target "$GITHUB_SHA" \
+            --title "Doc2FAQ v0.5.0 — Source & Review" \
+            --notes-file docs/RELEASE-NOTES-0.5.0.md \
+            --latest \
+            release/doc2faq-0.5.0.jar \
+            release/Doc2FAQ-0.5.0-Windows.zip \
+            release/SHA256SUMS.txt

.gitignore

@@ -17,3 +17,4 @@ Thumbs.db
 
 # Generated browser demo (built from tracked sources)
 /demo-dist/
+/website-dist/

CHANGELOG.md

@@ -2,11 +2,13 @@
 
 All notable Doc2FAQ changes are recorded here. Version numbers follow semantic versioning; entries describe shipped source functionality and do not imply an external AI service.
 
-## [0.5.0] — Unreleased
+## [0.5.0] — Unreleased (release candidate)
 
 ### Added
 - Browser PDF/Word (.docx) import and paginated export with local processing, PDF page/file/text limits, bounded DOCX XML decompression, optional references, and clear unsupported-file/font errors.
+- Browser PDF exports now embed bundled DejaVu Sans regular/bold font subsets instead of standard Helvetica, fixing Turkish and extended-Unicode text copied from web pages; unchanged Word exports continue to preserve the source characters.
 - Browser-only website demo built from the shared frontend, with simplified text drafting, explicit PDF/Word limitations, homepage navigation, and text exports.
+- Redesigned Doc2FAQ homepage and matching browser/Java workbench with an original document mascot, responsive illustrated cards, accessible focus styles, reduced-motion support, and a reproducible `website-dist/` build. The "What's new" section distinguishes development previews from published downloads.
 - Source & Review user guide and current documentation for development builds, schema compatibility, and v0.5.0 release preparation.
 - Read-only source viewer highlighting the selected FAQ's exact original passages, with a stacked layout on narrow screens.
 - Per-FAQ Needs review / Approved status, persisted in saved projects and optional browser autosave.
@@ -16,7 +18,11 @@ All notable Doc2FAQ changes are recorded here. Version numbers follow semantic v
 - Editing questions or answers and merging FAQs reset approval; incomplete FAQs cannot be approved.
 - Project schema 2 stores review status and upgrades schema-1 projects with Needs review defaults. Older application versions reject schema-2 files instead of silently discarding approval state.
 - Filters affect only the review list; saving, export preview, and all export formats retain every FAQ in draft order.
-- Development version is 0.5.0-SNAPSHOT; v0.4.0 remains the published release.
+- Export formats now open with PDF first and Word (.docx) second; the default download name uses `.pdf`.
+- **Clear saved data** is now a prominent, high-contrast action with a confirmation prompt. Cancel leaves the browser's saved draft intact; confirming removes only browser storage and keeps the current workspace open.
+- GitHub Actions now uses Node 24-based checkout/setup-java actions and pins Ubuntu 24.04 to avoid runner-label migration notices.
+- The v0.5.0 release gate validates **Java 21–26** with Java 21-compatible bytecode. Java 27 formal support is deferred, not declared incompatible: a transient JDK-download HTTP 504 caused an initial CI failure, and a later rerun **passed Java 27 build/tests and packaged-JAR smoke checks**.
+- Release-candidate source version is 0.5.0; v0.4.0 remains the published release until the new artifacts are validated and released.
 
 ## 0.4.0 — 2026-10-29
 

README.md

@@ -8,19 +8,21 @@ Created by **Okan Tiktas** · [OKAN-SOFTWARE](https://github.com/OKAN-SOFTWARE).
 
 > **Latest published download: v0.4.0 — Review, Save & Export.** Download the ready-to-run JAR or Windows ZIP from [GitHub Releases](https://github.com/OKAN-SOFTWARE/Doc2FAQ/releases/tag/v0.4.0).
 
-## Current source: v0.5.0-SNAPSHOT — Source & Review
+## Current source: v0.5.0 release candidate — Source & Review
+
+I redesigned Doc2FAQ with an illustrated homepage and a responsive FAQ workbench. Visit the [product homepage](https://okantiktas.com/projects/doc2faq/) for an overview, or try the [interactive browser demo](https://okantiktas.com/projects/doc2faq/demo/) to import documents, review FAQs, and export the results directly in your browser. The browser demo and downloadable Java application have different processing engines, so their FAQ suggestions may differ. See the [v0.5.0 changes](CHANGELOG.md#050--unreleased-release-candidate) and [design system](docs/DESIGN-SYSTEM.md) for details.
 
 - **Source beside answer:** select **View source beside answer** on an FAQ to highlight all of its original passages in a read-only document viewer beside the review editor on desktop (stacked on smaller screens). References still use extracted-text lines, not PDF page numbers. Manual FAQs have no automatic reference.
 - **Review status:** FAQs start as **Needs review**. Mark a complete answer **Approved** after checking it. Editing its question or answer, or merging FAQs, returns it to **Needs review**. Moving an item preserves approval; Undo restores the status from before a removal or merge.
 - **Search and review filters:** combine a case-insensitive question/answer search with **All statuses**, **Needs review**, or **Approved**. The summary shows visible, approved, and pending counts. **Clear filters** restores the full list. Filters never change what is saved, previewed, or exported: all FAQs remain included, and incomplete entries still block export.
 - **Saved work compatibility:** approval status is preserved in project downloads and optional autosave. New saves use project schema 2; v0.4 schema-1 files still open with FAQs marked Needs review. Schema-2 files require v0.5 or later to reopen.
 
-Development builds use `0.5.0-SNAPSHOT` in `pom.xml` (`target/doc2faq-0.5.0-SNAPSHOT.jar`). The latest published download remains v0.4.0 until a new release is validated and published.
+The release-candidate branch uses `0.5.0` in `pom.xml` (`target/doc2faq-0.5.0.jar`). The latest published download remains v0.4.0 until the release candidate passes validation and v0.5.0 is published. This branch is not itself a published release.
 
 ## New in v0.4.0
 
 - **Save work / Open saved work:** a versioned JSON file preserves source text, title, mode, draft order, edits, original excerpts, and duplicate-review choices. Incomplete FAQs can be saved too. Project files are limited to 4 MB and validated before replacing the workspace.
-- **Optional browser autosave:** off by default. Enabling it stores the complete source and draft on this browser's origin and restores them on reload. Disabling autosave or using **Clear saved data** removes Doc2FAQ's saved data without clearing your open workspace. Storage failures leave the draft open; use **Save work** as a backup.
+- **Optional browser autosave:** off by default. Enabling it stores the complete source and draft on this browser's origin and restores them on reload. The highlighted **Clear saved data** button asks for confirmation before removing the browser copy; canceling preserves it, and confirming leaves your current workspace open. Disabling autosave also removes the stored copy. Storage failures leave the draft open; use **Save work** as a backup.
 - **Source references:** expand **Show source** to see the original section, extracted-text line range, and exact passage. Edited questions and answers are marked for rechecking. References use text lines, not PDF page numbers; manually added FAQs have no automatic reference.
 - **Duplicate review:** distinct passages are retained even if their questions cover the same topic. Similar questions are flagged using a word-overlap heuristic. Choose **Keep both** or **Merge into this FAQ**. Merging keeps both answers and all source references; **Undo removal / merge** restores the previous items until another FAQ edit, addition, reorder, or review choice. Exact duplicate question/answer pairs are still filtered. The maximum remains 30 FAQs.
 - **PDF and Word export:** edited content, a centered document title, readable page layout, metadata, and page numbers. Optionally include section/line references and edited-answer notices. PDF embeds Lato Regular and Bold (see `src/main/resources/fonts/LICENSE-Lato.txt`); if text contains a glyph that font cannot represent, export returns an error and suggests DOCX.
@@ -52,15 +54,15 @@ The document placeholder now uses neutral Q&A prompts, and Generate Mode's sampl
 
 ## Try it in your browser
 
-[Open the interactive browser demo](https://okantiktas.com/projects/doc2faq/) · [Source & Review user guide](docs/USER-GUIDE.md) · [Demo capabilities and deployment](docs/WEB-DEMO.md)
+[Doc2FAQ homepage](https://okantiktas.com/projects/doc2faq/) · [Try the interactive browser demo](https://okantiktas.com/projects/doc2faq/demo/) · [Source & Review user guide](docs/USER-GUIDE.md) · [Demo capabilities and deployment](docs/WEB-DEMO.md) · [Design system](docs/DESIGN-SYSTEM.md)
 
-The demo processes pasted text and TXT/Markdown in your browser, using simplified rules. Try both drafting modes, source highlighting, editing, approval status, duplicate review, search/filters, saved projects, and Markdown/JSON/HTML exports. PDF/Word (.docx) import and export also run locally in the browser; PDF uploads are limited to 5 MB and 50 pages, and DOCX to 5 MB. Scanned PDFs need external OCR. The demo does not run a Java backend and its drafting rules remain simplified. Document libraries load from a version-pinned CDN when needed; document content is not uploaded. Browser PDF export uses standard Latin fonts and suggests Word when a character cannot be represented. The development demo may include features newer than the latest release download.
+The demo processes pasted text and TXT/Markdown in your browser, using simplified rules. Try both drafting modes, source highlighting, editing, approval status, duplicate review, search/filters, saved projects, and Markdown/JSON/HTML exports. PDF/Word (.docx) import and export also run locally in the browser; PDF uploads are limited to 5 MB and 50 pages, and DOCX to 5 MB. Scanned PDFs need external OCR. The demo does not run a Java backend and its drafting rules remain simplified. Document libraries load from a version-pinned CDN when needed; document content is not uploaded. Browser PDF export now embeds bundled DejaVu Sans fonts for Turkish and a wider range of Unicode characters; Word remains the fallback for unsupported scripts. The development demo may include features newer than the latest release download.
 
 For detailed changes, see [CHANGELOG.md](CHANGELOG.md). For the release checklist, see [docs/RELEASING.md](docs/RELEASING.md).
 
 ## Requirements
 
-- To run a release download: **Java 21**. The JAR works on Windows, macOS, and Linux; the Windows ZIP includes `Start-Doc2FAQ.cmd` and a quick-start guide. Extract the ZIP into a new folder, stop any older Doc2FAQ process, run the launcher, and open **http://localhost:8080**. Maven and Node.js are only needed to build and test from source.
+- To run a release download: **Java 21 or newer**. The JAR targets Java 21 bytecode; v0.5.0's **required automated compatibility matrix is Java 21–26**. Java 27 **passed an exploratory CI build and packaged-JAR smoke test** on November 8, 2026, but is not a committed v0.5.0 support target; formal support can follow in a later release. Newer Java versions are not automatically guaranteed compatible. The JAR works on Windows, macOS, and Linux; the Windows ZIP includes `Start-Doc2FAQ.cmd` and a quick-start guide. Extract the ZIP into a new folder, stop any older Doc2FAQ process, run the launcher, and open **http://localhost:8080**. Maven and Node.js are only needed to build and test from source.
 
 To build from source:
 
@@ -182,15 +184,15 @@ After updating your checkout to the latest `main`, run these commands from the d
 ```cmd
 mvn -B -ntp clean verify
 node --test src/test/js/*.test.cjs
-java -jar target/doc2faq-0.5.0-SNAPSHOT.jar
+java -jar target/doc2faq-0.5.0.jar
 ```
 
 The JavaScript checks require Node.js. Keep the terminal open while the app runs, and use **Ctrl+C** to stop it. Open **http://localhost:8080** and refresh the browser to load the updated frontend.
 
 If port 8080 is occupied, stop the previous Doc2FAQ process or use an alternate port:
 
 ```cmd
-java -jar target/doc2faq-0.5.0-SNAPSHOT.jar --server.port=8081
+java -jar target/doc2faq-0.5.0.jar --server.port=8081
 ```
 
 Then open **http://localhost:8081**. Merging source changes does not update an existing JAR or a running Java process; rebuild and restart to use the fixes. Published JARs must be built from the corresponding release commit.