{"id":455,"date":"2016-06-19T14:22:55","date_gmt":"2016-06-19T12:22:55","guid":{"rendered":"https:\/\/blogs.gentoo.org\/mgorny\/?p=455"},"modified":"2016-06-19T15:24:16","modified_gmt":"2016-06-19T13:24:16","slug":"on-good-metadata-xml-maintainer-descriptions","status":"publish","type":"post","link":"https:\/\/blogs.gentoo.org\/mgorny\/2016\/06\/19\/on-good-metadata-xml-maintainer-descriptions\/","title":{"rendered":"On\u00a0good metadata.xml maintainer descriptions"},"content":{"rendered":"

Since GLEP 67<\/a> was approved, bug assignment became easier. However, there were still many metadata.xml files which made this suboptimal. Today, I have fixed most of\u00a0them and\u00a0I would like to provide this short guide on how to write good metadata.xml files.<\/p>\n

<\/p>\n

The\u00a0bug assignment procedure<\/h2>\n

To understand the\u00a0points that I am going to make, let’s take a\u00a0look at how bug assignment happens these days. Assuming a\u00a0typical case of bug related to a\u00a0specific package (or\u00a0multiple packages), the\u00a0procedure for assigning the\u00a0bug involves, for each package:<\/p>\n

    \n
  1. reading all <maintainer\/><\/kbd> elements from the\u00a0package’s metadata.xml file, in\u00a0order<\/em>;<\/li>\n
  2. filtering the\u00a0maintainers based on\u00a0restrict=\"\"<\/kbd> attributes (if\u00a0any);<\/li>\n
  3. filtering and\u00a0reordering the\u00a0maintainers based on\u00a0<description\/><\/kbd>s;<\/li>\n
  4. assigning the\u00a0bug to the\u00a0first maintainer left, and\u00a0CC-ing the\u00a0remaining ones.<\/li>\n<\/ol>\n

    I think the procedure is quite clear. Since we no longer have <herd\/><\/kbd> elements with special meaning applied to them, the\u00a0assignment is mostly influenced by\u00a0maintainer occurrence order. Restrictions can be used to limit maintenance to specific versions of a\u00a0package, and\u00a0descriptions to apply special rules and\u00a0conditions.<\/p>\n

    Now, for semi-automatic bug assignment, only the\u00a0first or\u00a0the\u00a0first two of the\u00a0above steps can be clearly automated. Applying restrictions correctly requires understanding whether the\u00a0bug can be correctly isolated to a\u00a0specific version range, as some bugs (e.g. invalid metadata) may require being fixed in\u00a0multiple versions of the\u00a0package. Descriptions, in\u00a0turn, are written for humans and\u00a0require a\u00a0human to interpret them.<\/p>\n

    What belongs in a\u00a0good description<\/h2>\n

    Now, many of\u00a0existing metadata.xml files had either useless or\u00a0even problematic maintainer descriptions. This is a\u00a0problem since it increases time needed for bug assignment, and\u00a0makes automation harder. Common examples of\u00a0bad maintainer descriptions include:<\/p>\n

      \n
    1. Assign bugs to him<\/q>; CC him on bugs<\/q> \u2014 this is either redundant or\u00a0contradictory. Ensure that maintainers are listed in\u00a0correct order, and\u00a0bugs will be assigned correctly. Those descriptions only force a\u00a0human to read them and\u00a0possibly change the\u00a0automatically determined order.<\/li>\n
    2. Primary maintainer<\/q>; proxied maintainer<\/q> \u2014 this is some information but it does not change anything. If the\u00a0maintainer comes first, he’s obviously the\u00a0primary one. If the\u00a0maintainer has non-Gentoo e-mail and\u00a0there are proxies listed, he’s obviously proxied. And\u00a0even if we did not know that, does it change anything? Again, we are forced to read information we do not need.<\/li>\n<\/ol>\n

      Good maintainer descriptions include:<\/p>\n

        \n
      1. Upstream; CC on\u00a0bugs concerning upstream<\/q>, Only CC on bugs that involve USE=”d3d9″<\/q> \u2014 useful information that influences bug assignment;<\/li>\n
      2. Feel free to fix\/update<\/q>, All modifications to this package must be approved by the wxwidgets herd.<\/q> \u2014 important information for other developers.<\/li>\n<\/ol>\n

        So, before adding another description, please answer two questions: will the\u00a0information benefit anyone? Can’t it be expressed in machine-readable form?<\/p>\n

        Proxy-maintained packages<\/h2>\n

        Since a\u00a0lot of the\u00a0affected packages are maintained by\u00a0proxied maintainers, I’d like to explicitly point out how proxy-maintained packages are to be described. This overlaps with the\u00a0current Proxy maintainers<\/a> team policy.<\/p>\n

        For proxy-maintained packages, the\u00a0maintainers should be listed in the\u00a0following order:<\/p>\n

          \n
        1. actual package maintainers, in\u00a0appropriate order \u2014 including developers maintaining or co-maintaining the\u00a0package, proxied maintainers and\u00a0Gentoo projects;<\/li>\n
        2. developer proxies, preferably described as such \u2014 i.e. developers who do not actively maintain the\u00a0package but only proxy for the\u00a0maintainers;<\/li>\n
        3. Proxy-maintainers project \u2014 serving as the\u00a0generic fallback proxy.<\/li>\n<\/ol>\n

          I would like to put more emphasis on the\u00a0key point here \u2014 the\u00a0maintainers should be listed in an\u00a0order making it clearly possible to distinguish packages that are maintained only by a\u00a0proxied maintainer (with developers acting as\u00a0proxies) from packages that are maintained by\u00a0Gentoo developers and\u00a0co-maintained by a\u00a0proxied maintainer.<\/p>\n

          Third-party repositories (overlays)<\/h2>\n

          As a\u00a0last point, I would like to point out the\u00a0special case of unofficial Gentoo repositories. Unlike the\u00a0core repositories, metadata.xml files can not be fully trusted there. The\u00a0reason for this is quite simple \u2014 many users copy (fork) packages from Gentoo along with metadata.xml files. If we were to trust those files \u2014 we would be assigning overlay bugs to Gentoo developers maintaining the\u00a0original package!<\/p>\n

          For this reason, all bugs on unofficial repository packages are assigned to the\u00a0repository owners.<\/p>\n","protected":false},"excerpt":{"rendered":"

          Since GLEP 67 was approved, bug assignment became easier. However, there were still many metadata.xml files which made this suboptimal. Today, I have fixed most of\u00a0them and\u00a0I would like to provide this short guide on how to write good metadata.xml files.<\/p>\n","protected":false},"author":137,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"jetpack_publicize_message":"","jetpack_is_tweetstorm":false,"jetpack_publicize_feature_enabled":true},"categories":[3],"tags":[],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/blogs.gentoo.org\/mgorny\/wp-json\/wp\/v2\/posts\/455"}],"collection":[{"href":"https:\/\/blogs.gentoo.org\/mgorny\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.gentoo.org\/mgorny\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.gentoo.org\/mgorny\/wp-json\/wp\/v2\/users\/137"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.gentoo.org\/mgorny\/wp-json\/wp\/v2\/comments?post=455"}],"version-history":[{"count":10,"href":"https:\/\/blogs.gentoo.org\/mgorny\/wp-json\/wp\/v2\/posts\/455\/revisions"}],"predecessor-version":[{"id":465,"href":"https:\/\/blogs.gentoo.org\/mgorny\/wp-json\/wp\/v2\/posts\/455\/revisions\/465"}],"wp:attachment":[{"href":"https:\/\/blogs.gentoo.org\/mgorny\/wp-json\/wp\/v2\/media?parent=455"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.gentoo.org\/mgorny\/wp-json\/wp\/v2\/categories?post=455"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.gentoo.org\/mgorny\/wp-json\/wp\/v2\/tags?post=455"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}