diff --git a/README.md b/README.md index df37863..639f1ab 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ SonarCloud status: [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode.openfasttrace%3Aopenfasttrace-intellij-plugin&metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=org.itsallcode.openfasttrace%3Aopenfasttrace-intellij-plugin) **User Guides** +* [OpenFastTrace IntelliJ Plugin User Guide](doc/user_guide.md) * [OpenFastTrace User Guide](https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md) * [OpenFastTrace in IDE Help Action](src/main/java/org/itsallcode/openfasttrace/intellijplugin/help/OpenFastTraceUserGuide.java) * [OpenFastTrace IntelliJ Plugin Demo](doc/demo/plugin-demo.md) @@ -44,6 +45,8 @@ SonarCloud status: ## Using the Plugin Use an IntelliJ Platform IDE and install/build this plugin to get OFT support while editing project files. +For installation and workflow instructions, see the [OpenFastTrace IntelliJ Plugin User Guide](doc/user_guide.md). + The plugin currently focuses on: * syntax highlighting for OFT items in supported files * navigation support (`Go To Declaration`, symbol search, and related navigation paths) @@ -55,6 +58,7 @@ The plugin currently focuses on: * quick access to the OpenFastTrace user guide from the IDE help menu For expected behavior and scope details, see: +* [User Guide](doc/user_guide.md) * [System Requirements](doc/system_requirements.md) * [Runtime View](doc/design/runtime_view.md) * [Plugin Demo Script](doc/demo/plugin-demo.md) @@ -72,7 +76,7 @@ For manual IDE testing, launch a sandbox IDE with the plugin: ./gradlew manualTestIde ``` -## Using the Plugin +## Trace Settings After the sandbox IDE opens a project, configure trace scope under `Settings | Tools | OpenFastTrace`. By default, `Trace Project` scans the whole opened project. If you switch to selected-resource tracing, the plugin includes IntelliJ source roots, IntelliJ test roots, and one default additional project-relative path entry, `doc/`, until you change it. Additional files or directories are entered one per line. diff --git a/doc/changes/changes_0.8.0.md b/doc/changes/changes_0.8.0.md index e3c508d..73a1f65 100644 --- a/doc/changes/changes_0.8.0.md +++ b/doc/changes/changes_0.8.0.md @@ -17,3 +17,7 @@ The global `Tools | OpenFastTrace | Trace Project` action and new or previously ## Features #40: Integrate OFT Trace into Test Runner UI + +## Documentation + +#43: Add a use-case-centric plugin user guide diff --git a/doc/changesets/43-user-guide.md b/doc/changesets/43-user-guide.md new file mode 100644 index 0000000..1cc043b --- /dev/null +++ b/doc/changesets/43-user-guide.md @@ -0,0 +1,116 @@ +# GH-43 User guide + +## Goal + +Create a use-case-centric user guide for the OpenFastTrace IntelliJ plugin under `doc/user_guide.md`. + +The guide should move the user-facing usage documentation out of the short README overview and give users a practical path for installation, authoring, navigation, tracing, run configurations, and trace-result inspection. + +## Scope + +In scope: + +* create `doc/user_guide.md` +* create `doc/user_guide/images/` for screenshots referenced by the guide +* document plugin installation and typical plugin use cases +* reuse and expand the current README usage content where it is still accurate +* link the new plugin user guide from `README.md` +* keep documentation examples trace-safe when they contain OFT-looking IDs or coverage tags + +Out of scope: + +* changing plugin behavior or production code +* changing automated plugin tests +* changing `doc/system_requirements.md` +* changing `doc/design.md` or linked design chapters +* changing the IDE Help-menu action that opens the upstream OpenFastTrace user guide +* replacing or editing the upstream OpenFastTrace user guide +* adding dependencies, build plugins, or screenshot tooling + +## Design References + +* [GitHub Issue #43](https://github.com/itsallcode/openfasttrace-intellij-plugin/issues/43) +* [System Requirements](../system_requirements.md) +* [Solution Strategy](../design/solution_strategy.md) +* [Building Block View](../design/building_block_view.md) +* [Runtime View](../design/runtime_view.md) +* [Quality Requirements](../design/quality_requirements.md) +* [README](../../README.md) + +## Strategy + +Treat GH-43 as a documentation-only change. The issue explicitly excludes code, requirement, and design changes. + +The existing traced Open OFT User Guide feature describes the plugin action that opens the upstream OpenFastTrace user guide from the IDE. GH-43 adds a repository-local user guide for this IntelliJ plugin, so the product requirements and runtime design remain accurate unless implementation uncovers a contradiction. + +Because `traceRequirements` scans `doc/`, wrap any illustrative OFT specification items or coverage tags in `` / `` blocks, or phrase examples so they cannot be imported as live trace artifacts. Keep screenshots as ordinary documentation assets under `doc/user_guide/images/` and reference them with relative Markdown paths. + +## Task List + +- [x] Create and checkout a new Git branch `documentation/43-user-guide` + +### Requirements And Design + +- [x] Confirm GH-43 remains a documentation-only issue and explicitly excludes code, requirement, and design changes +- [x] Confirm the existing Open OFT User Guide requirements and design items describe the IDE action for the upstream OpenFastTrace guide, not the repository-local plugin user guide requested by GH-43 +- [x] Keep `doc/system_requirements.md` unchanged unless guide work reveals a real mismatch +- [x] Keep `doc/design.md` and linked design chapters unchanged unless guide work reveals a real mismatch +- [x] Record any discovered requirement or design mismatch before changing traced artifacts + +### User Guide + +- [x] Create `doc/user_guide.md` +- [x] Create `doc/user_guide/images/` +- [x] Add an installation section for installing or running the plugin from the available project/release workflows +- [x] Add a quick-start workflow that starts from an opened IntelliJ project containing OFT documents +- [x] Document syntax-highlighting support for supported specification documents and coverage tags +- [x] Document searching specification items through `Go to Symbol` +- [x] Document navigation from `Covers:` entries and coverage tags to specification item declarations +- [x] Document bundled OpenFastTrace live templates and completion in `Covers:` fields +- [x] Document project-wide and selected-resource tracing through `Tools | OpenFastTrace | Trace Project` +- [x] Document custom OpenFastTrace run configurations, trace inputs, artifact-type filters, tag filters, and output modes +- [x] Document the default IntelliJ Test Runner UI trace result view and source navigation from trace results +- [x] Document the existing Help-menu action that opens the upstream OpenFastTrace user guide +- [x] Add a short troubleshooting section for common user-guide-level problems such as no specification items found, missing navigation targets, and unexpected trace results +- [x] Add links to the demo script and demo example project where they help users practice the workflows + +### Screenshots + +- [x] Capture current screenshots from a sandbox or installed IDE session with the plugin enabled +- [x] Store screenshots under `doc/user_guide/images/` with stable lowercase kebab-case names +- [x] Add `doc/user_guide/images/plugin-installed.png` showing the plugin installed in `Settings | Plugins` +- [x] Add `doc/user_guide/images/syntax-highlighting.png` showing highlighted OFT items in the demo specification +- [x] Add `doc/user_guide/images/go-to-symbol.png` showing symbol search for an OFT item ID +- [x] Add `doc/user_guide/images/reference-completion.png` showing completion in a `Covers:` field or coverage-tag target +- [x] Add `doc/user_guide/images/trace-setting.png` showing `Settings | Tools | OpenFastTrace` +- [x] Add `doc/user_guide/images/run-configurations.png` showing an `OpenFastTrace` run configuration +- [x] Add `doc/user_guide/images/test-runner-results.png` showing trace output in the IntelliJ Test Runner UI +- [x] Add `doc/user_guide/images/help-user-guide.png` showing the Help-menu user-guide action or the opened guide tab +- [x] Reference the screenshots from the relevant sections in `doc/user_guide.md` +- [x] Verify each screenshot path referenced from `doc/user_guide.md` resolves correctly in GitHub Markdown +- [x] Keep screenshots focused on plugin UI and avoid unrelated IDE state or local user data + +### README Update + +- [x] Add the new plugin user guide link to the README `User Guides` section +- [x] Reduce duplicated usage details in README if the new guide becomes the authoritative user-facing usage document +- [x] Preserve the upstream OpenFastTrace User Guide link because it documents OFT syntax and tracing outside this plugin +- [x] Preserve the plugin demo link as a demonstration resource + +### Verification + +- [x] Run `./gradlew traceRequirements` and keep the repository OpenFastTrace trace clean +- [x] Verify examples in `doc/user_guide.md` do not create imported trace artifacts unless intentionally excluded from tracing +- [x] Verify all new README and user-guide links resolve locally +- [x] Verify all referenced images exist under `doc/user_guide/images/` +- [x] Confirm no dependency-policy review is needed because the change adds no third-party libraries +- [x] Confirm required build and plugin verification tasks are not additionally required because implementation touched only documentation and screenshot files + +## Version And Changelog Update + +- [x] Check the current version mentioned in the build scripts and code parameters against the latest GitHub release: `gradle.properties` currently uses `0.8.0`, while the latest GitHub release is `0.7.0` as of 2026-06-09 +- [x] Re-check the latest GitHub release immediately before version editing in case `0.8.0` has been published meanwhile +- [x] Keep the project version at `0.8.0` if it is still ahead of the latest GitHub release; otherwise raise the version to `0.8.1` as a documentation patch release +- [x] Add a changelog entry for GH-43 to the active release changelog +- [x] Update release date to 2026-06-09 or the actual implementation date +- [x] Ensure the issue list contains `#43: User guide` diff --git a/doc/user_guide.md b/doc/user_guide.md new file mode 100644 index 0000000..188b5c4 --- /dev/null +++ b/doc/user_guide.md @@ -0,0 +1,239 @@ +# OpenFastTrace IntelliJ Plugin User Guide + +This guide explains how to install and use the OpenFastTrace IntelliJ plugin in a JetBrains IDE. + +The plugin helps you author OpenFastTrace (OFT) documents, navigate between specification items and coverage links, and run OFT traces without leaving the IDE. + +For the OFT syntax and tracing concepts themselves, see the [OpenFastTrace User Guide](https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md). + +## Install The Plugin + +### Install A Release Build + +The plugin is distributed as a ZIP file on the repository's GitHub releases page: + + + +1. Open the latest release. +2. Download the plugin distribution ZIP from the release assets, for example `OpenFastTrace-.zip`. +3. In the IDE, open `Settings | Plugins`. +4. Open the gear menu and choose `Install Plugin from Disk...`. +5. Select the downloaded plugin ZIP. +6. Confirm the installation and restart the IDE when prompted. + +Use the plugin ZIP from the release assets. Do not install the GitHub-generated source-code ZIP. + +Later versions will hopefully be available via the marketplace. For now manual installation and update is unfortunately still necessary. + +![OpenFastTrace plugin installed in the IDE plugin settings](user_guide/images/plugin-installed.png) + +### Run A Development Build + +For local development or manual testing, clone this repository and launch a sandbox IDE: + +```sh +./gradlew manualTestIde +``` + +The sandbox IDE starts with the locally built plugin installed. + +## Open A Project + +Open the project that contains your OFT specification documents and source files. The plugin works on the files in the opened IntelliJ project and uses the IDE index for search, navigation, and completion. + +The checked-in demo project under [doc/demo/example](demo/example) is a small practice project. The guided walkthrough is in [doc/demo/plugin-demo.md](demo/plugin-demo.md). + +## Recognize OFT Content + +The plugin highlights OFT specification items in Markdown and reStructuredText specification files with these extensions: + +* `.md` +* `.markdown` +* `.rst` + +It also highlights OFT coverage tags in source, configuration, and markup files supported by the OpenFastTrace tag importer, for example Java, Kotlin, JavaScript, TypeScript, Python, shell scripts, JSON, YAML, TOML, SQL, Terraform, PlantUML, and Cucumber feature files. + +OFT files remain ordinary project files. The plugin only adds editor support, navigation, completion, and trace execution. + +![Highlighted OpenFastTrace specification items in a Markdown document](user_guide/images/syntax-highlighting.png) + +## Find Specification Items + +Use IntelliJ symbol search to find OFT specification item declarations across the project: + +1. Invoke `Navigate | Symbol...` or use `Search Everywhere` and switch to the `Symbols` tab. +2. Type the full or partial OFT item ID. +3. Select the matching item. + +The IDE opens the specification document at the item declaration. + +![OpenFastTrace specification items in IntelliJ symbol search](user_guide/images/go-to-symbol.png) + +## Navigate Between Items + +Use `Go To Declaration` on OFT references to jump to the declaring specification item. + +Supported navigation points include: + +* an item ID under a `Covers:` entry in a supported specification document +* the left side of an OFT coverage tag in a supported source or configuration file +* the right side of an OFT coverage tag in a supported source or configuration file + +When the caret is on an OFT item declaration, `Go To Declaration` stays on that declaration. Use `Go To Implementations` on the declaration to find covering occurrences such as `Covers:` entries and source-side coverage tags. + +## Author Specification Items With Live Templates + +The plugin bundles an `OpenFastTrace` live-template group under `Settings | Editor | Live Templates`. + +Use a template by typing its abbreviation in a supported editor context and pressing `Tab`. + +Common template abbreviations include: + +* `feat` for a feature +* `req` for a requirement +* `scn` for a scenario +* `dsn` for a design item +* `arch` for an architecture item +* `constr` for a technical constraint + +The `scn` template inserts a Given-When-Then scenario skeleton. Templates with a covered-item field can use completion while the caret is still inside that field. + +## Complete OFT References + +Use basic completion while editing a `Covers:` entry to select an existing specification item ID from the project index. + +![OpenFastTrace reference completion in a Covers entry](user_guide/images/reference-completion.png) + +Completion also works on the target side of a likely OFT coverage tag after the left-hand artifact type and arrow. For example, in a supported source file, start the tag and invoke completion after the arrow. + + + +```text +[impl->] +``` + + + +The completion list is based on declarations already present in the opened project. If the expected item is missing from completion, first verify that the item is declared in a supported specification file and that IntelliJ indexing has finished. + + +## Run A Project Trace + +Run a project trace from the main menu: + +1. Open `Tools | OpenFastTrace`. +2. Select `Trace Project`. + +The default keyboard shortcut is `Ctrl+Alt+Shift+O`. + +By default, the action traces the whole opened project and displays results in the IntelliJ Test Runner UI. + +## Configure The Trace Project Action + +Open `Settings | Tools | OpenFastTrace` to configure the global `Trace Project` action. + +![OpenFastTrace trace settings in the IDE settings dialog](user_guide/images/trace-setting.png) + +Choose one trace scope: + +* `Trace the whole project` scans the opened project root. +* `Trace selected resources` scans only the selected source directories, test directories, and additional paths. + +For selected-resource traces, configure these inputs: + +* `Include IntelliJ source directories` +* `Include IntelliJ test directories` +* `Additional project-relative files or directories (one per line)` + +The default additional path is `doc/`. Paths are resolved relative to the opened project root. The settings page validates the entered paths and shows the base directory used for resolution. + +Use `Artifact types:` to limit a trace to comma-separated artifact types such as `feat,req,scn,dsn`. + +Use `Tags:` to limit a trace to comma-separated OFT tags. + +Leave `Artifact types:` or `Tags:` empty to include all artifact types or tags. + +## Create OpenFastTrace Run Configurations + +Use OpenFastTrace run configurations when you need multiple repeatable trace setups. + +1. Open the run/debug configuration menu. +2. Choose `Edit Configurations...`. +3. Add a new `OpenFastTrace` configuration. +4. Configure the trace scope, artifact types, tags, and result view. +5. Save and run the configuration from the IDE toolbar. + +Run configurations use the same trace-scope controls as `Settings | Tools | OpenFastTrace`. + +They also let you choose the result view: + +* `IntelliJ Test Runner UI` shows a structured result tree. +* `Plain text output` shows the rendered OFT report in an IDE output tab with ANSI colors preserved. + +Use run configurations for recurring workflows such as tracing only a subsystem, tracing only requirement and design layers, or tracing a document set with a specific tag. + +![OpenFastTrace run configuration editor](user_guide/images/run-configurations.png) + +## Read Trace Results + +The default Test Runner UI groups trace results by source file, specification item, and trace link. + +Use it to: + +* see whether the trace passed or failed +* expand failed files and specification items +* inspect incoming and outgoing trace links +* read defect explanations in the details panel +* navigate from result nodes back to source files, specification declarations, and source-side coverage tags + +Clean items are shown as passed tests. Trace defects are shown as failed tests. The top-level trace result is marked failed when OFT reports trace defects. + +Plain text output is useful when you want the raw OFT report. Specification item IDs in the plain text output are clickable when the plugin can resolve them to project files. + +![OpenFastTrace trace result in the IntelliJ Test Runner UI](user_guide/images/test-runner-results.png) + +## Open The OpenFastTrace User Guide + +Use `Help | OpenFastTrace User Guide` to open the upstream OpenFastTrace user guide in an integrated IDE browser tab. + +Use that guide when you need details about OFT syntax, trace reports, importers, coverage tags, and command-line tracing outside the IntelliJ plugin. + +![OpenFastTrace user guide opened in an integrated IDE browser tab](user_guide/images/help-user-guide.png) + +## Troubleshooting + +### No Specification Items Appear In Symbol Search + +Check that the item is declared in a supported specification file extension: `.md`, `.markdown`, or `.rst`. + +Wait for IntelliJ indexing to finish. Symbol search and completion depend on the project index. + +### Navigation Does Not Jump To The Expected Item + +Check the item ID spelling, artifact type, name, and revision. OFT revisions are part of the ID, so `req~example~1` and `req~example~2` are different items. + +Check that the declaration exists in the opened project, not only in another checkout or a generated report. + +### Completion Does Not Suggest The Expected ID + +Verify that the target item is already declared in a supported specification file. + +For coverage-tag completion, invoke completion on the target side after the arrow in a supported source or configuration file. + +### Trace Project Scans Too Much Or Too Little + +Open `Settings | Tools | OpenFastTrace` and switch between `Trace the whole project` and `Trace selected resources`. + +For selected resources, verify the source-root checkboxes and the `Additional project-relative files or directories (one per line)` field. The field accepts one file or directory per line. + +### The Trace Is Red After Adding Documentation Examples + +If documentation contains illustrative OFT items or coverage tags that should not become part of the real trace, exclude those examples with OFT parser control comments named `oft:off` and `oft:on`. + +Keep real product requirements, design items, implementation tags, and tests outside excluded example blocks so OFT can continue tracing them. + +## Practice The Workflow + +For a guided live demonstration, use [doc/demo/plugin-demo.md](demo/plugin-demo.md) with the isolated example project in [doc/demo/example](demo/example). + +The demo walks through syntax highlighting, symbol search, live templates, completion, navigation, red and green trace results, source-side coverage tags, and the Help-menu guide action. diff --git a/doc/user_guide/images/go-to-symbol.png b/doc/user_guide/images/go-to-symbol.png new file mode 100644 index 0000000..54745ff Binary files /dev/null and b/doc/user_guide/images/go-to-symbol.png differ diff --git a/doc/user_guide/images/help-user-guide.png b/doc/user_guide/images/help-user-guide.png new file mode 100644 index 0000000..e41c78f Binary files /dev/null and b/doc/user_guide/images/help-user-guide.png differ diff --git a/doc/user_guide/images/plugin-installed.png b/doc/user_guide/images/plugin-installed.png new file mode 100644 index 0000000..b2de687 Binary files /dev/null and b/doc/user_guide/images/plugin-installed.png differ diff --git a/doc/user_guide/images/reference-completion.png b/doc/user_guide/images/reference-completion.png new file mode 100644 index 0000000..1279ca2 Binary files /dev/null and b/doc/user_guide/images/reference-completion.png differ diff --git a/doc/user_guide/images/run-configurations.png b/doc/user_guide/images/run-configurations.png new file mode 100644 index 0000000..0cf2a91 Binary files /dev/null and b/doc/user_guide/images/run-configurations.png differ diff --git a/doc/user_guide/images/syntax-highlighting.png b/doc/user_guide/images/syntax-highlighting.png new file mode 100644 index 0000000..42dc474 Binary files /dev/null and b/doc/user_guide/images/syntax-highlighting.png differ diff --git a/doc/user_guide/images/test-runner-results.png b/doc/user_guide/images/test-runner-results.png new file mode 100644 index 0000000..215af2b Binary files /dev/null and b/doc/user_guide/images/test-runner-results.png differ diff --git a/doc/user_guide/images/trace-setting.png b/doc/user_guide/images/trace-setting.png new file mode 100644 index 0000000..7e5122f Binary files /dev/null and b/doc/user_guide/images/trace-setting.png differ