Document that cached results are not invalidated by changes to neighboring files (e.g. BIDS sidecars) #114

Follow-up to #113.

annex_key_fingerprint(pair_with_path=True) pairs the key with the absolute path as given. That is intended: results stay separate per location, so a file whose result depends on its neighbors (e.g. a BIDS data file and its sidecar .json) is never served a result computed for the same content elsewhere.

But pairing does not make the result depend on those neighbors. If sub-01_bold.json changes and sub-01_bold.nii.gz does not, the key (path, key of the .nii.gz) is unchanged, so the cache returns the stale result. stat() mode has the same limitation, since it only fingerprints the argument itself. This is not a regression, just undocumented.

docs/design/git-annex-content.md currently says pairing is "needed whenever the result depends on the path, e.g. on the extension ... or on neighboring files". That's true, but it reads as if pairing were sufficient for neighbor-dependent results.

Suggested:

• Say explicitly, in the design doc and briefly in the memoize_path/annex_key_fingerprint docstrings, that only the first argument is fingerprinted, in both stat() and custom modes. Changes to other files the function reads (sidecars, inherited metadata, etc.) do not invalidate the cache.
• Optionally note how to handle it: a custom callable can fold the fingerprints of the relevant neighbors into its result (e.g. (annex_key_fingerprint(path), *(fingerprints of sidecars))), or the caller can pass them as extra arguments.