From patchwork Sat Aug 8 17:57:09 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nicolas George X-Patchwork-Id: 21545 Return-Path: X-Original-To: patchwork@ffaux-bg.ffmpeg.org Delivered-To: patchwork@ffaux-bg.ffmpeg.org Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by ffaux.localdomain (Postfix) with ESMTP id A470F44A9CE for ; Sat, 8 Aug 2020 20:57:19 +0300 (EEST) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 728D368B8F9; Sat, 8 Aug 2020 20:57:19 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from nef.ens.fr (nef2.ens.fr [129.199.96.40]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 8740568ABC2 for ; Sat, 8 Aug 2020 20:57:13 +0300 (EEST) X-ENS-nef-client: 129.199.129.80 ( name = phare.normalesup.org ) Received: from phare.normalesup.org (phare.normalesup.org [129.199.129.80]) by nef.ens.fr (8.14.4/1.01.28121999) with ESMTP id 078HvCW8020995 for ; Sat, 8 Aug 2020 19:57:13 +0200 Received: by phare.normalesup.org (Postfix, from userid 1001) id 8C63BE1DC8; Sat, 8 Aug 2020 19:57:12 +0200 (CEST) From: Nicolas George To: ffmpeg-devel@ffmpeg.org Date: Sat, 8 Aug 2020 19:57:09 +0200 Message-Id: <20200808175709.7359-1-george@nsup.org> X-Mailer: git-send-email 2.27.0 MIME-Version: 1.0 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (nef.ens.fr [129.199.96.32]); Sat, 08 Aug 2020 19:57:13 +0200 (CEST) Subject: [FFmpeg-devel] [PATCH v2] doc/developer: origin of tables should be documented. X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Tables that were not just written by the code author are not actually source code, otherwise, "recode data..x1 < proprietary.o > source.c" would be enough to launder a proprietary blob into the source code. Documenting the origin of the tables or the methods for their generation is necessary to let other developers take over if the original author is no longer available. Signed-off-by: Nicolas George --- doc/developer.texi | 8 ++++++++ 1 file changed, 8 insertions(+) I count: - Two objections, to which I have answered, and who have not given follow up. - One objection about a typo, I fixed "engineered" and proof-read everything carefully. - Two positive opinions. Andreas: > Not sure I agree with your definition of Libre Software and your exact I was more trying to express the difference between Libre Software and Open Source, which is minute in legal terms but huge in terms of mentality. Anyway, this part is only explanatory, it does not go into the tree. > wording of the patch. Have you suggestions to make it better? > I agree that leaving a hint of where the data comes from, directly where > the data is defined in the source code, is a good thing and probably not > to much to ask for. Thanks. diff --git a/doc/developer.texi b/doc/developer.texi index b33cab0fc7..c3103f31dc 100644 --- a/doc/developer.texi +++ b/doc/developer.texi @@ -216,6 +216,14 @@ please use av_log() instead. @item Casts should be used only when necessary. Unneeded parentheses should also be avoided if they don't make the code easier to understand. + +@item +If the code contains tables of numbers or other data, their origin should be +documented in a comment, so that other developers can rebuild them if +necessary. If they were taken from a reference, include the URL of that +reference. If they were computed by a tool, include the code of the tool. +If they were reverse-engineered, include an honest attempt at explaining the +methods used. @end itemize @section Editor configuration