Re: [webkit-dev] webkit-dev Digest, Vol 208, Issue 5

[Elliott Williams via webkit-dev]

> On Sep 29, 2022, at 18:54, Ryosuke Niwa via webkit-dev 
>  wrote:
> 
>> Introduction.md is definitely not the right place for much of this, so that 
>> leaves the GitHub Wiki (which, I might point out, was never discussed as a 
>> community either, I started it so we could discuss migrating Trac in the 
>> future, but it’s never been officially “blessed") or Brandon’s DocC 
>> documentation repo as the two proposed choices
> 
> 
> I don’t think those two are only solutions. Namely, I suggest we create a new 
> documentation repository using a cross-platform tool written in Python, Ruby, 
> or Perl such that contributors don’t need to learn yet another programming 
> language or runtime thereof.

For what it’s worth: I just tried out the Linux workflow, and was honestly 
surprised at how easy it was, compared to my experiments with Swift on Linux 
years ago. I had to download and extract Swift from swift.org 
, and run an apt-get command listed on the download page. 
Then, `make preview` built the docs in less than a second and started a local 
server.

Perhaps “install Swift” is too much of a barrier for access. But if we’re okay 
with asking contributors to do that, building the docs locally appears to be 
very simple.
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] webkit-dev Digest, Vol 208, Issue 5

[Ryosuke Niwa via webkit-dev]

> On Sep 29, 2022, at 5:26 PM, Jonathan Bedard  wrote:
> 
>> On Sep 29, 2022, at 4:28 PM, Ryosuke Niwa  wrote:
>> 
>>> On Sep 29, 2022, at 11:48 AM, Jonathan Bedard via webkit-dev 
>>> mailto:webkit-dev@lists.webkit.org>> wrote:
>>> 
> On Sep 20, 2022, at 1:52 PM, Brent Fulgham  > wrote:
> 
>> On Sep 20, 2022, at 1:16 AM, Ryosuke Niwa via webkit-dev 
>> mailto:webkit-dev@lists.webkit.org>> wrote:
>> 
>>> On Sep 19, 2022, at 2:28 PM, Brandon Stewart via webkit-dev 
>>> mailto:webkit-dev@lists.webkit.org> 
>>> >> >> wrote:
>>> 
>>> Documentation is an important part of any open source project, 
>>> especially for a larger project like WebKit. Being able to ramp up 
>>> during the onboarding process, reading up on architectural decisions, 
>>> and learning how to perform common procedures are all features the 
>>> documentation should tackle. WebKit has a large set of documentation 
>>> already, but it is scattered around a wide range of platforms (Trac, 
>>> GitHub Wiki, markdown files in the code, Git commits, etc...), and some 
>>> of the information is out of date.
>> 
>> This ultimately feels like this situation:
>> https://xkcd.com/927/  > >
>> 
>> I?ve been working on 
>> https://github.com/WebKit/WebKit/blob/main/Introduction.md 
>>  
>> > > for the 
>> past couple of years, and I?d would have preferred to have a 
>> collaboration rather than a competition here.
>>> 
>>> Right now we have:
>>> https://github.com/WebKit/WebKit/wiki 
>>> 
>>> https://trac.webkit.org/ 
>>> https://webkit.org/getting-started/ 
>>> https://github.com/WebKit/WebKit/blob/main/Introduction.md 
>>> 
>>> 
>>> Brandon’s solution is designed to replace the first 2, and he has buy in 
>>> from the maintainers of the first two, when his solution is deployed, our 
>>> existing wikis will die.
>> 
>> I don’t think there is a community wide buy-in to replace either 
>> documentations / tools at this point. I don’t think people who happen to 
>> maintain the infrastructure get to have unilateral say on which tools will 
>> get supported or deprecated.
> 
> This is an effort to get community wide buy-in.

Right, and I’m pointing out that as of this moment, there isn’t community wide 
buy-in.

>>> I have tested this on macOS and Linux and have found it works extremely 
>>> well. (Windows should be able to use WSL2 at the moment, while a few 
>>> remaining issues get sorted out). The only dependency for this project 
>>> is a recent installation of Swift.
>> 
>> Previously, we?ve rejected Swift as a general purpose programming 
>> languages in WebKit: 
>> https://lists.webkit.org/pipermail/webkit-dev/2014-July/026722.html 
>>  
>> > > 
>> other than to allow existing C++ code to call into Swift API: 
>> https://lists.webkit.org/pipermail/webkit-dev/2021-June/031882.html 
>>  
>> > >
>> 
>> As such, I don?t think we should require having a functional Swift 
>> toolchain as a requirement for contributing to WebKit or its 
>> documentations either.
> 
> DocC is not a requirement to use or participate in this work. It?s simply 
> a ?port? of the documentation that works for our needs. If others prefer 
> to ?build? output documentation from Markdown using a different tool set, 
> they are welcome to contribute those build commands and instructions.
 
>>> 
>>> Something else worth calling out here is that contributing DocC compatible 
>>> markdown is similar to contributions to 
>>> https://github.com/WebKit/WebKit/tree/main/Websites/webkit.org 
>>>  that 
>>> eventually end up on webkit.org , except that we have a 
>>> nice path to automating DocC deployment (either to GitHub pages or a 
>>> webkit.org  property). We pretty frequently use 
>>> technologies in our services we don’t intend 

Re: [webkit-dev] webkit-dev Digest, Vol 208, Issue 5

[Jonathan Bedard via webkit-dev]

> On Sep 29, 2022, at 4:28 PM, Ryosuke Niwa  wrote:
> 
> 
> 
>> On Sep 29, 2022, at 11:48 AM, Jonathan Bedard via webkit-dev 
>> mailto:webkit-dev@lists.webkit.org>> wrote:
>> 
>> 
 On Sep 20, 2022, at 1:52 PM, Brent Fulgham >>> > wrote:
 
> On Sep 20, 2022, at 1:16 AM, Ryosuke Niwa via webkit-dev 
> mailto:webkit-dev@lists.webkit.org>> wrote:
> 
>> On Sep 19, 2022, at 2:28 PM, Brandon Stewart via webkit-dev 
>> mailto:webkit-dev@lists.webkit.org> 
>> > wrote:
>> 
>> Documentation is an important part of any open source project, 
>> especially for a larger project like WebKit. Being able to ramp up 
>> during the onboarding process, reading up on architectural decisions, 
>> and learning how to perform common procedures are all features the 
>> documentation should tackle. WebKit has a large set of documentation 
>> already, but it is scattered around a wide range of platforms (Trac, 
>> GitHub Wiki, markdown files in the code, Git commits, etc...), and some 
>> of the information is out of date.
> 
> This ultimately feels like this situation:
> https://xkcd.com/927/ 
> 
> I?ve been working on 
> https://github.com/WebKit/WebKit/blob/main/Introduction.md 
>  for the past 
> couple of years, and I?d would have preferred to have a collaboration 
> rather than a competition here.
>> 
>> Right now we have:
>> https://github.com/WebKit/WebKit/wiki
>> https://trac.webkit.org/
>> https://webkit.org/getting-started/
>> https://github.com/WebKit/WebKit/blob/main/Introduction.md
>> 
>> Brandon’s solution is designed to replace the first 2, and he has buy in 
>> from the maintainers of the first two, when his solution is deployed, our 
>> existing wikis will die.
> 
> I don’t think there is a community wide buy-in to replace either 
> documentations / tools at this point. I don’t think people who happen to 
> maintain the infrastructure get to have unilateral say on which tools will 
> get supported or deprecated.

This is an effort to get community wide buy-in.

But it’s also worth noting that services (Trac, in particular) aren’t free to 
maintain, while we don’t have anything forcing action on Trac yet, it is likely 
we will be forced to do something in the future. And folks maintaining 
infrastructure might be forced to unilaterally make decisions in the future if 
the community hasn’t already made a decision. My point in bringing up the 
deprecation of our other two Wiki sources is that I don’t think we’re in the 
“competing standards” situation referenced in the xkcd comic.

> 
>> I have tested this on macOS and Linux and have found it works extremely 
>> well. (Windows should be able to use WSL2 at the moment, while a few 
>> remaining issues get sorted out). The only dependency for this project 
>> is a recent installation of Swift.
> 
> Previously, we?ve rejected Swift as a general purpose programming 
> languages in WebKit: 
> https://lists.webkit.org/pipermail/webkit-dev/2014-July/026722.html 
>  
> other than to allow existing C++ code to call into Swift API: 
> https://lists.webkit.org/pipermail/webkit-dev/2021-June/031882.html 
> 
> 
> As such, I don?t think we should require having a functional Swift 
> toolchain as a requirement for contributing to WebKit or its 
> documentations either.
 
 DocC is not a requirement to use or participate in this work. It?s simply 
 a ?port? of the documentation that works for our needs. If others prefer 
 to ?build? output documentation from Markdown using a different tool set, 
 they are welcome to contribute those build commands and instructions.
>>> 
>> 
>> Something else worth calling out here is that contributing DocC compatible 
>> markdown is similar to contributions to 
>> https://github.com/WebKit/WebKit/tree/main/Websites/webkit.org that 
>> eventually end up on webkit.org , except that we have a 
>> nice path to automating DocC deployment (either to GitHub pages or a 
>> webkit.org  property). We pretty frequently use 
>> technologies in our services we don’t intend contributors to regularly run 
>> at desk.
> 
> That sounds strictly worse than contributing to Trac wiki or Github wiki, or 
> even Introduction.md then. Why are we making contribution to documentation 
> harder than it already is?

I wouldn’t describe it as “worse”, it’s different. It’s not obvious (to me, at 
least) that the sort of web-UI editing that GitHub’s Wiki and Trac’s Wiki 
provides is actually desirable. We have to restrict who can edit these sorts of 
wiki (in GitHub, in 

Re: [webkit-dev] webkit-dev Digest, Vol 208, Issue 5

[Ryosuke Niwa via webkit-dev]

> On Sep 29, 2022, at 11:48 AM, Jonathan Bedard via webkit-dev 
>  wrote:
> 
> 
>>> On Sep 20, 2022, at 1:52 PM, Brent Fulgham  wrote:
>>> 
 On Sep 20, 2022, at 1:16 AM, Ryosuke Niwa via webkit-dev 
  wrote:
 
> On Sep 19, 2022, at 2:28 PM, Brandon Stewart via webkit-dev 
> mailto:webkit-dev@lists.webkit.org>> wrote:
> 
> Documentation is an important part of any open source project, especially 
> for a larger project like WebKit. Being able to ramp up during the 
> onboarding process, reading up on architectural decisions, and learning 
> how to perform common procedures are all features the documentation 
> should tackle. WebKit has a large set of documentation already, but it is 
> scattered around a wide range of platforms (Trac, GitHub Wiki, markdown 
> files in the code, Git commits, etc...), and some of the information is 
> out of date.
 
 This ultimately feels like this situation:
 https://xkcd.com/927/ 
 
 I?ve been working on 
 https://github.com/WebKit/WebKit/blob/main/Introduction.md 
  for the past 
 couple of years, and I?d would have preferred to have a collaboration 
 rather than a competition here.
> 
> Right now we have:
> https://github.com/WebKit/WebKit/wiki 
> https://trac.webkit.org/ 
> https://webkit.org/getting-started/ 
> https://github.com/WebKit/WebKit/blob/main/Introduction.md 
> 
> 
> Brandon’s solution is designed to replace the first 2, and he has buy in from 
> the maintainers of the first two, when his solution is deployed, our existing 
> wikis will die.

I don’t think there is a community wide buy-in to replace either documentations 
/ tools at this point. I don’t think people who happen to maintain the 
infrastructure get to have unilateral say on which tools will get supported or 
deprecated.

> I have tested this on macOS and Linux and have found it works extremely 
> well. (Windows should be able to use WSL2 at the moment, while a few 
> remaining issues get sorted out). The only dependency for this project is 
> a recent installation of Swift.
 
 Previously, we?ve rejected Swift as a general purpose programming 
 languages in WebKit: 
 https://lists.webkit.org/pipermail/webkit-dev/2014-July/026722.html 
  
 other than to allow existing C++ code to call into Swift API: 
 https://lists.webkit.org/pipermail/webkit-dev/2021-June/031882.html 
 
 
 As such, I don?t think we should require having a functional Swift 
 toolchain as a requirement for contributing to WebKit or its 
 documentations either.
>>> 
>>> DocC is not a requirement to use or participate in this work. It?s simply a 
>>> ?port? of the documentation that works for our needs. If others prefer to 
>>> ?build? output documentation from Markdown using a different tool set, they 
>>> are welcome to contribute those build commands and instructions.
>> 
> 
> Something else worth calling out here is that contributing DocC compatible 
> markdown is similar to contributions to 
> https://github.com/WebKit/WebKit/tree/main/Websites/webkit.org 
>  that 
> eventually end up on webkit.org , except that we have a 
> nice path to automating DocC deployment (either to GitHub pages or a 
> webkit.org  property). We pretty frequently use 
> technologies in our services we don’t intend contributors to regularly run at 
> desk.

That sounds strictly worse than contributing to Trac wiki or Github wiki, or 
even Introduction.md then. Why are we making contribution to documentation 
harder than it already is?

>>> Our goal is to accumulate all relevant and open source documentation 
>>> related to WebKit in this repository so that we can generate searchable 
>>> documentation. We would also like this to be accessible and searchable from 
>>> the web.
>> 
>> I suggest that we don?t migrate contents of https://trac.webkit.org/wiki 
>>  to whatever new documentation we create.  
>> Most information on that wiki is extremely outdated or outright wrong.
> 
> That very much depends on the section of Trac’s Wiki you’re looking at. 
> https://trac.webkit.org/wiki/TestExpectations 
>  is ancient, but pretty 
> accurate, for example. Same for 
> https://trac.webkit.org/wiki/LayoutTestsSearchPath 
>  (despite the references 
> to ancient MacOS versions). We need to do some 

Re: [webkit-dev] webkit-dev Digest, Vol 208, Issue 5

[Jonathan Bedard via webkit-dev]

>> On Sep 20, 2022, at 1:52 PM, Brent Fulgham  wrote:
>> 
>>> On Sep 20, 2022, at 1:16 AM, Ryosuke Niwa via webkit-dev 
>>>  wrote:
>>> 
 On Sep 19, 2022, at 2:28 PM, Brandon Stewart via webkit-dev 
 mailto:webkit-dev@lists.webkit.org>> wrote:
 
 Documentation is an important part of any open source project, especially 
 for a larger project like WebKit. Being able to ramp up during the 
 onboarding process, reading up on architectural decisions, and learning 
 how to perform common procedures are all features the documentation should 
 tackle. WebKit has a large set of documentation already, but it is 
 scattered around a wide range of platforms (Trac, GitHub Wiki, markdown 
 files in the code, Git commits, etc...), and some of the information is 
 out of date.
>>> 
>>> This ultimately feels like this situation:
>>> https://xkcd.com/927/ 
>>> 
>>> I?ve been working on 
>>> https://github.com/WebKit/WebKit/blob/main/Introduction.md 
>>>  for the past 
>>> couple of years, and I?d would have preferred to have a collaboration 
>>> rather than a competition here.

Right now we have:
https://github.com/WebKit/WebKit/wiki
https://trac.webkit.org/
https://webkit.org/getting-started/
https://github.com/WebKit/WebKit/blob/main/Introduction.md

Brandon’s solution is designed to replace the first 2, and he has buy in from 
the maintainers of the first two, when his solution is deployed, our existing 
wikis will die.

I think https://webkit.org/getting-started/ and 
https://github.com/WebKit/WebKit/blob/main/Introduction.md are both designed to 
be too narrow to be a dumping ground for all our documentation. 

>> 
>> Ryosuke: Your document is outstanding, and is a large part of the content we 
>> pulled into the current repo. I don?t think we view this as a competition; 
>> rather we are trying to host a collection of Markdown content in a common 
>> repo that does not have to be pulled and synced with WebKit source and 
>> tests. This provides a lower bar for people interested in contributing 
>> documentation as they do not have to download and sync Gigabytes of WebKit 
>> code to write documentation.
> 
> Who are these people who want to contribute to WebKit?s documentation yet 
> doesn?t already have a clone of WebKit repository? I just can?t think of 
> people who would fit that description.

Mixing together documentation commits with commits which change product code is 
not great, it makes tracking down regressions more difficult for the same 
reasons we like monotonically increasing commit numbers. I think this is a 
trade off well worth it for Introduction.md, but not for something like 
https://github.com/WebKit/WebKit/wiki/Source-Control#identifiers.

It’s also worth calling out that Jon Davis and I have had a similar discussion 
about https://github.com/WebKit/WebKit/tree/main/Websites/webkit.org, that’s 
probably something we shouldn’t be committing to the same repository with all 
our product code.

> 
> (2) is particularly important because many people who are new to WebKit often 
> don?t know what they don?t know. This is why, for example, memory management 
> section appears towards the beginning of the document and the information 
> about adding IDL files is immediately followed by the discussion of JS 
> wrapper lifecycles. With these information now split across multiple files, 
> it?s easy for people to miss out on critical information. In the ideal world, 
> people won?t be adding or editing IDL files before they understood how JS 
> wrappers are managed because not knowing the latter is a sure way of 
> introducing subtle GC bugs.
> 
 A few months ago, I started working on a new documentation solution based 
 on the DocC documentation framework.
>>> 
>>> Was there any discussion as to which documentation framework should be 
>>> used? I?m personally not familiar with DooC documentation, and I?m  
>>> surprised that such an important decision was made unilaterally without 
>>> much discussion on webkit-dev.
>> 
>> We discussed this internally, but today?s message is the first discussion on 
>> this repository that we?ve opened on the webkit-dev mailing list. We wanted 
>> to convince ourselves that the tool worked well, and was easy to use, and 
>> could produce documentation output that would be useful for Apple engineers. 
>> That is not the only intended audience for this work, but is the origin of 
>> this effort which we wanted to make available to others to use and 
>> contribute to.
>> 
>> Those of us who have worked on WebKit for some time can easily remember the 
>> many discussions over the years about documentation efforts of various 
>> types. Lots of people have strong opinions, but few ever contribute despite 
>> their opinions of the right way for the work to be done. You are obviously 
>> part of the group that has contributed heavily, so I am