From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id ACECHlfWdmP4MwAAbAwnHQ (envelope-from ) for ; Fri, 18 Nov 2022 01:48:23 +0100 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id 0OwRHVfWdmNuUgAAG6o9tA (envelope-from ) for ; Fri, 18 Nov 2022 01:48:23 +0100 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 2D7571903E for ; Fri, 18 Nov 2022 01:48:23 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ovpXL-0006Tq-Ai; Thu, 17 Nov 2022 19:47:19 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ovpWs-0006Qm-Bl for emacs-orgmode@gnu.org; Thu, 17 Nov 2022 19:47:14 -0500 Received: from mail-pl1-x62f.google.com ([2607:f8b0:4864:20::62f]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1ovpWm-0004b6-BP; Thu, 17 Nov 2022 19:46:47 -0500 Received: by mail-pl1-x62f.google.com with SMTP id p21so3190631plr.7; Thu, 17 Nov 2022 16:46:42 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:message-id:in-reply-to:date :subject:cc:to:from:user-agent:references:from:to:cc:subject:date :message-id:reply-to; bh=dIBpHLuWsXx7b+6vP8FAwT9F4NBq93T2fpT6vw+Cdsg=; b=hxC3++koe2lBPJ1zub1hL2BntSmeKhxDKwEyNmDWPFq62SxsJN89v2KcshApy/HVUM T0uiXklnL/G6ew13PM1m0JjvAUWuu+AWFOlO2/9YMqP/9EWV8b4kzo1ODAGCZuTFauVt weIfGHDt/KUL44UYaMPOXSlXm20tiqSOivC+Ko2+oTyOXsdu2AYXMLJHH4pHg7v/o9X8 GPiGVMmbd7xUuBUV49r6mNlOQrtaB2rXO/8p4QzrVKpV6Rx7l3bTkefnWDTSowcigRlB LAsjoWorSUkb6HpfcRt8Y0aUCx/Nzv+WKxb0D4+cjR/gOKmHIWVhGyfwuk89mYnVRoIr 3w9A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:message-id:in-reply-to:date :subject:cc:to:from:user-agent:references:x-gm-message-state:from:to :cc:subject:date:message-id:reply-to; bh=dIBpHLuWsXx7b+6vP8FAwT9F4NBq93T2fpT6vw+Cdsg=; b=d/c2D/0euRP/IDD9UWr1l/PVujlKwAONRyxMi1mxG8n5y7j6yWHxtE0crCFE6bojJq r3lGLkmYvHDx+rdh//pIwkwUt437tiLctSoYO88Zfa5vXJt/Smq9qsfYjS5EBEOlunjw kKNb1FdeWSsD+KJz1h/TQ1xUtvfhk4pyAYdtzZgWmrYFtPPI82F9WMzC8vJ0VDHtLVSr qKZQQHGHo87R3rJdh71i4raCp55esc3khfmos5M5DjjrKPrB1Y0yKTQtJNjZ9vhs7H6+ 3AUiyLdD438aQFVcxt5gsZ4A1qIF/5A2SmL7pdkv6ShoRnIn/hO4yLQ8a/gdSoMWDNad p4yw== X-Gm-Message-State: ANoB5plxy0nM6FstLgqZK/VuLECAo734esASYuEUL/cWOrdEqmySzK4Q v/lHxxQRsQ/L3d8lxRo0cm5gbH9EXlQ= X-Google-Smtp-Source: AA0mqf4AmxLixJrcizOTF4+OW+lJJTgA92xQABIw4wyHtj7PZ2qoaF9fXtImBOvEEPKTJcuTiVaeXQ== X-Received: by 2002:a17:90b:2542:b0:1fb:e7a:79b with SMTP id nw2-20020a17090b254200b001fb0e7a079bmr11444611pjb.93.1668732401123; Thu, 17 Nov 2022 16:46:41 -0800 (PST) Received: from dingbat (220-235-181-183.dyn.iinet.net.au. [220.235.181.183]) by smtp.gmail.com with ESMTPSA id c27-20020a056a00009b00b0056c04dee930sm1787482pfj.120.2022.11.17.16.46.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 17 Nov 2022 16:46:40 -0800 (PST) References: <87h6z69myp.fsf@localhost> <86wn7ubflw.fsf@gmail.com> <87cz9lbxdd.fsf@localhost> User-agent: mu4e 1.9.2; emacs 29.0.50 From: Tim Cross To: Ihor Radchenko Cc: Bastien , emacs-orgmode@gnu.org Subject: Re: [MAINTENANCE] Do we have any backwards-compatibility policy for third-party packages? Date: Fri, 18 Nov 2022 10:38:06 +1100 In-reply-to: <87cz9lbxdd.fsf@localhost> Message-ID: <86iljd3x90.fsf@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=2607:f8b0:4864:20::62f; envelope-from=theophilusx@gmail.com; helo=mail-pl1-x62f.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1668732503; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=dIBpHLuWsXx7b+6vP8FAwT9F4NBq93T2fpT6vw+Cdsg=; b=GcU7SB1PZ10ztElXjpaQgiWjKrPF6e01Oea+YGoYP0yrHdeqBv078nyNu5/fgqWOXsrlc/ OW+E3Xrm4fCXGKdc447ITWzOhd2dIT6fbLOUmpbcPxdqL9kLKvhscAglpWegZFzvRgLAxH ypBxyIF6AYmwcmwMlDIR0U0Qd0VKD5qoR6jHp66NBXCXBIHZipc90TnsjOXxtdYvCNPegg v4oYyYeHYL9yWuiVKCuS8po4YiRPq5LAP4l4XGhyyk6Ixt30qr2e0YuRld6rK2ABDuGZZr Z+MEJsTURPN8fpEAj6S/1JURDfrx9DlLlwqxlgVTJtknFw0sGxk95xtVrs5Ksw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1668732503; a=rsa-sha256; cv=none; b=bVnyrAG1I3VLAiQGgxDmlWrwsCURXrQtoNoBa740LRHnFYhhhB8w8e6SiF4aL3K8wifJte WvT+Oeo2mKdMoBm1Vj5mljBh6HNuoTS4Yk73imWJSAKL0DqgnyBxNJGUcV5EiZ0XRrVpoM S0oP02ZftJESSPO2HeoVRmCS5NaJcu+Vw6eTFlTvIy3ayj982iFskLbZOLZ1hI2pqs0mLD GQRt3IXUTZx0OU/fGLSKmYoez2FLgKdRFVIEKGY2Hb5Q4Ztr6CfZtPzw893KWu0hKs+zxY 763XOONb31iLcdzWhkUQvZCNEVL28feePM1HVLZyB3TqE0kVr5F6ZzghtGmK3A== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=hxC3++ko; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -1.53 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=hxC3++ko; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 2D7571903E X-Spam-Score: -1.53 X-Migadu-Scanner: scn1.migadu.com X-TUID: imS5ETQs0bfI Ihor Radchenko writes: >> It might be worthwhile defining what is meant by 3rd party packages. >> >> For example, ob-scheme relying on geiser as a 3rd party package is one >> thing. Org roam is another type of 3rd party package. I think they need >> different approaches. The first is about our (org) interface to them and >> the latter is about their (org roam) interface with org. > > Sorry for not being clear. > I was referring to third-party packages Org optionally depends on. > Like geiser or citeproc or engrave-faces. > >> For the former (e.g. geiser type), I don't think backwards compatibility >> is as important. Thanks to package.el and GNU ELPA/NONGNU ELPA, it is >> fairly trivial to update to the current version. We just need to support >> the current version. > > Yes, but what if, say, the newest geiser version no longer supports the > Emacs version Org still supports? > I guess we are limited by what the packages we rely on support. For example, if geiser doesn't support Emacs 26 but org is supposed to, there isn't much we can do. We cannot afford to fork geiser and modify it to add the support and even if we provided a patch to add the support to the geiser project, they may not merge it. Best we can do is best effort and reflect this limitation in the manual where we stipulate what our backwards compatibility policy is.=20 >> For the latter (e.g. org-roam), backwards compatibility is much more >> important. Org needs to provide as stable a public API for such packages >> as possible. It may even be worthwhile separating the API into a >> public/external API and an internal/private API. The former would be as >> stable as possible and when changes are made, all efforts to provide >> backwards compatibility are made. The latter is also stable, but more >> subject to change. It is the API intended for internal org use. If >> external packages use it, it is at their own risk. We would still try to >> keep it stable, but with less of a guarantee and we may not provide >> backwards compatibility if doing so was going to cause too much >> complexity or maintenance burden etc. > > That's what we already do. > I mean, https://bzg.fr/en/the-software-maintainers-pledge/ :) > > Public/private is the usual org-* vs. org--*. > We never break org-*. Even if we do, we first deprecate things. > Yes, I know. I included it for completeness. However, I'm not convinced worg is an effective communication channel for this information. We may need to either add it to the manual or reference it from the manual. (I'm reminded of the Douglas Adams quote from the Hitch Hikers Guide [1]). >> The big thing here is IMO avoiding surprise. We probably should add a >> section to the 'Hacking' section of the manual which outlines our >> position wrt backwards compatibility and API (public/private) and change >> etc. I think most people expect change (even if they might not like >> it). What they don't like is unexpected change. As long as we are >> conservative and communicate change when necessary, we will likely be >> OK. > > I hope that we never had unexpected changes. Isn't it for granted? I > felt like it was always the case in Org and Emacs forever. > > It feels so obvious that I cannot even figure out how we could clarify > it in the manual. The one thing we can expect is unexpected change! What is expected by one can be unexpected by others and what may seem obvious to you or me may not be as obvious to others. We should be extremely careful about assumptions regarding what can be taken for granted. Org mode has a very broad user base. We have users with varying familiarity with Emacs, software development practices and basic software lifecycle management. For example, I know that symbol names with '--' in them tend to indicate private API elements. However, that is because I've been using Emacs for a long time. Someone new or someone who is not a programmer may not be familiar with this convention. There has been multiple occasions where I've seen posts on this list from users complaining about unexpected and breaking changes. Such posts usually end up in a thread about all the things org developers do to try and mitigate such things. This would indicate it isn't necessarily taken for granted by all. Often, those complaining were unaware of changes being documented in the NEWS file or failed to check it before upgrading or were unaware of backwards compatibility policy or didn't understand the extent to which org relies on other external packages/services etc. Then there is the situation where a change has unforeseen impact. Consider the change a while ago with electric-indent. I agree that in general, the org development process is pretty good in its approach to handling change and maintenance of compatibility. Where we are perhaps a little weak is in ensuring we communicate this effectively.=20 Perhaps we don't need to do anything extra. However, I feel it would be beneficial to be very explicit regarding how we manage change and what developers will promise and provide some guidance on how to use the org APIs in the manual. Start from the position of users who have no familiarity with what we do or even common development/maintenance processes. Take little for granted and be explicit. I would consider - Adding a section regarding pubic/private API and naming conventions to the Hacking section of the manual. This section could outline what the processes are for adding/changing APIs.=20 - Add the maintainers pledge to the manual as well. It is useful for users to know what the maintainers pledge to try and do. I doubt many users will find the page on worg which already exists. At the very least, add a link to the wrog page. - Briefly document the org maintenance and release process or add links to relevant worg pages. .=20 One possibility would be to add/extend the 'Hacking' section to be 'Maintenance & Hacking' and add new sections which explicitly outline the maintenance approach, the API conventions, the developer/maintainer pledge, filing bug reports, requesting API change/enhancements, etc. I realise some of this information is already in the manual (for example, the feedback section covers submitting bug reports) and we could either move it or reference that information. I also know much of this is covered in worg, but I'm not sure that is a terribly effective communication channel in itself. It may be sufficient to just add links to worg content. However, for content which is very static, I think it would be good to add it into the manual as I suspect that is the first port of call for most users. --- [1] =E2=80=9CBut the plans were on display=E2=80=A6=E2=80=9D =E2=80=9COn display? I eventually had to go down to the cellar to find = them.=E2=80=9D =E2=80=9CThat=E2=80=99s the display department.=E2=80=9D =E2=80=9CWith a flashlight.=E2=80=9D =E2=80=9CAh, well, the lights had probably gone.=E2=80=9D =E2=80=9CSo had the stairs.=E2=80=9D =E2=80=9CBut look, you found the notice, didn=E2=80=99t you?=E2=80=9D =E2=80=9CYes,=E2=80=9D said Arthur, =E2=80=9Cyes I did. It was on display in the bottom of a locked filing cabinet stuck in a disused lavatory with a sign on the door saying =E2=80=98Beware of the Leopard.=E2=80=9D - Douglas Adams, The Hitchhike's Guide to the Galaxy