Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-8.5 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,NICE_REPLY_A,SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_SANE_1 autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 8FB19C433E0 for ; Wed, 15 Jul 2020 14:41:37 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 6922020658 for ; Wed, 15 Jul 2020 14:41:37 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 6922020658 Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=suse.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1jvib9-0000h0-9a; Wed, 15 Jul 2020 14:41:27 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1jvib7-0000gv-U0 for xen-devel@lists.xenproject.org; Wed, 15 Jul 2020 14:41:25 +0000 X-Inumbo-ID: 42140728-c6a9-11ea-bca7-bc764e2007e4 Received: from mx2.suse.de (unknown [195.135.220.15]) by us1-rack-iad1.inumbo.com (Halon) with ESMTPS id 42140728-c6a9-11ea-bca7-bc764e2007e4; Wed, 15 Jul 2020 14:41:25 +0000 (UTC) X-Virus-Scanned: by amavisd-new at test-mx.suse.de Received: from relay2.suse.de (unknown [195.135.221.27]) by mx2.suse.de (Postfix) with ESMTP id BD406AF70; Wed, 15 Jul 2020 14:41:27 +0000 (UTC) Subject: Re: [PATCH v2] docs: specify stability of hypfs path documentation To: George Dunlap , Jan Beulich References: <20200713140338.16172-1-jgross@suse.com> <8a96b1b9-cbcb-557a-5b82-661bbe40fe25@suse.com> <68F727A8-29B8-4846-8BE9-BD4F6E0DC60D@citrix.com> From: =?UTF-8?B?SsO8cmdlbiBHcm/Dnw==?= Message-ID: <8505ec1a-bc50-ea16-306f-998c27045e30@suse.com> Date: Wed, 15 Jul 2020 16:41:22 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.9.0 MIME-Version: 1.0 In-Reply-To: <68F727A8-29B8-4846-8BE9-BD4F6E0DC60D@citrix.com> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 8bit X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Cc: Stefano Stabellini , Julien Grall , Wei Liu , Paul Durrant , Andrew Cooper , Ian Jackson , "open list:X86" Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" On 15.07.20 16:37, George Dunlap wrote: > > >> On Jul 13, 2020, at 3:47 PM, Jan Beulich wrote: >> >> On 13.07.2020 16:03, Juergen Gross wrote: >>> In docs/misc/hypfs-paths.pandoc the supported paths in the hypervisor >>> file system are specified. Make it more clear that path availability >>> might change, e.g. due to scope widening or narrowing (e.g. being >>> limited to a specific architecture). >>> >>> Signed-off-by: Juergen Gross >>> Release-acked-by: Paul Durrant >> >> Acked-by: Jan Beulich >> >> However, I'd like agreement by at least one other REST maintainer on >> ... >> >>> @@ -55,6 +58,11 @@ tags enclosed in square brackets. >>> * CONFIG_* -- Path is valid only in case the hypervisor was built with >>> the respective config option. >>> >>> +In case a tag for a path indicates that this path is available in some >>> +case only, this availability might be extended or reduced in future by >>> +modification or removal of the tag. A path once assigned meaning won't go >>> +away altogether or change its meaning, though. >> >> ... the newly imposed guarantee we're now making. We really want to >> avoid declaring something as stable without being quite certain we >> can keep it stable. > > The declaration of new nodes must all happen in this file, right? So as long as the maintainer(s) fo this file are aware of that, and it’s commented so that people know that expecation, I think it’s OK. > > But I think this paragraph isn’t very clear to me what “might be extended or reduced …but won’t go away altogether”. > > IT sounds like you’re saying: > > 1. Paths listed without conditions will always be available > > 2. Paths listed with conditions may be extended: i.e., a node currently listed as PV might also become available for HVM guests > > 3. Paths listed with conditions might have those conditions reduced, but will never entirely disappear. So something currently listed as PV might be reduced to CONFIG_HAS_FOO, but won’t be completely removed. > > Is that what you meant? Yes. Juergen