Metadata API: Document serialization "repro" issue

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 theupdateframework#1392

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

tuf/api/metadata.py

@@ -232,6 +232,13 @@ def to_bytes(
     ) -> bytes:
         """Return the serialized TUF file format as bytes.
 
+        Note that if bytes are first deserialized into ``Metadata`` and then
+        serialized with ``to_bytes()``, the two are not guaranteed to be the
+        same because of whitespace issues. If byte-for-byte equivalence is
+        required (which is the case when the content hashes have already been
+        inserted into other metadata), the original content should be used
+        instead of re-serializing.
+
         Arguments:
             serializer: A MetadataSerializer instance that implements the
                 desired serialization format. Default is JSONSerializer.
@@ -265,6 +272,13 @@ def to_file(
     ) -> None:
         """Writes TUF metadata to file storage.
 
+        Note that if a file is first deserialized into ``Metadata`` and then
+        serialized with ``to_file()``, the two files are not guaranteed to be
+        the same because of whitespace issues. If byte-for-byte equivalence is
+        required (which is the case when file hashes have already been inserted
+        into other metadata), the original file should be used instead of
+        re-serializing.
+
         Arguments:
             filename: The path to write the file to.
             serializer: A MetadataSerializer instance that implements the