From 31a89840cd13c768a89add921d70cb9f444e8a0b Mon Sep 17 00:00:00 2001
From: OKAN TIKTAS <346542017+OKAN-SOFTWARE@users.noreply.github.com>
Date: Sat, 7 Nov 2026 21:37:38 -0500
Subject: [PATCH 1/9] Prepare Doc2FAQ v0.5.0 release candidate and Java 21-27
CI checks
---
.github/workflows/ci.yml | 16 ++++++--
CHANGELOG.md | 4 +-
README.md | 10 ++---
docs/RELEASING.md | 20 +++++++---
docs/USER-GUIDE.md | 2 +-
pom.xml | 3 +-
scripts/smoke-packaged-jar.sh | 75 +++++++++++++++++++++++++++++++++++
7 files changed, 113 insertions(+), 17 deletions(-)
create mode 100644 scripts/smoke-packaged-jar.sh
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d7243e0..397181c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -10,19 +10,29 @@ permissions:
jobs:
build-and-test:
runs-on: ubuntu-latest
- timeout-minutes: 10
+ timeout-minutes: 20
+ name: Java ${{ matrix.java }} compatibility
+ strategy:
+ fail-fast: false
+ matrix:
+ java: ['21', '22', '23', '24', '25', '26', '27']
steps:
- uses: actions/checkout@v4
- uses: actions/setup-java@v4
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
+ if: matrix.java == '21'
run: node scripts/build-web-demo.mjs
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 78189b5..f0dc685 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,7 @@
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.
@@ -16,7 +16,7 @@ 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.
+- 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
diff --git a/README.md b/README.md
index 57bb703..b3c9f1d 100644
--- a/README.md
+++ b/README.md
@@ -8,14 +8,14 @@ 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
- **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
@@ -60,7 +60,7 @@ For detailed changes, see [CHANGELOG.md](CHANGELOG.md). For the release checklis
## 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; GitHub Actions checks the released JDK versions 21–27 before v0.5.0 publication. Newer future 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,7 +182,7 @@ 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.
@@ -190,7 +190,7 @@ The JavaScript checks require Node.js. Keep the terminal open while the app runs
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.
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index e50eaa5..03623c9 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -1,20 +1,28 @@
# Doc2FAQ release checklist
-**Current source:** `0.5.0-SNAPSHOT`. **Latest published download:** v0.4.0. The next planned release is **v0.5.0 — Source & Review**. Merging source changes does not publish a release or update an installed JAR. Keep existing tags and assets unchanged.
+**Release-candidate branch:** `0.5.0`. **Latest published download:** v0.4.0. The next planned release is **v0.5.0 — Source & Review**. The release-candidate branch is not a published release. Merging source changes does not publish a release or update an installed JAR. Keep existing tags and assets unchanged.
-## Validate the development build
+## Validate the release candidate
-Use JDK 21, Maven 3.6.3+, and Node.js:
+Use JDK 21+, Maven 3.6.3+, and Node.js. CI compiles the application for Java 21 and runs Java tests plus a packaged-JAR smoke check on JDKs 21 through 27. All matrix jobs must succeed before publication:
```cmd
mvn -B -ntp clean verify
node --test src/test/js/*.test.cjs
node scripts/build-web-demo.mjs
-java -jar target/doc2faq-0.5.0-SNAPSHOT.jar
+java -jar target/doc2faq-0.5.0.jar
```
Open `http://localhost:8080` (or use `--server.port=8081` if occupied). Test the packaged JAR, not only a static frontend preview:
+On Linux or Git Bash, the optional automated JAR smoke check runs the packaged server locally, tests health, loads the frontend, and extracts an FAQ before stopping it:
+
+```sh
+bash scripts/smoke-packaged-jar.sh target/doc2faq-0.5.0.jar
+```
+
+GitHub Actions runs this smoke check on every push/PR. On Windows without Bash, use the equivalent manual checks below.
+
1. Import TXT, Markdown, PDF, and DOCX. Extract explicit questions and generate from ordinary sections; inspect exact excerpts and text-line ranges. Scanned PDFs must explain the OCR limitation.
2. Select an FAQ's source viewer and check all highlights, including multiple references after merge. Try a manual FAQ and HTML-like source text. Check desktop side-by-side and mobile stacked layouts. Typing in questions/answers must preserve page and source scroll positions.
3. Approve complete FAQs, then edit each field or merge and confirm Needs review. Blank entries cannot be approved. Move an approved FAQ and confirm approval remains. Remove/Undo restores status and references.
@@ -30,7 +38,7 @@ Open `http://localhost:8080` (or use `--server.port=8081` if occupied). Test the
## Prepare v0.5.0
1. Review and merge development changes after CI and packaged-JAR checks pass.
-2. Change `pom.xml` from `0.5.0-SNAPSHOT` to `0.5.0`; date the changelog section and update README source/run commands and download links. Keep historical v0.4.0 notes accurate. Review this release-preparation change.
+2. Review the release-candidate branch with `pom.xml` already at `0.5.0`. Verify the README and guide match the JAR name. Leave v0.4.0 labeled as the latest published download until v0.5.0 actually ships. Date the changelog and update download links at publication. Keep historical v0.4.0 notes accurate.
3. Update a clean checkout to the merged release commit, then build again:
```cmd
@@ -44,6 +52,8 @@ Open `http://localhost:8080` (or use `--server.port=8081` if occupied). Test the
java -jar target/doc2faq-0.5.0.jar
```
+ On Linux or Git Bash, also run `bash scripts/smoke-packaged-jar.sh target/doc2faq-0.5.0.jar` against the clean build. The application must be stopped before the manual JAR launch, unless you specify an alternate port.
+
4. Confirm a clean working tree and record the exact SHA. Repeat the packaged-JAR smoke check. Confirm that v0.5.0 does not already exist as a tag or release.
## Publish tested artifacts
diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md
index 21a7510..f87bc42 100644
--- a/docs/USER-GUIDE.md
+++ b/docs/USER-GUIDE.md
@@ -1,6 +1,6 @@
# Doc2FAQ — Source & Review guide
-This guide describes the `0.5.0-SNAPSHOT` source build. The latest published v0.4.0 download does not include the new source viewer or approval filters. See the [README](../README.md) for installation and [browser-demo comparison](WEB-DEMO.md) for the website's supported features.
+This guide describes the `0.5.0` release-candidate source build, which has not yet been published. The latest published v0.4.0 download does not include the new source viewer or approval filters. See the [README](../README.md) for installation and [browser-demo comparison](WEB-DEMO.md) for the website's supported features.
## Create a draft
diff --git a/pom.xml b/pom.xml
index 2dcadeb..0ef0c07 100644
--- a/pom.xml
+++ b/pom.xml
@@ -11,11 +11,12 @@
com.okansoftwaredoc2faq
- 0.5.0-SNAPSHOT
+ 0.5.0Doc2FAQPrivacy-conscious document-to-FAQ preview workbench21
+ 21
diff --git a/scripts/smoke-packaged-jar.sh b/scripts/smoke-packaged-jar.sh
new file mode 100644
index 0000000..ba22c2e
--- /dev/null
+++ b/scripts/smoke-packaged-jar.sh
@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+jar_path="${1:-target/doc2faq-0.5.0.jar}"
+port="${DOC2FAQ_SMOKE_PORT:-18080}"
+base_url="http://127.0.0.1:${port}"
+
+if [[ ! -f "$jar_path" ]]; then
+ echo "Packaged JAR does not exist: $jar_path" >&2
+ exit 1
+fi
+
+log_path="$(mktemp)"
+success=false
+app_pid=""
+
+cleanup() {
+ if [[ -n "$app_pid" ]]; then
+ kill "$app_pid" 2>/dev/null || true
+ wait "$app_pid" 2>/dev/null || true
+ fi
+ if [[ "$success" != true ]]; then
+ echo "Packaged application log:" >&2
+ sed -n '1,180p' "$log_path" >&2
+ fi
+ rm -f "$log_path"
+}
+trap cleanup EXIT
+
+java -jar "$jar_path" "--server.port=$port" >"$log_path" 2>&1 &
+app_pid=$!
+
+ready=false
+for ((attempt=1; attempt<=45; attempt++)); do
+ if curl --max-time 2 --fail --silent "$base_url/api/health" >/dev/null; then
+ ready=true
+ break
+ fi
+ if ! kill -0 "$app_pid" 2>/dev/null; then
+ echo "Packaged application exited before becoming ready" >&2
+ exit 1
+ fi
+ sleep 1
+done
+
+if [[ "$ready" != true ]]; then
+ echo "Packaged application did not become ready within 45 seconds" >&2
+ exit 1
+fi
+
+health="$(curl --fail --silent --show-error "$base_url/api/health")"
+printf '%s' "$health" | node -e '
+ const fs = require("node:fs");
+ const response = JSON.parse(fs.readFileSync(0, "utf8"));
+ if (response.status !== "ok" || response.aiEnabled !== false) process.exit(1);
+'
+
+index_html="$(curl --fail --silent --show-error "$base_url/")"
+if [[ "$index_html" != *Doc2FAQ* ]]; then
+ echo "Packaged frontend did not contain the expected application title" >&2
+ exit 1
+fi
+
+preview="$(curl --fail --silent --show-error \
+ --header 'Content-Type: application/json' \
+ --data-binary '{"content":"## What is Doc2FAQ?\nIt drafts FAQs from documents."}' \
+ "$base_url/api/faqs/preview")"
+printf '%s' "$preview" | node -e '
+ const fs = require("node:fs");
+ const response = JSON.parse(fs.readFileSync(0, "utf8"));
+ if (response.count !== 1 || response.items?.[0]?.question !== "What is Doc2FAQ?") process.exit(1);
+'
+
+success=true
+echo "Packaged JAR smoke test passed: health, frontend, and FAQ preview"
From 5983c064b6c3ebbe1cc8f7e48c09240840ee88aa Mon Sep 17 00:00:00 2001
From: OKAN TIKTAS <346542017+OKAN-SOFTWARE@users.noreply.github.com>
Date: Sun, 8 Nov 2026 04:30:53 -0500
Subject: [PATCH 2/9] ci: upgrade Node 24 actions and pin Ubuntu runner
---
.github/workflows/ci.yml | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 397181c..d08d38e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -9,7 +9,7 @@ permissions:
jobs:
build-and-test:
- runs-on: ubuntu-latest
+ runs-on: ubuntu-24.04
timeout-minutes: 20
name: Java ${{ matrix.java }} compatibility
strategy:
@@ -17,8 +17,8 @@ jobs:
matrix:
java: ['21', '22', '23', '24', '25', '26', '27']
steps:
- - uses: actions/checkout@v4
- - uses: actions/setup-java@v4
+ - uses: actions/checkout@v7
+ - uses: actions/setup-java@v6
with:
distribution: temurin
java-version: ${{ matrix.java }}
From 113a8af70b54cdf2fa7d98ddc5b48e0e1f18be18 Mon Sep 17 00:00:00 2001
From: OKAN TIKTAS <346542017+OKAN-SOFTWARE@users.noreply.github.com>
Date: Sun, 8 Nov 2026 04:37:26 -0500
Subject: [PATCH 3/9] ci: avoid duplicate PR runs and limit JDK download
concurrency
---
.github/workflows/ci.yml | 3 +++
1 file changed, 3 insertions(+)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d08d38e..b95506f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,6 +2,8 @@ name: Verify Doc2FAQ
on:
push:
+ branches:
+ - main
pull_request:
permissions:
@@ -14,6 +16,7 @@ jobs:
name: Java ${{ matrix.java }} compatibility
strategy:
fail-fast: false
+ max-parallel: 2
matrix:
java: ['21', '22', '23', '24', '25', '26', '27']
steps:
From 1309475a021f1b9ee20a67cb80b29574ce19a5ef Mon Sep 17 00:00:00 2001
From: OKAN TIKTAS <346542017+OKAN-SOFTWARE@users.noreply.github.com>
Date: Sun, 8 Nov 2026 05:38:43 -0500
Subject: [PATCH 4/9] ui: prioritize PDF and Word in export dropdown
---
src/main/resources/static/index.html | 8 ++++----
src/test/js/app-ui.test.cjs | 11 +++++++++++
2 files changed, 15 insertions(+), 4 deletions(-)
diff --git a/src/main/resources/static/index.html b/src/main/resources/static/index.html
index 63391d0..7d89015 100644
--- a/src/main/resources/static/index.html
+++ b/src/main/resources/static/index.html
@@ -99,7 +99,7 @@
Turn long documents into clear answers.
- .md
+ .pdf
Edit this name before downloading. The extension follows your chosen format.
@@ -107,14 +107,14 @@
Turn long documents into clear answers.
-
+
diff --git a/src/test/js/app-ui.test.cjs b/src/test/js/app-ui.test.cjs
index c62ac0d..066885f 100644
--- a/src/test/js/app-ui.test.cjs
+++ b/src/test/js/app-ui.test.cjs
@@ -7,6 +7,17 @@ const vm = require("node:vm");
const scriptPath = path.resolve(__dirname, "../../main/resources/static/app.js");
const source = readFileSync(scriptPath, "utf8");
+test("PDF and Word are the first two export choices, with PDF selected by default", () => {
+ const html = readFileSync(path.resolve(__dirname, "../../main/resources/static/index.html"), "utf8");
+ const menu = html.match(/