Misleading documentation about how block instances are stored

I think what it's trying to say is that the block field's blocks have their configuration stored in the entity field, so site builders and editors can easily tweak them WITHOUT impacting any configuration management.

Agreed it's unclear and doesn't make any sense currently.

@balazswmann could you perhaps help and prepare a MR for the README.md based on the reply from @joachim? That would surely help a lot. Thanks for raising this point!

I was initially confused by the description as well. It's correct, just that "configuration" is a bit ambiguous in this context. Took a stab at clarifying that it's concerning block configuration/settings.

This hopefully makes it clear that it's quite lightweight and essentially content on the entity, rather than something that from then on needs to be managed via Drupal config commits.

(It was already sentences, of course, i broke up one long sentence into two. I hope my edits are clearer than my commit message!)

Liked the improvement, tried to take it a little further.

Yep, fine with me. Just noticed there's test failures, but they don't seem to be related to any of these changes. Not sure if it's due to how the MR was set up.

@balazswmann & @joachim all fine with the new text?

LGTM and tests don't fail anymore, that was clearly unrelated!

Not sure this is much of an improvement. This introduces concepts that don't really exist like that, there is no such thing as an "original block" and "copy of that blocks configuration".

What we store is a block *plugin* ID and configuration for it. A block plugin has default configuration, but ours isn't a copy of that, it's just *the* configuration.

To differentiate it from block.module with the block config entities, what might be useful is to be more specific about that. Something like "This module does not store references to block config entities, which are placed in regions, it instead directly references the underlying block plugin ID's with configuration for them. As a result, each block placement is stored only in the given field as part of that content entity and is not part of Drupal's configuration management system.".

The storage here is fairly similar to layout_builder, that also stores block plugin ID's with configuration, it just also happens to have layouts as an extra wrapper, while we store only a single block per field item. Maybe comparing it with that will make it easier to understand? Something like a comparison table?

Thanks for clearing that up. Trying to maintain the emphasis on the original request, which is that the current description easily leads to the assumption that this utilises the site configuration system. Don't think this needs to get into layout storage comparison at this point, but might be useful in some more detailed doc?

Anyway, leaving it for others to refine this further if needed.