[PATCHv6,wayland-protocols] Add name event to xdg-output

Submitted by Drew DeVault on April 24, 2018, 10:07 a.m.

Details

Message ID 20180424100726.17045-1-sir@cmpwn.com
State Superseded
Headers show
Series "Add name event to xdg-output" ( rev: 8 ) in Wayland

Not browsing as part of any series.

Commit Message

Drew DeVault April 24, 2018, 10:07 a.m.
Signed-off-by: Drew DeVault <sir@cmpwn.com>
Reviewed-by: Simon Ser <contact@emersion.fr>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
---
Only change is the additional <!-- comment -->

 .../xdg-output/xdg-output-unstable-v1.xml     | 47 ++++++++++++++++++-
 1 file changed, 45 insertions(+), 2 deletions(-)

Patch hide | download patch | download mbox

diff --git a/unstable/xdg-output/xdg-output-unstable-v1.xml b/unstable/xdg-output/xdg-output-unstable-v1.xml
index 0c0c481..6eed8b0 100644
--- a/unstable/xdg-output/xdg-output-unstable-v1.xml
+++ b/unstable/xdg-output/xdg-output-unstable-v1.xml
@@ -54,7 +54,7 @@ 
     reset.
   </description>
 
-  <interface name="zxdg_output_manager_v1" version="1">
+  <interface name="zxdg_output_manager_v1" version="2">
     <description summary="manage xdg_output objects">
       A global factory interface for xdg_output objects.
     </description>
@@ -77,7 +77,7 @@ 
     </request>
   </interface>
 
-  <interface name="zxdg_output_v1" version="1">
+  <interface name="zxdg_output_v1" version="2">
     <description summary="compositor logical output region">
       An xdg_output describes part of the compositor geometry.
 
@@ -157,5 +157,48 @@ 
       </description>
     </event>
 
+    <!-- Version 2 additions -->
+    <event name="name" since="2">
+      <description summary="name of this output">
+    Many compositors will assign names to their outputs, show them to the user,
+    allow them to be configured by name, etc. The client may wish to know this
+    name as well to offer the user similar behaviors.
+
+    The naming convention is compositor defined, but limited to alphanumeric
+    characters and dashes (-). Each name is unique among all wl_output
+    globals, but if a wl_output global is destroyed the same name may be reused
+    later. The names will also remain consistent across sessions with the same
+    hardware and software configuration.                                                           
+
+    Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. However, do not
+    assume that the name is a reflection of an underlying DRM connector, X11
+    connection, etc.
+
+    The name event is sent after creating an xdg_output (see
+    xdg_output_manager.get_xdg_output). This event is only sent once per
+    xdg_output, and the name does not change over the lifetime of the wl_output
+    global.
+      </description>
+      <arg name="name" type="string" summary="output name"/>
+    </event>
+
+    <event name="description" since="2">
+      <description summary="human-readable description of this output">
+    Many compositors can produce human-readable descriptions of their outputs.
+    The client may wish to know this description as well, to communicate the
+    user for various purposes.
+
+    The description is a UTF-8 string with no convention defined for its
+    contents. Examples might include 'Foocorp 11" Display' or 'Virtual X11
+    output via :1'.
+
+    The description event is sent after creating an xdg_output (see
+    xdg_output_manager.get_xdg_output). This event is only sent once per
+    xdg_output, and the description does not change over the lifetime of the
+    wl_output global. The description is optional, and may not be sent at all.
+      </description>
+      <arg name="description" type="string" summary="output description"/>
+    </event>
+
   </interface>
 </protocol>

Comments

On Tue, 24 Apr 2018 12:07:26 +0200
Drew DeVault <sir@cmpwn.com> wrote:

> Signed-off-by: Drew DeVault <sir@cmpwn.com>
> Reviewed-by: Simon Ser <contact@emersion.fr>
> Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
> ---
> Only change is the additional <!-- comment -->

Hi,

when someone merges this patch, please do add a commit message
explaining why these events are added. See
https://cgit.freedesktop.org/wayland/wayland/tree/doc/Contributing#n21
for guidance on what to write.

Even if it seems obvious to everyone right now, it's not obvious after
5 years. I don't think the one line summary explains it.

For example, we had a long discussion about having just one event
instead of two, what that one event would mean, and yet we ended up
with two separate events (which I think is for the better). I would
expect the commit message to explain why we have two events instead of
one, since having one was the original and intuitive proposal.

Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>

I would give R-b if the commit message was there. The protocol spec
text looks good to me.


Thanks,
pq

> 
>  .../xdg-output/xdg-output-unstable-v1.xml     | 47 ++++++++++++++++++-
>  1 file changed, 45 insertions(+), 2 deletions(-)
> 
> diff --git a/unstable/xdg-output/xdg-output-unstable-v1.xml b/unstable/xdg-output/xdg-output-unstable-v1.xml
> index 0c0c481..6eed8b0 100644
> --- a/unstable/xdg-output/xdg-output-unstable-v1.xml
> +++ b/unstable/xdg-output/xdg-output-unstable-v1.xml
> @@ -54,7 +54,7 @@
>      reset.
>    </description>
>  
> -  <interface name="zxdg_output_manager_v1" version="1">
> +  <interface name="zxdg_output_manager_v1" version="2">
>      <description summary="manage xdg_output objects">
>        A global factory interface for xdg_output objects.
>      </description>
> @@ -77,7 +77,7 @@
>      </request>
>    </interface>
>  
> -  <interface name="zxdg_output_v1" version="1">
> +  <interface name="zxdg_output_v1" version="2">
>      <description summary="compositor logical output region">
>        An xdg_output describes part of the compositor geometry.
>  
> @@ -157,5 +157,48 @@
>        </description>
>      </event>
>  
> +    <!-- Version 2 additions -->
> +    <event name="name" since="2">
> +      <description summary="name of this output">
> +    Many compositors will assign names to their outputs, show them to the user,
> +    allow them to be configured by name, etc. The client may wish to know this
> +    name as well to offer the user similar behaviors.
> +
> +    The naming convention is compositor defined, but limited to alphanumeric
> +    characters and dashes (-). Each name is unique among all wl_output
> +    globals, but if a wl_output global is destroyed the same name may be reused
> +    later. The names will also remain consistent across sessions with the same
> +    hardware and software configuration.                                                           
> +
> +    Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. However, do not
> +    assume that the name is a reflection of an underlying DRM connector, X11
> +    connection, etc.
> +
> +    The name event is sent after creating an xdg_output (see
> +    xdg_output_manager.get_xdg_output). This event is only sent once per
> +    xdg_output, and the name does not change over the lifetime of the wl_output
> +    global.
> +      </description>
> +      <arg name="name" type="string" summary="output name"/>
> +    </event>
> +
> +    <event name="description" since="2">
> +      <description summary="human-readable description of this output">
> +    Many compositors can produce human-readable descriptions of their outputs.
> +    The client may wish to know this description as well, to communicate the
> +    user for various purposes.
> +
> +    The description is a UTF-8 string with no convention defined for its
> +    contents. Examples might include 'Foocorp 11" Display' or 'Virtual X11
> +    output via :1'.
> +
> +    The description event is sent after creating an xdg_output (see
> +    xdg_output_manager.get_xdg_output). This event is only sent once per
> +    xdg_output, and the description does not change over the lifetime of the
> +    wl_output global. The description is optional, and may not be sent at all.
> +      </description>
> +      <arg name="description" type="string" summary="output description"/>
> +    </event>
> +
>    </interface>
>  </protocol>
On 2018-04-26 10:49 AM, Pekka Paalanen wrote:
> when someone merges this patch, please do add a commit message
> explaining why these events are added. See
> https://cgit.freedesktop.org/wayland/wayland/tree/doc/Contributing#n21
> for guidance on what to write.
> 
> Even if it seems obvious to everyone right now, it's not obvious after
> 5 years. I don't think the one line summary explains it.
> 
> For example, we had a long discussion about having just one event
> instead of two, what that one event would mean, and yet we ended up
> with two separate events (which I think is for the better). I would
> expect the commit message to explain why we have two events instead of
> one, since having one was the original and intuitive proposal.
> 
> Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
> 
> I would give R-b if the commit message was there. The protocol spec
> text looks good to me.

I respectfully disagree. The commit message should pertain only to the
final approach, and historical information and timely commentary belongs
on the mailing list. 5 years from now, should it prove confusing,
looking up the mailing list posts will not be considerably more
difficult than looking up the commit message.

--
Drew DeVault
On Thu, 26 Apr 2018 11:46:54 +0200
Drew DeVault <sir@cmpwn.com> wrote:

> On 2018-04-26 10:49 AM, Pekka Paalanen wrote:
> > when someone merges this patch, please do add a commit message
> > explaining why these events are added. See
> > https://cgit.freedesktop.org/wayland/wayland/tree/doc/Contributing#n21
> > for guidance on what to write.
> > 
> > Even if it seems obvious to everyone right now, it's not obvious after
> > 5 years. I don't think the one line summary explains it.
> > 
> > For example, we had a long discussion about having just one event
> > instead of two, what that one event would mean, and yet we ended up
> > with two separate events (which I think is for the better). I would
> > expect the commit message to explain why we have two events instead of
> > one, since having one was the original and intuitive proposal.
> > 
> > Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
> > 
> > I would give R-b if the commit message was there. The protocol spec
> > text looks good to me.  
> 
> I respectfully disagree. The commit message should pertain only to the
> final approach, and historical information and timely commentary belongs
> on the mailing list. 5 years from now, should it prove confusing,
> looking up the mailing list posts will not be considerably more
> difficult than looking up the commit message.

A commit must always document the "why exactly this change is being
made", and here it is completely missing, even for the final approach.


Thanks,
pq
On Thu, Apr 26, 2018 at 01:20:28PM +0300, Pekka Paalanen wrote:
> On Thu, 26 Apr 2018 11:46:54 +0200
> Drew DeVault <sir@cmpwn.com> wrote:
> 
> > On 2018-04-26 10:49 AM, Pekka Paalanen wrote:
> > > when someone merges this patch, please do add a commit message
> > > explaining why these events are added. See
> > > https://cgit.freedesktop.org/wayland/wayland/tree/doc/Contributing#n21
> > > for guidance on what to write.
> > > 
> > > Even if it seems obvious to everyone right now, it's not obvious after
> > > 5 years. I don't think the one line summary explains it.
> > > 
> > > For example, we had a long discussion about having just one event
> > > instead of two, what that one event would mean, and yet we ended up
> > > with two separate events (which I think is for the better). I would
> > > expect the commit message to explain why we have two events instead of
> > > one, since having one was the original and intuitive proposal.
> > > 
> > > Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
> > > 
> > > I would give R-b if the commit message was there. The protocol spec
> > > text looks good to me.  
> > 
> > I respectfully disagree. The commit message should pertain only to the
> > final approach, and historical information and timely commentary belongs
> > on the mailing list. 5 years from now, should it prove confusing,
> > looking up the mailing list posts will not be considerably more
> > difficult than looking up the commit message.
> 
> A commit must always document the "why exactly this change is being
> made", and here it is completely missing, even for the final approach.

There should be a commit message explaining the change, yes. Sorry for
missing that when reviewing.


Jonas

> 
> 
> Thanks,
> pq



> _______________________________________________
> wayland-devel mailing list
> wayland-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel