-
Notifications
You must be signed in to change notification settings - Fork 6
2024 How to build a new feature for the web platform
- GitHub issue: https://github.com/Igalia/webengineshackfest/issues/24
- Documentation after standardization
- How do you propose a new feature, from the very beginning, for example explainers
- At the start of the process, it's not always clear what spec the feature should go in
sideshowbarker: Let's do intros.
Valerie: Co-chair of ARIA spec, working at Igalia.
Alice: Worked on inert, working at Igalia.
Keith: Work at GitHub on the Primer design system, doing spec work to get stuff done. Done CSS (custom states), ARIA, WHATWG, OpenUI.
Luke: Work at Igalia on web platform. OpenUI, WHATWG, some W3C WGs. eg: preference media queries, invokers, showPicker.
Dominic: WHATWG stuff, working at Google.
Anne: WHATWG stuff too (HTML, XHR, etc), working at Apple.
sideshowbarker: Document what has worked and not worked in the past, and find what we can change.
sideshowbarker: Has anyone come with specific things you want to talk about?
Valerie: Crossing specification boundaries/layers, already talked about in a previous session.
Valerie: What parts of the specifying process are mysterious to you?
Vadim: I work on MDN, writing specs then writing docs (MDN). Include it this discussion?
sideshowbarker: Absolutely, that is why I titled it so. I also contribute to MDN, it is something we should be putting resources into.
Manuel (rego): How do you propose a new feature, from the very beginning, for example explainers
Andreu: (?) Not always clear at the start of the process what spec a feature belongs in, so that should be part of the process
sideshowbarker: There are steps listed in the issue, but this one before: how do you know where to go for your problem?
Andreu: Describing the problem and who you are solving it for might help that problem. Do you open issues in every possible place you think?
Dominic: You could get quick answers with a Matrix chat in terms of location. Matrix is useful for sync comms with ~0 time. Is Matrix intimidating? Should we advertise it better? That could easily answer where you should file spec issues.
?: Cultural barrier rather than technical. Painless once you are doing it for your job.
Valerie: Reminds me of 2 issues: a HTML feature request and a browser bug, both filed in the ARIA GitHub issues. We could do a better job directing where to instead of just being like "this should be a HTML issue close". All these processes are made up of people so hopefully someone will tell you where is right. A browser's Bugzilla seems more intimidating than GitHub issues.
sideshowbarker: People do find that to be unfamiliar and intimidating, also questioning why not GitHub issues. There are good reasons they use Bugzilla. WebKit uses Bugzilla not GitHub issues.
?: What are the "good reasons" to use Bugzilla?
sideshowbarker: Actually not sure, I guess "good" is wrong. Anne why does WebKit use Bugzilla?
Anne: Legacy. Did not want to erase work of previous bugs so had to migrate. WHATWG and (?) used to use Bugzilla. There is a lot of tooling built around Bugzilla for browser engines now. You can still use Bugzilla to submit changes for WebKit, as you do not want to break someone's workflow.
Luke: Migrating is hard, don't want to kill old issues. Bug trackers have many more fields than GitHub issues.
canadahonk: I like Bugzilla, it has many fields which you can edit. Great for meta bugs.
?: Me too. Bugzilla allows you to use dependent bugs. WebKit's Bugzilla is old so is missing some features.
Dominic: I hate Bugzilla but lets go back on track.
sideshowbarker: Hard to overstate the important of step 0 (describing the problem) in the process. Regularly someone enters the WHATWG Matrix with a "great solution" but they do not know what problem they are solving. WHATWG FAQ has a subsection for adding new features. Has anyone had any successful experiences with that without bursting their bubble? Are we doing that well? Do other specs have documents on where to start?
Vadim: GitHub issue forms and PR templates helps as you can structure user's feedback/use-case, but sometimes it intimidates people into not filing anything at all.
Anne: WHATWG has 2 issue templates: an issue in the spec and requesting a feature to be added. Sometimes they make it fit the solution they have in mind already, instead of thinking more broadly of the issue they ran into. People file issues and some are good ideas, but we do not have the bandwidth to do them all (and neither do the issue authors). You want people to have their say in the spec process but also want to reduce workload.
Romero: How many people here mentor or document? Can we standardise the onboarding of new people into contributing?
Valerie: Another social problem, no real process solution. People will come with this feeling that they already have a solution, so we will have to say a million times working on specs "good try but we have to start with the problem". Do your best to redirect people instead of just denying.
Alice: A solution is a discrete thing where as a problem is harder to describe and think of, you only really think of problems when you run into them.
Andreu: Not sure how much should I explain in some issues or how much context to give.
Brian: Your attention and timespan is governed by you, other people's are their own. A lot of developers are used to working on their projects where you question if you don't get a response in a few days. Large threads with many developers latching on sharing their own thoughts can happen with issues/PRs which sit open for a while.
Philip Chimento: How many people there are affects this too. How good can you put yourself in their shoes? Different people will interpret in different ways. Once a group gains a critical mass of members, it can be hard.
?: I like a lot of what is being said so many htings are weird about working in standards. maybe better onboaridng docs. I think its weird to convince people of the problem not the solution. At business, you are working on days, but in specs, it's like a many year experience. for example: Why can't we have this? Actually it's really hard to ship in a browser.
Valerie: people come across people first, not documentation. We need to know where these resources are, but talks are really ideal as an introduction because you see a person talking, it feels more familiar. Some of these things could turn into topics for talks, like "how do you identify the problem?"
Brian: Domenic Denicola had a talk... it's still a really good talk, perhaps we should find some (?) and highlight them...
Valerie: can you find those?
luke: community groups exist approaching working groups, joining matrix can be scary, but community groups, helped me get involved in standards.
dom: Where should we put these resources?
mike: page in the wiki, you can put in there. Dominics talks "how to make friends in specs", "hichhikers guides to webstandards".
Alice: write drunk, edit sober. I've read a lot of explainers when I was on the W3C TAG, so many explainers NEEDED editing, I couldn't understanding it -- so it's not explaining anything. I wrote a "how to write an explainer".
luke: on thing, it's hard to get into the write mindset. Remember to write it for someone who doesn't have any of the context you have. There is certainly a lot of contextual knowledge you have.
anne: I'm not a really big fan of explainers. Often when people write explainers they don't write the equiv text in the standard, but the standard should have the explainers. I would prefer to review the standard rather than the explainer. If the standard doesn't give an examples, it makes it hard to digest. Sometimes writing standard takes away from writing a well written standard because people looke at explainer instead of the spec text.
Andreu: For cross-org standards, (?). It is not always clear.
Vadim: I want to follow up on technical journalism background. Explainer is the best tool to get developers excited. Like Anne said, later when you read about the feature in the spec it is focused on implementers not developers.
Luke: It depends on the order in which you are doing things. For me the explainer comes first, especially with a HTML spec there is not really a introduction section unlike some W3C specs. Putting explainers on MDN via documentation. An MDN issue is required for some PRs to get merged which help with documentation. Chrome's intent to ship process could require an MDN issue, or even a PR to force documentation to be written? A spec without documentation is not that helpful.
Vadim: Requiring writing docs for MDN could be a good thing for intent to ship. I started to notice Chromium folks showing up on MDN with issues or draft PRs to do that. Not sure of the formal process.
mike: we added that to the whatwg templated
Andreu: If you're used to standards, you need to get into a different mindset for writing explainers or MDN documentation, which is not easy. It is a skillset which needs to be worked on. When I implemented structuredClone in Chromium, I think sideshowbarker tagged me in the MDN PR. I tried explaining the technical content to the PR author but even just trying to get them to understand the details was tough for me.
mike: another problem -- people get to the point of where they raise issue in issue traccker... and getting responses. how do to this well. A big anti pattern, you don't want to alienate people, you don't want to get defensive or get into arguments. I listed "how to win friends and influence people". An piece of advice is "you can't win an argument" -- if you have an argument, you will always lose, because you alienate people. You don't want to get into haggling or side tracked. You get defensive about something you have made. One thing I thought about concretely, one context where we really go out of way not to alienate someone -- it's when we are in a job interview, if they are wrong and you disagree. You don't say "you are wrong" because you want the job. You are trying to win people over to your proposal, pretend everyone is interviewing.
Aapo: I have not done standards work, but I have come to rely on this method when I realize I might be getting into a argument. If you write english in the "you" passive voice. You will read passive as if I am instructing you what to do. Using "a person" helps in this type of thing. I hope it helps. My messages read back later seem less combative.
Anne: When people write epic poems in issues it gets quite annoying. I don't have time to read it all, they want something - your standard to change in some way. Then someone else comments so the author replies again with a very long thing again. It makes spec editors skip issues as they do not want to deal with such long content. You want to be consise and make your point instead of re-explaining everything each time to each newcomer to a "debate". As a tactic, I try to ask questions when I disagree with someone to understand where they are coming from to help resolve the disagreement.
mike: I am one of those who tends to write a lot, but mostly as I prefer to write everything in one chunk instead of having several back and forths. Something nice is that we have details in GitHub issues, so I use that when I find I have written too much stuff so people can view in detail if they choose to. Satifies my need that everything is there without overwhelming spec editors.
Dominic: And foot notes.
mike: Putting together a PR is the next step.
Luke: One issue which might not be solvable as different repos have different style guides. It can get confusing when you work on spec work which crosses several specs, some things using short/long hand, HTML spec having 100 character wrap (Dominic has a tool but not sure how known it is), and more. Spreading style guides would be good, or linters could help. Although usually someone will reply to PRs to help you fix the style, but it definitely causes a learning curve for newcomers.
Anne: Style nits are the most annoying thing as a reviewer as you can do several nit comments but then it turns out the PR is wrong anyway. You can focus on what it should say and not how it says it.
Brian: That resonated with me, noticing style nits first and then later realising there are major problems with the PR. Fixing those, then adding the style problems again. I'm not sure how to handle this other than pointing people in the right direction for styling.
Nico: What kind of style rules are we talking about?
Brian: The 100 character HTML limit I have run into a bunch.
Dominic: In the CONTRIBUTING.md file there is some help. Maybe we should make some tool to do it automatically, but the hints exist in the CONTRIBUTING.md.
Alice: Get someone to look at explainers for you first, but edit first (cut out half the words).
Brian: Maybe we should add a character limit like tweets and if someone engages you get more characters (lol)
mike: With WHATWG PRs, part of the checklist is if it has WPTs. Personally I find it quite painful and procastinate on it the most. You first have to write the tests then get it reviewed in the WPT repo.
Anne: I have also had this. I think I was the person most opposed to adding WPT PRs to the checklist. I don't like writing tests. It is one of the more useful process changes WHATWG made but it has slowed down changes. But the changes we make we have to revisit less often. By writing tests we have to improve (?) the choices we make, so it creates a feedback loop. There are some recent examples with popover where it hasn't gone as well, but generally the stuff we test is pretty solid. Before we used to write stuff without tests so they did not describe reality. I agree it is painful and makes things take longer, but it is a good change. Writing a test doesn't add 10 years of confusion/tech debt.
Nico: I agree, but I find writing WPTs painful. Getting it setup is annoying. Running tests are slow. Running flexbox against Servo takes a couple of minutes. If we could somehow make the test runner and process smoother and faster that could help.
Luke: I think the act of writing the tests for implementation work is good as it handles a feedback loop. Doing a change to WPTs in a browser engine automatically makes PRs to upstream WPT which get merged when merged into browser engines. There are large surface areas where WPT cannot do coverage for, eg input UI. Partly because it is implementation defined but also partly because it is relying on platform APIs or there are no test hooks for it. Then you have to do engine specific tests which can lead to interop issues. Making the WPT test runner more capable could help. Part of the process be the closewatcher API (?) relies on the Escape key, but that does not work on eg iOS. Adding more hooks for edge-cases.
canadahonk: A problem I've had with wpt tests, sometimes the test pass in one engine but the tests don't follow the actual spec as those tests were written by the engine themselves when they implemented it against the spec.
Valerie: Maybe we should fund WPT more? Session tomorrow about a11y WPT stuff \o/
mike: Running out of time but from a contributor point of view, filing browser bugs without tests there is little possibility I would willingly choose it to implement rather than others with tests. The odds of someone working on a bug with tests is much higher than one without.
Brian: Are you saying normal people should write WPTs for browser bugs?
mike: No, when writing a spec PR when you want it implemented in browser engines. Having WPTs gives extra motivation for people to implement it.
mike: People show up and file/contribute test cases and assume people are waiting to review those. New contributors do not know you have to get reviewers. There are a lot of reviewers. The more obscure area, the less likely that the existing WPT reviewers will be prepared to review it.
Luke: GitHub will suggest assignees but I would not trust it. You can always use the Matrix channel to ask for reviewers.
Brian: Microsoft was making a WPT test writer in-browser which was much more friendly to create and submit. I thought it was really good, I saw a few presentations on it. It is difficult to setup and run WPT. Running it with a local fork of a browser is not nice either.
mike: Chromium and WebKit have Slack but not sure what criteria you need to join.
?: For Chromium you have to be in the AUTHORS file so need one patch.
Luke: WebKit is public, and you can request access to Chromium if not in the AUTHORS file.
Aapo: I used a Google Groups when working on V8 and I thought it was great.
mike: My personal experience is that I do not go there (where?) unless I have exhausted other options. I am not sure how people manage to do their first patch without doing that.
canadahonk: Mozilla has a Matrix instance which is open and used a lot.
Nico: I couldn't find channels really due to how Matrix works. Is there a list somewhere?
canadahonk: No :P