See PHI1321.

Currently, diffs are created with differential.creatediff or differential.createrawdiff. These are both older methods which are not transaction-oriented. differential.creatediff is unrealistic for third-parties to call on their own because the format of changes is complex. differential.createrawdiff can not affect most of the fields. Neither method can interact with custom fields or extensions.

Both methods are limited to accepting JSON changes (i.e., UTF8 data which is not binary), and neither method can accept very large diffs.

Instead:

• Diff creation should happen through a modern differential.diff.edit API method.
• We should provide multiple transaction types for specifying a diff source, including "raw string" and "pointer to a file containing a raw string, which may be arbitrarily large and/or include binary data".
• In the longer run, arc should use this as well, although we may want or need to preserve the behavior where arc submits a complex data structure instead of a raw blob because there are some weird cases where we run additional commands to supplement the information present in a diff and may not be able to represent everything completely in a raw diff. A possible simple example of this is that it's faster and more flexible for us to upload raw data for enormous_1GB_photo_encoded_lossessly.png than to encode it in base85 as part of a bigger change, upload that, and then make the server decode it back into actual data.
• In the future, this API can also support creating a diff directly from a range of commits (by specifying commit names or PHIDs in the transaction).