payload: {"action":"created","issue":{"url":"https://api.github.com/repos/web-platform-tests/wpt/issues/17913","repository_url":"https://api.github.com/repos/web-platform-tests/wpt","labels_url":"https://api.github.com/repos/web-platform-tests/wpt/issues/17913/labels{/name}","comments_url":"https://api.github.com/repos/web-platform-tests/wpt/issues/17913/comments","events_url":"https://api.github.com/repos/web-platform-tests/wpt/issues/17913/events","html_url":"https://github.com/web-platform-tests/wpt/issues/17913","id":469911618,"node_id":"MDU6SXNzdWU0Njk5MTE2MTg=","number":17913,"title":" \"Common\" files are untested and poorly documented","user":{"login":"jugglinmike","id":677252,"node_id":"MDQ6VXNlcjY3NzI1Mg==","avatar_url":"https://avatars2.githubusercontent.com/u/677252?v=4","gravatar_id":"","url":"https://api.github.com/users/jugglinmike","html_url":"https://github.com/jugglinmike","followers_url":"https://api.github.com/users/jugglinmike/followers","following_url":"https://api.github.com/users/jugglinmike/following{/other_user}","gists_url":"https://api.github.com/users/jugglinmike/gists{/gist_id}","starred_url":"https://api.github.com/users/jugglinmike/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jugglinmike/subscriptions","organizations_url":"https://api.github.com/users/jugglinmike/orgs","repos_url":"https://api.github.com/users/jugglinmike/repos","events_url":"https://api.github.com/users/jugglinmike/events{/privacy}","received_events_url":"https://api.github.com/users/jugglinmike/received_events","type":"User","site_admin":false},"labels":[{"id":57148765,"node_id":"MDU6TGFiZWw1NzE0ODc2NQ==","url":"https://api.github.com/repos/web-platform-tests/wpt/labels/common","name":"common","color":"ededed","default":false},{"id":125445429,"node_id":"MDU6TGFiZWwxMjU0NDU0Mjk=","url":"https://api.github.com/repos/web-platform-tests/wpt/labels/docs","name":"docs","color":"fbca04","default":false},{"id":45230790,"node_id":"MDU6TGFiZWw0NTIzMDc5MA==","url":"https://api.github.com/repos/web-platform-tests/wpt/labels/infra","name":"infra","color":"fbca04","default":false},{"id":693964558,"node_id":"MDU6TGFiZWw2OTM5NjQ1NTg=","url":"https://api.github.com/repos/web-platform-tests/wpt/labels/priority:backlog","name":"priority:backlog","color":"ededed","default":false}],"state":"open","locked":false,"assignee":{"login":"zcorpan","id":244772,"node_id":"MDQ6VXNlcjI0NDc3Mg==","avatar_url":"https://avatars2.githubusercontent.com/u/244772?v=4","gravatar_id":"","url":"https://api.github.com/users/zcorpan","html_url":"https://github.com/zcorpan","followers_url":"https://api.github.com/users/zcorpan/followers","following_url":"https://api.github.com/users/zcorpan/following{/other_user}","gists_url":"https://api.github.com/users/zcorpan/gists{/gist_id}","starred_url":"https://api.github.com/users/zcorpan/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zcorpan/subscriptions","organizations_url":"https://api.github.com/users/zcorpan/orgs","repos_url":"https://api.github.com/users/zcorpan/repos","events_url":"https://api.github.com/users/zcorpan/events{/privacy}","received_events_url":"https://api.github.com/users/zcorpan/received_events","type":"User","site_admin":false},"assignees":[{"login":"zcorpan","id":244772,"node_id":"MDQ6VXNlcjI0NDc3Mg==","avatar_url":"https://avatars2.githubusercontent.com/u/244772?v=4","gravatar_id":"","url":"https://api.github.com/users/zcorpan","html_url":"https://github.com/zcorpan","followers_url":"https://api.github.com/users/zcorpan/followers","following_url":"https://api.github.com/users/zcorpan/following{/other_user}","gists_url":"https://api.github.com/users/zcorpan/gists{/gist_id}","starred_url":"https://api.github.com/users/zcorpan/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zcorpan/subscriptions","organizations_url":"https://api.github.com/users/zcorpan/orgs","repos_url":"https://api.github.com/users/zcorpan/repos","events_url":"https://api.github.com/users/zcorpan/events{/privacy}","received_events_url":"https://api.github.com/users/zcorpan/received_events","type":"User","site_admin":false}],"milestone":null,"comments":13,"created_at":"2019-07-18T17:59:44Z","updated_at":"2019-10-04T14:32:21Z","closed_at":null,"author_association":"CONTRIBUTOR","body":"The files in [the `common/` directory](https://github.com/web-platform-tests/wpt/tree/c1e9969044fed6bf1bd9d0a5cb1630845cde70fb/common) are intended to be used by tests across all of WPT. This makes documenting their usage and verifying their correctness very important. Today, they are inconsistently documented and uniformly untested. Some are unused, and others are used so sparingly as to not justify their presence in `common/`.\r\n\r\nHere's what I think we should do about that:\r\n\r\n- define a convention for documenting each file\r\n- document each file\r\n- extend the documentation website build process to consume that pattern and generate a page for the common code\r\n- extend the lint tool to require documentation\r\n- write tests for the code (likely stored in a new subdirectory of `infrastructure/`)\r\n- remove files that are no longer used\r\n- relocate files that are used sparingly\r\n\r\n/cc @zqzhang @deniak @gsnedders (the current [suggested reviewers for `common/`](https://github.com/web-platform-tests/wpt/blob/c1e9969044fed6bf1bd9d0a5cb1630845cde70fb/common/META.yml))\r\n\r\n<details>\r\n  <summary>Documentation references to <code>common/</code> directory</summary>\r\n\r\n- `README.md`:\r\n\r\n  > Various resources that tests depend on are in `common`, `images`, and\r\n  > `fonts`.\r\n\r\n- `docs/writing-tests/general-guidelines.md`:\r\n\r\n  > Various support files are available in in the `/common/` and `/media/`\r\n  > directories (web-platform-tests) and `/support/` (in css/). Reusing\r\n  > existing resources is encouraged where possible, as is adding\r\n  > generally useful files to these common areas rather than to specific\r\n  > test suites.\r\n\r\n- `docs/writing-tests/testharness.md`\r\n\r\n  > There are two utility scripts in that work well together with variants,\r\n  > `/common/subset-tests.js` and `/common/subset-tests-by-key.js`, where\r\n  > a test that would otherwise have too many tests to be useful can be\r\n  > split up in ranges of subtests. For example:\r\n\r\n</details>\r\n\r\n<details>\r\n  <summary>Reference count for each file in <code>common/</code></summary>\r\n\r\n    $ for f in $(ls common/ | grep -v headers); do echo $(git grep \"common/$f\" | wc -l) common/$f; done | sort -n\r\n    0 common/form-submission.py\r\n    0 common/META.yml\r\n    0 common/sleep.py\r\n    1 common/canvas-frame.css\r\n    1 common/canvas-index.css\r\n    1 common/canvas-spec.css\r\n    1 common/css-red.txt\r\n    1 common/echo.py\r\n    1 common/entities.json\r\n    2 common/arrays.js\r\n    2 common/object-association.js\r\n    3 common/stringifiers.js\r\n    4 common/dummy.xml\r\n    5 common/redirect-opt-in.py\r\n    6 common/domain-setter.sub.html\r\n    6 common/namespaces.js\r\n    6 common/subset-tests-by-key.js\r\n    8 common/dummy.xhtml\r\n    8 common/text-plain.txt\r\n    10 common/test-setting-immutable-prototype.js\r\n    15 common/slow.py\r\n    17 common/PrefixedPostMessage.js\r\n    28 common/PrefixedLocalStorage.js\r\n    31 common/performance-timeline-utils.js\r\n    57 common/redirect.py\r\n    142 common/media.js\r\n    143 common/subset-tests.js\r\n    183 common/worklet-reftest.js\r\n    191 common/blank.html\r\n    204 common/utils.js\r\n    390 common/get-host-info.sub.js\r\n    488 common/reftest-wait.js\r\n    902 common/canvas-tests.css\r\n    2209 common/security-features\r\n    2482 common/canvas-tests.js\r\n\r\n</details>"},"comment":{"url":"https://api.github.com/repos/web-platform-tests/wpt/issues/comments/538422296","html_url":"https://github.com/web-platform-tests/wpt/issues/17913#issuecomment-538422296","issue_url":"https://api.github.com/repos/web-platform-tests/wpt/issues/17913","id":538422296,"node_id":"MDEyOklzc3VlQ29tbWVudDUzODQyMjI5Ng==","user":{"login":"zcorpan","id":244772,"node_id":"MDQ6VXNlcjI0NDc3Mg==","avatar_url":"https://avatars2.githubusercontent.com/u/244772?v=4","gravatar_id":"","url":"https://api.github.com/users/zcorpan","html_url":"https://github.com/zcorpan","followers_url":"https://api.github.com/users/zcorpan/followers","following_url":"https://api.github.com/users/zcorpan/following{/other_user}","gists_url":"https://api.github.com/users/zcorpan/gists{/gist_id}","starred_url":"https://api.github.com/users/zcorpan/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zcorpan/subscriptions","organizations_url":"https://api.github.com/users/zcorpan/orgs","repos_url":"https://api.github.com/users/zcorpan/repos","events_url":"https://api.github.com/users/zcorpan/events{/privacy}","received_events_url":"https://api.github.com/users/zcorpan/received_events","type":"User","site_admin":false},"created_at":"2019-10-04T14:32:21Z","updated_at":"2019-10-04T14:32:21Z","author_association":"MEMBER","body":"When trying to implement the above reorg I changed my mind a bit and left some files as top-level.\r\n\r\nI'm also not certain yet how/where to best write documentation for these.\r\n\r\nhttps://github.com/web-platform-tests/wpt/pull/19514"}}
other: {"actor":{"display_login":"zcorpan"}}