ENH: write_raw_bids() should not overwrite existing README

[bruAristimunha]

Describe the problem

write_raw_bids() creates a generic boilerplate README file ("This dataset was created with...") that contains no useful dataset-specific information. If a user has already created a comprehensive README with dataset-specific documentation, write_raw_bids() overwrites it.

Related: #1042

Describe your solution

Two possible approaches:

1. Don't overwrite existing README: If a README file already exists with content beyond the boilerplate, skip writing it.
2. Accept a readme parameter: Add an optional readme string parameter to write_raw_bids() that, when provided, is used instead of the boilerplate.

Option 1 is the least disruptive change and most backwards-compatible.

Describe possible alternatives

The current workaround is to write the README after all write_raw_bids() calls, overwriting the boilerplate. This works but requires careful ordering of operations.

Current downstream workaround (MOABB)

# After all write_raw_bids calls, overwrite the boilerplate README
readme_path = Path(root) / "README"
readme_path.write_text(_build_readme(dataset), encoding="utf-8")

Where _build_readme() generates a comprehensive document with paradigm info, channel setup, references, license, etc.

Additional context

• mne-bids version: 0.19.0.dev
• Discovered while building BIDS export in MOABB and eegdash
• Originally discussed at ENH: write_raw_bids() should not overwrite existing README bruAristimunha/mne-bids#16 with feedback from @drammock

[larsoner]

If a user has already created a comprehensive README with dataset-specific documentation, write_raw_bids() overwrites it.

Looking at overwrite=False here

mne-bids/mne_bids/write.py

Lines 2346 to 2349 in 8de579b

	# save readme file unless it already exists
	# XXX: can include README overwrite in future if using a template API
	# XXX: see https://github.com/mne-tools/mne-bids/issues/551
	_readme(bids_path.datatype, readme_fname, False)

and

mne-bids/mne_bids/write.py

Line 613 in 8de579b

if fname.is_file() and not overwrite:

It looks like if README already exists it should just append some refs. Maybe it shouldn't do this even... but it shouldn't overwrite the whole thing. Can you double check / make a minimal example? Maybe the code is indeed broken somehow...

Also our locking mechanics are broken there, if the file exists, we need to lock, read, write, and unlock. Not lock, read, unlock, write. It can lead to partially written files in multiple threads etc.

But really we should probably have readme=True mean current behavior (with fixed locking mechanics), meaning "write if missing, otherwise append refs" and readme=False can be used to mean "don't create or modify no matter what".

[bruAristimunha]

Addressed your three points in the latest push to #1592:

1. The issue body was inaccurate — current code only appends the references section, it doesn't clobber user content. Updated the PR design accordingly.
2. Locking fix in _readme: now lock once for the whole read-modify-write cycle (the previous lock → read → unlock → write race is gone). Inlined the write because _open_lock isn't actually re-entrant across separate FileLock instances — nesting it deadlocked the test suite.
3. Added readme=True/False to write_raw_bids with the semantics you described. Default keeps the existing behavior verbatim; readme=False skips the call entirely so the file is neither created nor modified.

PR diff is now +92/-19 across 3 files.