Skip to content

Conversation

marcoscaceres
Copy link
Contributor

@marcoscaceres marcoscaceres commented Sep 18, 2025

closes #38

This pull request adds new documentation guidance to the index.bs file, advising spec authors to prefer existing task sources rather than creating new ones, unless there is a clear, spec-driven reason. This helps improve interoperability, predictability, and performance scheduling across the platform.

Guidance on task source usage:

  • Added a new section recommending the use of generic or preexisting task sources (such as the DOM manipulation, user interaction, networking, navigation, and rendering task sources) when queuing tasks, instead of minting new task sources without a strong, testable need.
  • Provided examples and rationale for when a new task source might be justified, such as when isolation from generic sources is required for correct feature behavior.
  • Encouraged the use of HTML's wrapper algorithms (queue a global task, queue an element task) and advised against specifying a particular event loop unless necessary.

Preview | Diff

Copy link

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds new documentation guidance for spec authors on task source usage, emphasizing the preference for existing task sources over creating new ones. This guidance aims to improve interoperability, predictability, and performance scheduling across the web platform.

  • Added a new section recommending the use of existing generic task sources
  • Provided clear criteria for when creating new task sources is justified
  • Encouraged use of HTML's wrapper algorithms for task queuing

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

Copy link

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.


Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

marcoscaceres and others added 2 commits September 18, 2025 11:59
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
@alice
Copy link
Contributor

alice commented Sep 18, 2025

Apologies for the drive-by comment, and this comment applies as much to a number of other principles which have been added in the last few years as it does to this, but:

We wrote a style guide for TAG design principles which includes this guidance:

When writing guidance, begin with your main point. Follow up with brief reasoning, clarifications and caveats in later paragraphs.

(emphasis added)

As an example, I think this guidance should begin with (some version of) the sentence "Use the generic or preexisting task sources whenever possible", rather than with an explanation of background with no indication of where in the text the actual guidance will be given.

marcoscaceres and others added 3 commits September 23, 2025 12:44
Co-authored-by: Martin Thomson <mt@lowentropy.net>
Co-authored-by: Martin Thomson <mt@lowentropy.net>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Guidance on re-using/creating task sources
3 participants