Add initial documentation for context menu for linked file moval

[koppor]

Related issues and pull requests

Refs #12287

PR Description

We have some disussions at the PR #15055

This should bring in some clarity.

Steps to test

Read and try to follow - or update

Checklist

• I own the copyright of the code submitted and I license it under the MIT license
• [/] I manually tested my changes in running JabRef (always required)
• [/] I added JUnit tests for changes (if applicable)
• [/] I added screenshots in the PR description (if change is visible to the user)
• [/] I added a screenshot in the PR description showing a library with a single entry with me as author and as title the issue number
• [/] I described the change in CHANGELOG.md in a way that can be understood by the average user (if change is visible to the user)
• [.] I checked the user documentation for up to dateness and submitted a pull request to our user documentation repository

[InAnYan]

Should we add this field?

[koppor]

Because we don't have it in the other ADRs I assume

[InAnYan]

Not sure if X1, X2, are needed.

• Should there be a dot at the end?

[InAnYan]

I think this section is optional

[InAnYan]

Suggested change

	# Multi-file move uses a single chosen target directory for all selected files
	# Multi-file move should use a single target directory for all selected files

[InAnYan]

Isn't this behaviour obvious? It would be strange if I performed a move action to 1 directory and files would end up in different. Maybe I don't understand fully the context

[koppor]

Removed ADRs - included the alternatives in the requirements at 32b973f (this PR).

[qodo-free-for-open-source-projects]

Review Summary by Qodo

Add requirements documentation for linked file directory movement

📝 Documentation

Walkthroughs

Description

• Add comprehensive requirements documentation for linked file movement feature
• Define four directory types (MD, LSD, USD, LD) and their scopes
• Specify context menu behavior for moving files between directories
• Document design decisions and rejected alternatives

Diagram

flowchart LR
  A["Linked File Move Feature"] --> B["Directory Types Defined"]
  A --> C["Context Menu Requirements"]
  A --> D["File Movement Logic"]
  A --> E["Design Alternatives"]
  B --> F["MD, LSD, USD, LD"]
  C --> G["Show All Configured Dirs"]
  C --> H["Disable Current Directory"]
  D --> I["Preserve Subdirectory Structure"]
  E --> J["Rejected Designs Documented"]

Loading

File Changes

1. docs/requirements/linked-file-move-between-directories.md 📝 Documentation +96/-0

New requirements documentation for linked file directory movement

• New requirements document for issue #12287 defining linked file movement between directories
• Defines four directory types with IDs, names, and scopes (MD, LSD, USD, LD)
• Specifies seven functional requirements for context menu behavior and file movement logic
• Documents design rationale and two rejected alternative approaches
• Includes implementation status markers (TODO Needs: impl, utest) for each requirement

docs/requirements/linked-file-move-between-directories.md

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0)

1. Invalid Needs syntax 🐞 Bug ◔ Observability

Description

The requirements use TODO Needs: impl, utest instead of the documented OpenFastTrace metadata line
Needs: ..., so requirement tracing will likely not register the intended implementation/test
needs. This weakens/invalidates gradle traceRequirements coverage reporting for these new
requirements and introduces an undocumented convention used nowhere else in the repo.

Code

docs/requirements/linked-file-move-between-directories.md[32]

+TODO Needs: impl, utest

Evidence

The repo’s own requirements documentation and contributor guidance define Needs: ... as the
supported marker for requirement tracing; existing requirements files follow that exact syntax. The
new file is the only place that introduces the TODO Needs: variant, which is not documented and is
unlikely to be interpreted as OpenFastTrace metadata.

docs/requirements/index.md[30-35]
AGENTS.md[370-392]
docs/requirements/files.md[10-16]
docs/requirements/files.md[25-34]
docs/requirements/linked-file-move-between-directories.md[17-86]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The requirements page uses `TODO Needs: ...` which does not match the documented OpenFastTrace syntax (`Needs: impl`, `Needs: impl, utest`). As a result, `traceRequirements` likely won’t treat these as declared needs, making requirement coverage output incomplete and creating an inconsistent requirements authoring style.

## Issue Context
- Repo guidance for requirements specifies using an exact `Needs: ...` line (and shows examples).
- CI runs `gradle traceRequirements`, so requirements markup should remain compatible with the tracing plugin.

## Fix
Choose one of these consistent approaches:
1) **If you want these needs to be traceable now:** replace every `TODO Needs: ...` with `Needs: ...` and add the corresponding implementation/test trace tags when available.
2) **If you do NOT want to declare needs until implementation exists (to avoid failing trace coverage):** replace `TODO Needs: impl, utest` with a plain `TODO: impl, utest` (or remove the line), so it doesn’t look like OpenFastTrace metadata.

## Fix Focus Areas
- docs/requirements/linked-file-move-between-directories.md[30-86]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[InAnYan]

The approach with requirements is quite interesting.

Only nitpicks:

1. I would introduce feature and in the requirements wrote "Covers"
2. To turn off "Needs:" one could also write:

<--! oft:on --->
<--! oft:off --->

(HTML comment, I forgot the exact syntax, but the contents of the comment is right)

3. Also the requirements when "library is not saved" and "no directory set" - they are not equal?