On 22.01.2018 03:10, Philippe Mathieu-Daudé wrote: > Hi Thomas, > >> This series introduces 5 different flavors of deprecation >> messages: >> >> * "Too old" >> * "Unmaintained" >> * "The ZCU102 machine has the same features supported" >> * "Use the \"pc\" machine instead" >> * "Obsoleted by the \"40p\" machine" >> >> Can we clearly document guidelines and examples for values of >> this field, to help ensure consistency? >> >> Examples of questions that could be answered in the field >> documentation: >> >> * Should the message start with an uppercase letter? >> * Should it really explain _why_ it was deprecated, or is a >> simple "please use xlnx-zcu102 instead" good enough? >> * Which of the following is preferred: >> * "obsoleted by the \"pc\" machine" >> * "obsoleted by \"pc\"" >> * "use \"pc\" instead" >> * "too old, use \"pc\" instead" >> * "too old; use \"pc\" instead" >> * <something else?> > > Do you have any preference regarding Eduardo's suggestions? > > I see this pattern: > > - obsoleted by newer > -> hint about replacement > - too old, unmaintained (maybe suggest use an older version?) > -> hint when removal is scheduled
I don't mind the exact wording, as long as there is an indication for the user what to do next (if possible). > These are also valid for Devices. > > Now if we want a consistent guideline, I suggest we clearly document the > deprecated machines/devices in qemu-doc.texi and extract this > information at build time, like trace.h. While it's a must of course to document deprecations in the qemu-doc, automatic extraction already sounds like over-engineering to me. I don't think that we are going to have as much deprecation entries as trace points, so would an additional automatic mechanism really help a lot here? Thomas
