[FFmpeg-devel] [PATCH] doc/APIchanges: document the lavu/lavf field moves

[James Almer]

On 6/30/2016 1:53 PM, James Almer wrote:
> On 6/30/2016 1:15 PM, Michael Niedermayer wrote:
>> The text is copied from the lavfi case. Not sure this matches
>> exactly private / public ABI wise, better text welcome!
>>
>> Signed-off-by: Michael Niedermayer <michael at niedermayer.cc>
>> ---
>>  doc/APIchanges |   16 ++++++++++++++++
>>  1 file changed, 16 insertions(+)
>>
>> diff --git a/doc/APIchanges b/doc/APIchanges
>> index 47106c2..fd649d6 100644
>> --- a/doc/APIchanges
>> +++ b/doc/APIchanges
>> @@ -15,6 +15,22 @@ libavutil:     2015-08-28
>>  
>>  API changes, most recent first:
>>  
>> +2016-06-30 - c1c7e0ab - lavf 57.41.100 - avformat.h
>> +  Fix accidental ABI breakage in AVFrame.
>> +  ABI was broken in 6f69f7a8, lavf 57.32.100 and released as ffmpeg 3.1.
> 
> AVStream, and again, there was *no* breakage in 3,1. A public field
> was added above private fields.
> The breakage is what we're now introducing in 3.1.1 to keep people
> misusing the API happy.
> 
> if we add a line here, it should mention how we're in breaking the
> 3.1 ABI to make 3.1.1 compatible at runtime with API-violating
> applications built against 3.0

How about something like

diff --git a/doc/APIchanges b/doc/APIchanges
index 47106c2..c80606a 100644
--- a/doc/APIchanges
+++ b/doc/APIchanges
@@ -15,6 +15,30 @@ libavutil:     2015-08-28

 API changes, most recent first:

+2016-06-30 - c1c7e0ab - lavf 57.41.100 - avformat.h
+  Moved codecpar field from AVFilterContext to the end of the struct.
+  This is an intentional ABI breakage as it's been informed to us that
+  several downstream projects wrongly accessed fields marked as private
+  which were below the newly added public field.
+
+  Because of this, said applications built against lavf <= 57.32.100
+  experienced problems when trying to use lavf >= 57.33.100 at runtime.
+
+  The availability of private fields in public structs will be limited
+  or removed in future releases to prevent unfortunate misuses like this.
+
+2016-06-30 - 042fb69d - lavu 55.28.100 - frame.h
+  Moved hw_frames_ctx field from AVFrame to the end of the struct.
+  This is an intentional ABI breakage as it's been informed to us that
+  several downstream projects wrongly accessed fields marked as private
+  which were below the newly added public field.
+
+  Because of this, said applications built against lavu <= 55.17.100
+  experienced problems when trying to use lavu >= 55.18.100 at runtime.
+
+  The availability of private fields in public structs will be limited
+  or removed in future releases to prevent unfortunate misuses like this.
+
 2016-06-29 - xxxxxxx - lavfi 6.47.100 - avfilter.h
   Fix accidental ABI breakage in AVFilterContext.
   ABI was broken in 8688d3a, lavfi 6.42.100 and released as ffmpeg 3.1.


Comments about how to improve it are welcome.