Metadata API: Document serialization "repro" issue

[jku]

It's not obvious to casual reader that reading metadata and then
writing it might not always produce the same file. It's also not
immediately obvious why this matters.

Document both concepts.

Fixes #1392

Signed-off-by: Jussi Kukkonen jkukkonen@vmware.com

It's a little wordy but I think it may be useful.

[coveralls]

Pull Request Test Coverage Report for Build 1805825853

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 97.89%

---

Totals
Change from base Build 1805452455:	0.0%
Covered Lines:	1112
Relevant Lines:	1132

---

💛 - Coveralls

[MVrachev]

The comments look good.

I wonder do we want to add a comment somewhere that even though when deserializing and serializing we don't get byte-for-byte equivalence we do get a consistent signature no matter the whitespaces?

[jku]

I can see that making the distinction could help... I'll try that (even if the paragraph is a bit long already)

[jku]

force pushed:

• rebased to get recent build fix
• added the mention that signatures are guaranteed to stay valid in a deserialize-serialize cycle even if the file content itself is not guaranteed to stay the same.

[MVrachev]

LGTM!

[MVrachev]

A smart way to mention that signatures are guaranteed to stay valid.

[lukpueh]

I like the clarification, modulo two nits:

• the claim "not guaranteed to be the same" depends on the serializer, which is configurable for both to_file and to_bytes. Maybe it's worth mentioning that?
• the reason "because of whitespace issues" is also specific to the default json serializer, and also only part of the problem (e.g. non-guaranteed dict key order is another problem). Maybe it's not necessary to mention a particular reason?

[jku]

Agreed on both comments, thanks, will update.

[jku]

I solved this by

• not mentioning whitespace as a reason
• just saying that serialization is not required to be byte-for-byte the same (the implication is that different serializers may make different decision, but that's not said)

[lukpueh]

Thanks for the update, @jku!