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

Signed-off-by: Jussi Kukkonen <[email protected]>

Author: Jussi Kukkonen

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 required to be
+        identical even though the signatures are guaranteed to stay valid. If
+        byte-for-byte equivalence is required (which is the case when content
+        hashes are used in 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 required to be
+        identical even though the signatures are guaranteed to stay valid. If
+        byte-for-byte equivalence is required (which is the case when file
+        hashes are used in 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