[webkit-dev] WebKit Tree Closure - Revised Time Window

[Chris Gibb via webkit-dev]

WebKit Tree Closure - Revised Time Window
What: WebKit tree closure
When: 11pm PT 2/24/2024 until 7am PT 2/25/2024
Impact
Affected services:
github.com/webkit/webkit
The default (main) branch of WebKit will be closed during the above time 
window. It will not be possible to commit changes to this branch during the 
specified time period. Pull requests and EWS will be unaffected.  Merge-queue 
labels may still be added to pull requests. They will not be processed until 
the tree is reopened.


Chris Gibb
Production Services Engineer
Apple
Internet Technologies and User Privacy
One Apple Park Way
Cupertino, CA 95014, USA
cgi...@apple.com

This email and any attachments may contain confidential information intended 
only for the recipient(s) named above. Any other distribution, forwarding, 
copying or disclosure of this message is strictly prohibited. If you have 
received this email in error, please notify me immediately by telephone or 
return email, and delete this message from your system.

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Tree Closure

[Jonathan Bedard via webkit-dev]

This tree closure has been canceled. ‘main’ will remain open for commits for 
the duration of 2/23 and 2/24.
Thank you for your patience!

Jonathan Bedard
WebKit Continuous Integration

> What: WebKit tree closure
> When: 8pm PT 2/23/2024 until 12pm PT 2/24/2024
> 
> Impact
> Affected services:
> github.com/webkit/webkit
> What: WebKit tree closure
> The default (main) branch of WebKit will be closed during the above time 
> window. It will not be possible to commit changes to this branch during the 
> specified time period. Pull requests and EWS will be unaffected. Merge-queue 
> labels may still be added to pull requests. They will not be processed until 
> the tree is reopened.


___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] WebKit Tree Closure

[Chris Gibb via webkit-dev]

What: WebKit tree closure
When: 8pm PT 2/23/2024 until 12pm PT 2/24/2024
Impact
Affected services:
github.com/webkit/webkit
The default (main) branch of WebKit will be closed during the above time 
window. It will not be possible to commit changes to this branch during the 
specified time period. Pull requests and EWS will be unaffected. Merge-queue 
labels may still be added to pull requests. They will not be processed until 
the tree is reopened.


Chris Gibb
Production Services Engineer
Apple
Internet Technologies and User Privacy
One Apple Park Way
Cupertino, CA 95014, USA
cgi...@apple.com

This email and any attachments may contain confidential information intended 
only for the recipient(s) named above. Any other distribution, forwarding, 
copying or disclosure of this message is strictly prohibited. If you have 
received this email in error, please notify me immediately by telephone or 
return email, and delete this message from your system.

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] webkit-unassigned

[Michael Catanzaro via webkit-dev]

On Mon, Dec 18 2023 at 09:58:14 PM +00:00:00, Alexey Proskuryakov 
 wrote:
Are you thinking of scraping Bugzilla? No plans to further limit 
public access at all (we do have some rate limiting already though, 
to protect service availability). I don't think that "it's in 
principle possible to notice a misplaced comment" is equivalent to 
"let's maintain a way to have every misplaced comment delivered to 
the mailbox of anyone who cares to collect those".


Not me personally.

Or if there is a similar way to follow all public activity that 
irreversibly emails everything out, then I don't know about it.


Hm, maybe not. I assumed there was, but can't find settings for it in 
Bugzilla. Maybe I was wrong.



___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] webkit-unassigned

[Alexey Proskuryakov via webkit-dev]

> 18 дек. 2023 г., в 1:44 PM, Michael Catanzaro  
> написал(а):
> 
> On Mon, Dec 18 2023 at 09:16:21 PM +00:00:00, Alexey Proskuryakov 
>  wrote:
>> Same thing - limiting the ability to trivially watch for security bugs that 
>> are initially filed in a wrong component,
> 
> You can currently follow all public activity on the Bugzilla. Are you 
> planning to limit that too?

Are you thinking of scraping Bugzilla? No plans to further limit public access 
at all (we do have some rate limiting already though, to protect service 
availability). I don't think that "it's in principle possible to notice a 
misplaced comment" is equivalent to "let's maintain a way to have every 
misplaced comment delivered to the mailbox of anyone who cares to collect 
those".

Or if there is a similar way to follow all public activity that irreversibly 
emails everything out, then I don't know about it.

- Alexey


___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] webkit-unassigned

[Michael Catanzaro via webkit-dev]

On Mon, Dec 18 2023 at 09:16:21 PM +00:00:00, Alexey Proskuryakov 
 wrote:
Same thing - limiting the ability to trivially watch for security 
bugs that are initially filed in a wrong component,


You can currently follow all public activity on the Bugzilla. Are you 
planning to limit that too?



___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] webkit-unassigned

[Alexey Proskuryakov via webkit-dev]

> 18 дек. 2023 г., в 1:11 PM, Michael Catanzaro via webkit-dev 
>  написал(а):
> 
> On Mon, Dec 18 2023 at 06:07:48 PM +00:00:00, Alexey Proskuryakov via 
> webkit-dev  wrote:
>> I'm still inclined to break the scenario of watching webkit-unassigned. What 
>> do others think?
> 
> I don't think there's any need to disable the ability to watch the Bugzilla 
> account? It shouldn't give anybody access to anything they don't already have 
> permission to see, so what's the point?

Same thing - limiting the ability to trivially watch for security bugs that are 
initially filed in a wrong component, or accidental comments that expose 
something and need to be hidden.

The alternative would be to periodically verify who is watching the account, 
which I don't think is practical.

- Alexey

> Turning off the public mailing list seems good.
> 
> Michael
> 
> 
> ___
> webkit-dev mailing list
> webkit-dev@lists.webkit.org
> https://lists.webkit.org/mailman/listinfo/webkit-dev


___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] webkit-unassigned

[Michael Catanzaro via webkit-dev]

On Mon, Dec 18 2023 at 06:07:48 PM +00:00:00, Alexey Proskuryakov via 
webkit-dev  wrote:
I'm still inclined to break the scenario of watching 
webkit-unassigned. What do others think?


I don't think there's any need to disable the ability to watch the 
Bugzilla account? It shouldn't give anybody access to anything they 
don't already have permission to see, so what's the point?


Turning off the public mailing list seems good.

Michael


___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] webkit-unassigned

[Alexey Proskuryakov via webkit-dev]

There isn't a lot of difference between unassigned bugs, and those that are 
assigned to people who don't read their bugmail for various reasons. If you 
want to get a decent subset of bugs that aren't being worked on, but not all, 
perhaps a query like this would work for you, 
https://bugs.webkit.org/buglist.cgi?bug_status=UNCONFIRMED_status=NEW_status=ASSIGNED_status=REOPENED=1d=Now=assigned_to=substring_format=advanced=unassigned
 ? This can even go into RSS, to track what's already been read.

Bugs that were filed a while ago and get updates is another query to 
potentially follow, which would have interesting updates and exclude bugs that 
are just opened for PR purposes.

I'm still inclined to break the scenario of watching webkit-unassigned. What do 
others think?

- Alexey

15 дек. 2023 г., в 5:43 PM, Fujii Hironori  
написал(а):

The user watching feature doesn't expose comments that you don't have access to 
the bug.
I'd like to notice that someone commented to unassigned bugs. I don't have to 
check bugs assigned to a developer.

On Sat, Dec 16, 2023 at 8:04 AM Alexey Proskuryakov mailto:a...@webkit.org> > wrote:

My approach would be to also disable the ability to watch the account, for the 
same reason of reducing exposure of accidental postings.

Would you mind sharing your use case? Bugs assigned to webkit-unassigned are 
not a very well defined set of bugs, so perhaps there is another solution that 
works.

- Alexey

15 дек. 2023 г., в 2:25 PM, Fujii Hironori via webkit-dev 
mailto:webkit-dev@lists.webkit.org> > написал(а):


I check it every day. Can I receive the same mails by setting my user watching 
to webkit-unassig...@lists.webkit.org 
<mailto:webkit-unassig...@lists.webkit.org> ?

On Sat, Dec 16, 2023 at 7:12 AM Alexey Proskuryakov via webkit-dev 
mailto:webkit-dev@lists.webkit.org> > wrote:
Hello,

Does anybody make use of the webkit-unassigned mailing list? I'd like to 
disable it, to reduce exposure of spam and accidental postings.

- Alexey
___
webkit-dev mailing list
webkit-dev@lists.webkit.org <mailto:webkit-dev@lists.webkit.org> 
https://lists.webkit.org/mailman/listinfo/webkit-dev 
<https://lists.webkit.org/mailman/listinfo/webkit-dev> 
___
webkit-dev mailing list
webkit-dev@lists.webkit.org <mailto:webkit-dev@lists.webkit.org> 
https://lists.webkit.org/mailman/listinfo/webkit-dev 
<https://lists.webkit.org/mailman/listinfo/webkit-dev> 


___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] webkit-unassigned

[Fujii Hironori via webkit-dev]

The user watching feature doesn't expose comments that you don't have
access to the bug.
I'd like to notice that someone commented to unassigned bugs. I don't have
to check bugs assigned to a developer.

On Sat, Dec 16, 2023 at 8:04 AM Alexey Proskuryakov  wrote:

>
> My approach would be to also disable the ability to watch the account, for
> the same reason of reducing exposure of accidental postings.
>
> Would you mind sharing your use case? Bugs assigned to webkit-unassigned
> are not a very well defined set of bugs, so perhaps there is another
> solution that works.
>
> - Alexey
>
> 15 дек. 2023 г., в 2:25 PM, Fujii Hironori via webkit-dev <
> webkit-dev@lists.webkit.org> написал(а):
>
> I check it every day. Can I receive the same mails by setting my user
> watching to webkit-unassig...@lists.webkit.org?
>
> On Sat, Dec 16, 2023 at 7:12 AM Alexey Proskuryakov via webkit-dev <
> webkit-dev@lists.webkit.org> wrote:
>
>> Hello,
>>
>> Does anybody make use of the webkit-unassigned mailing list? I'd like to
>> disable it, to reduce exposure of spam and accidental postings.
>>
>> - Alexey
>> ___
>> webkit-dev mailing list
>> webkit-dev@lists.webkit.org
>> https://lists.webkit.org/mailman/listinfo/webkit-dev
>>
> ___________
> webkit-dev mailing list
> webkit-dev@lists.webkit.org
> https://lists.webkit.org/mailman/listinfo/webkit-dev
>
>
>
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] webkit-unassigned

[Alexey Proskuryakov via webkit-dev]

My approach would be to also disable the ability to watch the account, for the 
same reason of reducing exposure of accidental postings.

Would you mind sharing your use case? Bugs assigned to webkit-unassigned are 
not a very well defined set of bugs, so perhaps there is another solution that 
works.

- Alexey

15 дек. 2023 г., в 2:25 PM, Fujii Hironori via webkit-dev 
 написал(а):

I check it every day. Can I receive the same mails by setting my user watching 
to webkit-unassig...@lists.webkit.org 
<mailto:webkit-unassig...@lists.webkit.org> ?

On Sat, Dec 16, 2023 at 7:12 AM Alexey Proskuryakov via webkit-dev 
mailto:webkit-dev@lists.webkit.org> > wrote:
Hello,

Does anybody make use of the webkit-unassigned mailing list? I'd like to 
disable it, to reduce exposure of spam and accidental postings.

- Alexey
___
webkit-dev mailing list
webkit-dev@lists.webkit.org <mailto:webkit-dev@lists.webkit.org> 
https://lists.webkit.org/mailman/listinfo/webkit-dev 
<https://lists.webkit.org/mailman/listinfo/webkit-dev> 
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] webkit-unassigned

[Fujii Hironori via webkit-dev]

I check it every day. Can I receive the same mails by setting my user
watching to webkit-unassig...@lists.webkit.org?

On Sat, Dec 16, 2023 at 7:12 AM Alexey Proskuryakov via webkit-dev <
webkit-dev@lists.webkit.org> wrote:

> Hello,
>
> Does anybody make use of the webkit-unassigned mailing list? I'd like to
> disable it, to reduce exposure of spam and accidental postings.
>
> - Alexey
> ___
> webkit-dev mailing list
> webkit-dev@lists.webkit.org
> https://lists.webkit.org/mailman/listinfo/webkit-dev
>
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] webkit-unassigned

[Alexey Proskuryakov via webkit-dev]

Hello,

Does anybody make use of the webkit-unassigned mailing list? I'd like to 
disable it, to reduce exposure of spam and accidental postings.

- Alexey
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Simon Fraser via webkit-dev]

> On Mar 9, 2023, at 10:48 AM, Brandon Stewart via webkit-dev 
>  wrote:
> 
> Hello,
> 
> Sorry for the delay on the documentation update.
> 
> For getting the documentation system online, we were trying to settle on a 
> subdomain.
> 
> What would people prefer we use as the official documentation location:
> (1) docs.webkit.org
> (2) developer.webkit.org
> (3) documentation.webkit.org

Make both 1) and 3) work, choose one as the canonical one and have the other 
redirect. Minor preference for docs.webkit.org  as the 
canonical one.

Simon

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Carlos Alberto Lopez Perez via webkit-dev]

On 09/03/2023 19:48, Brandon Stewart via webkit-dev wrote:
> What would people prefer we use as the official documentation location:
> (1) docs.webkit.org
> (2) developer.webkit.org
> (3) documentation.webkit.org
> (4) Other
+1 for docs.webkit.org (shorter is better)
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Adrian Perez de Castro via webkit-dev]

Hi all,

On Thu, 09 Mar 2023 10:48:27 -0800 Brandon Stewart via webkit-dev 
 wrote:
 
> Sorry for the delay on the documentation update.
> For getting the documentation system online, we were trying to settle on a 
> subdomain.

Looking forward to have the documentation online ^_^
 
> What would people prefer we use as the official documentation location:
> (1) docs.webkit.org
> (2) developer.webkit.org
> (3) documentation.webkit.org
> (4) Other
> 
> Could you please reply to this e-mail indicating which origin you would 
> prefer?

One vote more for (1) because it's shorter top type, but (3) could do as well.

Cheers,
—Adrián


signature.asc
Description: PGP signature
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Vitor Ribeiro Roriz via webkit-dev]

I prefer (1) as well!On 12 Mar 2023, at 16:07, Brent Fulgham via webkit-dev  wrote:I prefer (1)!On Mar 9, 2023, at 5:54 PM, Kirsling, Ross via webkit-dev  wrote:







I’d vote for (1) since it’s easy to type!
 
Thanks,
Ross
 

From: Ryosuke Niwa via webkit-dev 
Reply-To: Ryosuke Niwa 
Date: Friday, March 10, 2023 at 6:41 AM
To: Brandon Stewart 
Cc: Ling Ho via webkit-dev 
Subject: Re: [webkit-dev] WebKit Documentation


 


 






On Mar 9, 2023, at 10:48 AM, Brandon Stewart via webkit-dev  wrote:




 



Sorry for the delay on the documentation update.


 


For getting the documentation system online, we were trying to settle on a subdomain.


 


What would people prefer we use as the official documentation location:


(1) docs.webkit.org


(2) developer.webkit.org


(3) documentation.webkit.org






 


(1) or (3) seems good.


 


- R. Niwa


 






On Feb 28, 2023, at 12:39 AM, dpino via webkit-dev  wrote:



On 9/20/22 05:28, Brandon Stewart via webkit-dev wrote:

Hi WebKit Developers,
 
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.
 
A few months ago, I started working on a new documentation solution based on the DocC documentation framework. This provides an easy way to add and edit documentation through markdown files. I have already ported a large section of Trac, all of the GitHub Wiki, and all of the non third party markdown files in the code over to this platform. 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.
 
You can already download the documentation and preview it locally, but we are looking to publish it online for easy viewing. We were looking to get your feedback if we would want to publish the documentation on GitHub Pages or webkit.org.
 
The documentation source can be found at https://github.com/webkit/documentation.
 
- Brandon
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

H,
It has been more than 5 months since this new documentation repository was announced and as far as I know it hasn't been published yet. Is there any news when this site will be publicly available?
Right now in Igalia we need to publish some information publicly and we were discussing where it's the right place to put it.
  * WebKit Documentation (https://github.com/webkit/documentation.git),
 IMHO it doesn't make sense because the information needs to be public.
  * Trac (https://trac.webkit.org/wiki),
 since WebKit Documentation hasn't been published yet, the fact is that we have been updating Trac pages in the last months.
  * WebKit GitHub Wiki (https://github.com/WebKit/WebKit/wiki),
 it seems like the best candidate. It says that new documentation should live there instead of being added to Trac. But on the other hand when WebKit Documentation was announced some people advocated for keep using the GH Wiki but that idea was discarded. It
 seems like WebKit GitHub Wiki is were new documents should be published until WebKit Documentation site is not available? Please confirm whether this assumption is correct or not.
--
Diego

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev



 

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev


 




___webkit-dev mailing listwebkit-dev@lists.webkit.orghttps://lists.webkit.org/mailman/listinfo/webkit-dev___webkit-dev mailing listwebkit-dev@lists.webkit.orghttps://lists.webkit.org/mailman/listinfo/webkit-dev___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Brent Fulgham via webkit-dev]

I prefer (1)!On Mar 9, 2023, at 5:54 PM, Kirsling, Ross via webkit-dev  wrote:







I’d vote for (1) since it’s easy to type!
 
Thanks,
Ross
 

From: Ryosuke Niwa via webkit-dev 
Reply-To: Ryosuke Niwa 
Date: Friday, March 10, 2023 at 6:41 AM
To: Brandon Stewart 
Cc: Ling Ho via webkit-dev 
Subject: Re: [webkit-dev] WebKit Documentation


 


 






On Mar 9, 2023, at 10:48 AM, Brandon Stewart via webkit-dev  wrote:




 



Sorry for the delay on the documentation update.


 


For getting the documentation system online, we were trying to settle on a subdomain.


 


What would people prefer we use as the official documentation location:


(1) docs.webkit.org


(2) developer.webkit.org


(3) documentation.webkit.org






 


(1) or (3) seems good.


 


- R. Niwa


 






On Feb 28, 2023, at 12:39 AM, dpino via webkit-dev  wrote:



On 9/20/22 05:28, Brandon Stewart via webkit-dev wrote:

Hi WebKit Developers,
 
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.
 
A few months ago, I started working on a new documentation solution based on the DocC documentation framework. This provides an easy way to add and edit documentation through markdown files. I have already ported a large section of Trac, all of the GitHub Wiki, and all of the non third party markdown files in the code over to this platform. 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.
 
You can already download the documentation and preview it locally, but we are looking to publish it online for easy viewing. We were looking to get your feedback if we would want to publish the documentation on GitHub Pages or webkit.org.
 
The documentation source can be found at https://github.com/webkit/documentation.
 
- Brandon
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

H,
It has been more than 5 months since this new documentation repository was announced and as far as I know it hasn't been published yet. Is there any news when this site will be publicly available?
Right now in Igalia we need to publish some information publicly and we were discussing where it's the right place to put it.
  * WebKit Documentation (https://github.com/webkit/documentation.git),
 IMHO it doesn't make sense because the information needs to be public.
  * Trac (https://trac.webkit.org/wiki),
 since WebKit Documentation hasn't been published yet, the fact is that we have been updating Trac pages in the last months.
  * WebKit GitHub Wiki (https://github.com/WebKit/WebKit/wiki),
 it seems like the best candidate. It says that new documentation should live there instead of being added to Trac. But on the other hand when WebKit Documentation was announced some people advocated for keep using the GH Wiki but that idea was discarded. It
 seems like WebKit GitHub Wiki is were new documents should be published until WebKit Documentation site is not available? Please confirm whether this assumption is correct or not.
--
Diego

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev



 

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev


 




___webkit-dev mailing listwebkit-dev@lists.webkit.orghttps://lists.webkit.org/mailman/listinfo/webkit-dev___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Kirsling, Ross via webkit-dev]

I’d vote for (1) since it’s easy to type!

Thanks,
Ross

From: Ryosuke Niwa via webkit-dev 
Reply-To: Ryosuke Niwa 
Date: Friday, March 10, 2023 at 6:41 AM
To: Brandon Stewart 
Cc: Ling Ho via webkit-dev 
Subject: Re: [webkit-dev] WebKit Documentation




On Mar 9, 2023, at 10:48 AM, Brandon Stewart via webkit-dev 
 wrote:

Sorry for the delay on the documentation update.

For getting the documentation system online, we were trying to settle on a 
subdomain.

What would people prefer we use as the official documentation location:
(1) docs.webkit.org
(2) developer.webkit.org
(3) documentation.webkit.org

(1) or (3) seems good.

- R. Niwa

On Feb 28, 2023, at 12:39 AM, dpino via webkit-dev 
 wrote:

On 9/20/22 05:28, Brandon Stewart via webkit-dev wrote:

Hi WebKit Developers,



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.



A few months ago, I started working on a new documentation solution based on 
the DocC documentation framework. This provides an easy way to add and edit 
documentation through markdown files. I have already ported a large section of 
Trac, all of the GitHub Wiki, and all of the non third party markdown files in 
the code over to this platform. 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.



You can already download the documentation and preview it locally, but we are 
looking to publish it online for easy viewing. We were looking to get your 
feedback if we would want to publish the documentation on GitHub Pages or 
webkit.org.



The documentation source can be found at 
https://github.com/webkit/documentation<https://github.com/webkit/documentation>.



- Brandon

___

webkit-dev mailing list

webkit-dev@lists.webkit.org<mailto:webkit-dev@lists.webkit.org>

https://lists.webkit.org/mailman/listinfo/webkit-dev<https://lists.webkit.org/mailman/listinfo/webkit-dev>

H,

It has been more than 5 months since this new documentation repository was 
announced and as far as I know it hasn't been published yet. Is there any news 
when this site will be publicly available?

Right now in Igalia we need to publish some information publicly and we were 
discussing where it's the right place to put it.

  * WebKit Documentation 
(https://github.com/webkit/documentation.git<https://github.com/webkit/documentation.git>),
 IMHO it doesn't make sense because the information needs to be public.

  * Trac (https://trac.webkit.org/wiki<https://trac.webkit.org/wiki>), since 
WebKit Documentation hasn't been published yet, the fact is that we have been 
updating Trac pages in the last months.

  * WebKit GitHub Wiki 
(https://github.com/WebKit/WebKit/wiki<https://github.com/WebKit/WebKit/wiki>), 
it seems like the best candidate. It says that new documentation should live 
there instead of being added to Trac. But on the other hand when WebKit 
Documentation was announced some people advocated for keep using the GH Wiki 
but that idea was discarded. It seems like WebKit GitHub Wiki is were new 
documents should be published until WebKit Documentation site is not available? 
Please confirm whether this assumption is correct or not.

--

Diego
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev<https://lists.webkit.org/mailman/listinfo/webkit-dev>

_______
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev<https://lists.webkit.org/mailman/listinfo/webkit-dev>

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Ryosuke Niwa via webkit-dev]

> On Mar 9, 2023, at 10:48 AM, Brandon Stewart via webkit-dev 
>  wrote:
> 
> Sorry for the delay on the documentation update.
> 
> For getting the documentation system online, we were trying to settle on a 
> subdomain.
> 
> What would people prefer we use as the official documentation location:
> (1) docs.webkit.org
> (2) developer.webkit.org
> (3) documentation.webkit.org

(1) or (3) seems good.

- R. Niwa

>> On Feb 28, 2023, at 12:39 AM, dpino via webkit-dev 
>>  wrote:
>> On 9/20/22 05:28, Brandon Stewart via webkit-dev wrote:
>> 
>>> Hi WebKit Developers,
>>> 
>>> 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.
>>> 
>>> A few months ago, I started working on a new documentation solution based 
>>> on the DocC documentation framework. This provides an easy way to add and 
>>> edit documentation through markdown files. I have already ported a large 
>>> section of Trac, all of the GitHub Wiki, and all of the non third party 
>>> markdown files in the code over to this platform. 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.
>>> 
>>> You can already download the documentation and preview it locally, but we 
>>> are looking to publish it online for easy viewing. We were looking to get 
>>> your feedback if we would want to publish the documentation on GitHub Pages 
>>> or webkit.org.
>>> 
>>> The documentation source can be found at 
>>> https://github.com/webkit/documentation.
>>> 
>>> - Brandon
>>> ___
>>> webkit-dev mailing list
>>> webkit-dev@lists.webkit.org <mailto:webkit-dev@lists.webkit.org>
>>> https://lists.webkit.org/mailman/listinfo/webkit-dev
>> H,
>> 
>> It has been more than 5 months since this new documentation repository was 
>> announced and as far as I know it hasn't been published yet. Is there any 
>> news when this site will be publicly available?
>> 
>> Right now in Igalia we need to publish some information publicly and we were 
>> discussing where it's the right place to put it.
>> 
>>   * WebKit Documentation (https://github.com/webkit/documentation.git), IMHO 
>> it doesn't make sense because the information needs to be public.
>> 
>>   * Trac (https://trac.webkit.org/wiki), since WebKit Documentation hasn't 
>> been published yet, the fact is that we have been updating Trac pages in the 
>> last months.
>> 
>>   * WebKit GitHub Wiki (https://github.com/WebKit/WebKit/wiki), it seems 
>> like the best candidate. It says that new documentation should live there 
>> instead of being added to Trac. But on the other hand when WebKit 
>> Documentation was announced some people advocated for keep using the GH Wiki 
>> but that idea was discarded. It seems like WebKit GitHub Wiki is were new 
>> documents should be published until WebKit Documentation site is not 
>> available? Please confirm whether this assumption is correct or not.
>> 
>> --
>> 
>> Diego
>> 
>> ___
>> webkit-dev mailing list
>> webkit-dev@lists.webkit.org
>> https://lists.webkit.org/mailman/listinfo/webkit-dev
> 
> ___
> webkit-dev mailing list
> webkit-dev@lists.webkit.org
> https://lists.webkit.org/mailman/listinfo/webkit-dev

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] WebKit Documentation using MkDocs

[Brandon Stewart via webkit-dev]

Hello,

I got feedback that people would prefer not to add Swift as a requirement for 
building the documentation. Since WebKit relies heavily on Python for large 
parts of its tooling, I decided to port it over to a popular Python 
documentation system MkDocs.

This provides a few benefits over the previous solution:
- Improved search across documents
- Python based
- Easier to setup and install (just run pip3 install mkdocs-material)
- Works great across macOS, Linux, and Windows

The repo is located at the same location: 
https://github.com/WebKit/Documentation

I have been continuing to port over a large amount of the relevant 
documentation from Trac, but if you notice anything missing please feel free to 
add it.

Feedback welcome.

Thanks,
Brandon___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Brandon Stewart via webkit-dev]

Hello,

Sorry for the delay on the documentation update.

For getting the documentation system online, we were trying to settle on a 
subdomain.

What would people prefer we use as the official documentation location:
(1) docs.webkit.org
(2) developer.webkit.org
(3) documentation.webkit.org
(4) Other

Could you please reply to this e-mail indicating which origin you would prefer?

Thanks,
Brandon

> On Feb 28, 2023, at 12:39 AM, dpino via webkit-dev 
>  wrote:
> 
> 
> 
> On 9/20/22 05:28, Brandon Stewart via webkit-dev wrote:
>> Hi WebKit Developers,
>> 
>> 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.
>> 
>> A few months ago, I started working on a new documentation solution based on 
>> the DocC documentation framework. This provides an easy way to add and edit 
>> documentation through markdown files. I have already ported a large section 
>> of Trac, all of the GitHub Wiki, and all of the non third party markdown 
>> files in the code over to this platform. 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.
>> 
>> You can already download the documentation and preview it locally, but we 
>> are looking to publish it online for easy viewing. We were looking to get 
>> your feedback if we would want to publish the documentation on GitHub Pages 
>> or webkit.org.
>> 
>> The documentation source can be found at 
>> https://github.com/webkit/documentation.
>> 
>> - Brandon
>> ___
>> webkit-dev mailing list
>> webkit-dev@lists.webkit.org <mailto:webkit-dev@lists.webkit.org>
>> https://lists.webkit.org/mailman/listinfo/webkit-dev
> H,
> 
> It has been more than 5 months since this new documentation repository was 
> announced and as far as I know it hasn't been published yet. Is there any 
> news when this site will be publicly available?
> 
> Right now in Igalia we need to publish some information publicly and we were 
> discussing where it's the right place to put it.
> 
>   * WebKit Documentation (https://github.com/webkit/documentation.git), IMHO 
> it doesn't make sense because the information needs to be public.
> 
>   * Trac (https://trac.webkit.org/wiki), since WebKit Documentation hasn't 
> been published yet, the fact is that we have been updating Trac pages in the 
> last months.
> 
>   * WebKit GitHub Wiki (https://github.com/WebKit/WebKit/wiki), it seems like 
> the best candidate. It says that new documentation should live there instead 
> of being added to Trac. But on the other hand when WebKit Documentation was 
> announced some people advocated for keep using the GH Wiki but that idea was 
> discarded. It seems like WebKit GitHub Wiki is were new documents should be 
> published until WebKit Documentation site is not available? Please confirm 
> whether this assumption is correct or not.
> 
> --
> 
> Diego
> 
> ___
> webkit-dev mailing list
> webkit-dev@lists.webkit.org
> https://lists.webkit.org/mailman/listinfo/webkit-dev

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[dpino via webkit-dev]

On 9/20/22 05:28, Brandon Stewart via webkit-dev wrote: 

> Hi WebKit Developers,
> 
> 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.
> 
> A few months ago, I started working on a new documentation solution based on 
> the DocC documentation framework. This provides an easy way to add and edit 
> documentation through markdown files. I have already ported a large section 
> of Trac, all of the GitHub Wiki, and all of the non third party markdown 
> files in the code over to this platform. 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.
> 
> You can already download the documentation and preview it locally, but we are 
> looking to publish it online for easy viewing. We were looking to get your 
> feedback if we would want to publish the documentation on GitHub Pages or 
> webkit.org.
> 
> The documentation source can be found at 
> https://github.com/webkit/documentation.
> 
> - Brandon
> ___
> webkit-dev mailing list
> webkit-dev@lists.webkit.org
> https://lists.webkit.org/mailman/listinfo/webkit-dev

H, 

It has been more than 5 months since this new documentation repository
was announced and as far as I know it hasn't been published yet. Is
there any news when this site will be publicly available? 

Right now in Igalia we need to publish some information publicly and we
were discussing where it's the right place to put it. 

  * WebKit Documentation (https://github.com/webkit/documentation.git),
IMHO it doesn't make sense because the information needs to be public. 

  * Trac (https://trac.webkit.org/wiki), since WebKit Documentation
hasn't been published yet, the fact is that we have been updating Trac
pages in the last months. 

  * WebKit GitHub Wiki (https://github.com/WebKit/WebKit/wiki), it seems
like the best candidate. It says that new documentation should live
there instead of being added to Trac. But on the other hand when WebKit
Documentation was announced some people advocated for keep using the GH
Wiki but that idea was discarded. It seems like WebKit GitHub Wiki is
were new documents should be published until WebKit Documentation site
is not available? Please confirm whether this assumption is correct or
not. 

-- 

Diego___
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

[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 

Re: [webkit-dev] WebKit Documentation

[Ryosuke Niwa via webkit-dev]

> On Sep 21, 2022, at 6:50 AM, Michael Catanzaro  wrote:
> 
> On Tue, Sep 20 2022 at 08:03:12 PM -0700, Ryosuke Niwa via webkit-dev 
>  wrote:
>> (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.
> 
> I didn't know any of this info about JS wrapper lifecycle until I read about 
> it in Introduction.md a couple months ago. It really does need to be very 
> prominent or developers won't find it. That said, I think we can find a way 
> to do this without keeping it all in one single page.

Yeah, I’m sure there are ways to make it prominent without putting all the 
information into a single md file. But we need to come up with a way to do that.

- R. Niwa

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Michael Catanzaro via webkit-dev]

On Tue, Sep 20 2022 at 08:03:12 PM -0700, Ryosuke Niwa via webkit-dev 
 wrote:
(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.


I didn't know any of this info about JS wrapper lifecycle until I read 
about it in Introduction.md a couple months ago. It really does need to 
be very prominent or developers won't find it. That said, I think we 
can find a way to do this without keeping it all in one single page.



___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Ryosuke Niwa 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.
> 
> 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.

There was a reason behind why the entire Introduction.md was written as a 
single markdown file though. Namely:
Reader can look up unknown terms right away in the same page using browsers’ 
find feature
Let reader be aware of things they are unaware of.

(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 sad that you do not seem to 
> like our approach.

Right, it’s why I wrote Introduction.md in the first place.

>>> I have already ported a large section of Trac, all of the GitHub Wiki, and 
>>> all of the non third party markdown files in the code over to this platform.
>> 
>> I’m not certain if there is a community wide support that this is the right 
>> tool to migrate all our documentations. I for one certainly object to the 
>> use of DooC as the primary documentation tool.
> 
> DocC is one way of processing the Markdown content in this repo, and one that 
> works well with Xcode since it creates output that matches Apple 
> documentation style, and an output archive that can be consumed and used 
> within Xcode search features.
> 
> There is nothing stopping an interested party using any of the other 
> available Markdown-to-HTML tools to process the data in a way they prefer, 
> much like WebKit sources can be built by Xcode, Visual Studio, and Make.

Okay but then which variant of 

Re: [webkit-dev] WebKit Documentation

[Brent Fulgham via webkit-dev]

> 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.

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.
> 
>> 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 sad that you do not seem to 
like our approach.

> 
>> I have already ported a large section of Trac, all of the GitHub Wiki, and 
>> all of the non third party markdown files in the code over to this platform.
> 
> I’m not certain if there is a community wide support that this is the right 
> tool to migrate all our documentations. I for one certainly object to the use 
> of DooC as the primary documentation tool.

DocC is one way of processing the Markdown content in this repo, and one that 
works well with Xcode since it creates output that matches Apple documentation 
style, and an output archive that can be consumed and used within Xcode search 
features.

There is nothing stopping an interested party using any of the other available 
Markdown-to-HTML tools to process the data in a way they prefer, much like 
WebKit sources can be built by Xcode, Visual Studio, and Make.


>> 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.

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.

Thanks,

-Brent

___
webkit-dev mailing list
webkit-dev@lists.webkit.org

Re: [webkit-dev] WebKit Documentation

[Ryosuke Niwa via webkit-dev]

> On Sep 20, 2022, at 6:04 AM, Michael Catanzaro  wrote:
> 
> On Tue, Sep 20 2022 at 01:16:53 AM -0700, Ryosuke Niwa via webkit-dev 
>  wrote:
>> 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.
> 
> This Introduction.md is great work (I've learned a lot from it), but it's 
> also getting pretty long for a single document. At least, it significantly 
> exceeds my attention span. We could present this same info better if we split 
> it into multiple pages.

Yeah, I agree. I wanted to keep the document searchable; putting them all in a 
single document lets us use browser’s “find” function. GitHub wiki pages are 
searchable so splitting into multiple pages isn’t an issue there.

- R. Niwa

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Michael Catanzaro via webkit-dev]

On Tue, Sep 20 2022 at 01:16:53 AM -0700, Ryosuke Niwa via webkit-dev 
 wrote:
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.


This Introduction.md is great work (I've learned a lot from it), but 
it's also getting pretty long for a single document. At least, it 
significantly exceeds my attention span. We could present this same 
info better if we split it into multiple pages.



___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Konstantin Tokarev via webkit-dev]

> Why not double-down on the GitHub wiki? It's very easy to learn to use,
> and there are edit buttons everywhere so there is no "distance" between
> the docs and the ability to edit them. The easier it is to edit docs,
> the better we'll do at keeping them up to date.
> 
> I like Markdown, and am OK with editing Markdown files wherever they
> live, but it's not very likely that I would install Swift and figure
> out how to build a new project to to see what the result looks like.
> With GitHub, we can easily preview results live to ensure we're not
> messing anything up.

Also, Markdown is not the only format supported by GitHub. It's also possible to
use AsciiDoc, POD, reStructuredText, or any other format listed in [1] in any
file of main repository or in wiki, and it will be rendered to HTML when 
browsing
online.

[1] https://github.com/github/markup/blob/master/README.md#markups

-- Regards,
Konstantin
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Ryosuke Niwa via webkit-dev]

> On Sep 19, 2022, at 2:58 PM, Michael Catanzaro via webkit-dev 
>  wrote:
> 
> Why not double-down on the GitHub wiki? It's very easy to learn to use, and 
> there are edit buttons everywhere so there is no "distance" between the docs 
> and the ability to edit them. The easier it is to edit docs, the better we'll 
> do at keeping them up to date.

One drawback of wiki is that changes won’t be code reviewed. I find that the 
much of the existing WebKit documentations are filled with outdated, 
inaccurate, and/or incomplete information, and a part of the reason is because 
no formal review is done unlike our code. At least in my experience working on 
https://github.com/WebKit/WebKit/blob/main/Introduction.md 
, I find that code 
review to be generally helpful.

> I like Markdown, and am OK with editing Markdown files wherever they live, 
> but it's not very likely that I would install Swift and figure out how to 
> build a new project to to see what the result looks like. With GitHub, we can 
> easily preview results live to ensure we're not messing anything up.

I totally agree. In order for this new documentation effort to be successful, 
contribution needs be as simple & straight forward as possible.

- R. Niwa

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Ryosuke Niwa via webkit-dev]

> On Sep 19, 2022, at 2:28 PM, Brandon Stewart via webkit-dev 
>  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.

> 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.

> I have already ported a large section of Trac, all of the GitHub Wiki, and 
> all of the non third party markdown files in the code over to this platform.

I’m not certain if there is a community wide support that this is the right 
tool to migrate all our documentations. I for one certainly object to the use 
of DooC as the primary documentation tool.

> 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.

- R. Niwa

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Ryosuke Niwa via webkit-dev]

> On Sep 19, 2022, at 4:48 PM, Fujii Hironori via webkit-dev 
>  wrote:
> 
> Why not double-down on WebKit Git repository?
> The closer the document is to the source code, the easier to keep them 
> up-to-date.
> We can modify both the source code and the document in a single commit 
> through our review process.

The fact documentation is separated from code is a feature, not a bug. We don't 
want to make updating documentation a contribution requirement. Just like unit 
tests, this sort of thing can significantly hinder our willingness and 
capabilities to do large scale refactoring, renames, etc...

- R. Niwa

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Ling Ho via webkit-dev]

On 9/19/22 4:48 PM, Fujii Hironori via webkit-dev wrote:

Why not double-down on WebKit Git repository?
The closer the document is to the source code, the easier to keep them 
up-to-date.
We can modify both the source code and the document in a single commit 
through our review process.


Do you plan to shutdown https://trac.webkit.org/wiki ?
There is no immediate plan to shut down https://trac.webkit.org/wiki as 
long as there is a need. However, keeping another system with separate 
set of credentials is not ideal especially they are no longer needed for 
SVN.


...
ling




___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Fujii Hironori via webkit-dev]

Why not double-down on WebKit Git repository?
The closer the document is to the source code, the easier to keep them
up-to-date.
We can modify both the source code and the document in a single commit
through our review process.

Do you plan to shutdown https://trac.webkit.org/wiki ?
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Documentation

[Michael Catanzaro via webkit-dev]

Why not double-down on the GitHub wiki? It's very easy to learn to use, 
and there are edit buttons everywhere so there is no "distance" between 
the docs and the ability to edit them. The easier it is to edit docs, 
the better we'll do at keeping them up to date.


I like Markdown, and am OK with editing Markdown files wherever they 
live, but it's not very likely that I would install Swift and figure 
out how to build a new project to to see what the result looks like. 
With GitHub, we can easily preview results live to ensure we're not 
messing anything up.


Michael


___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] WebKit Documentation

[Brandon Stewart via webkit-dev]

Hi WebKit Developers,

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.

A few months ago, I started working on a new documentation solution based on 
the DocC documentation framework. This provides an easy way to add and edit 
documentation through markdown files. I have already ported a large section of 
Trac, all of the GitHub Wiki, and all of the non third party markdown files in 
the code over to this platform. 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.

You can already download the documentation and preview it locally, but we are 
looking to publish it online for easy viewing. We were looking to get your 
feedback if we would want to publish the documentation on GitHub Pages or 
webkit.org.

The documentation source can be found at 
https://github.com/webkit/documentation.

- Brandon
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] webkit-changes substitute

[Alexey Proskuryakov via webkit-dev]

Hi,

There doesn't appear to be anything good enough, filed 
https://bugs.webkit.org/show_bug.cgi?id=243793 to track. Please add your use 
scenarios if they are different from what I listed.

I wanted this too, but gave Jonathan incorrect information about importance - 
it seemed like the mailing list only had a few subscribers these days, but 
double-checking that, there are actually many.

- Alexey

> 8 авг. 2022 г., в 7:32 AM, Dan Bernstein via webkit-dev 
>  написал(а):
> 
> Hello,
> 
> Is there some way to receive full webkit commits in email form, similar to 
> the webkit-changes mailing list?
> ___
> webkit-dev mailing list
> webkit-dev@lists.webkit.org
> https://lists.webkit.org/mailman/listinfo/webkit-dev


_______
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] webkit-changes substitute

[Dan Bernstein via webkit-dev]

Hello,

Is there some way to receive full webkit commits in email form, similar to the 
webkit-changes mailing list?
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit is now on GitHub

[Alex Christensen via webkit-dev]

It may be worth considering doing one more commit with a message explaining 
that we moved the repository.  I often find old repositories places without 
knowing where all the newest things are, and sometimes they have a last git 
commit pointing to the new repository location and I find that quite helpful.  
That may cause tooling problems and it has been quite well communicated that we 
are moving to GitHub, so there are also reasons not to.

> On Jun 23, 2022, at 3:24 PM, Michael Catanzaro via webkit-dev 
>  wrote:
> 
> On Thu, Jun 23 2022 at 03:21:59 PM -0700, Jonathan Bedard  
> wrote:
>> I´m aware of the WebKitGTK branches, please reach out about the WPE ones, 
>> I´m not sure which ones those are.
> 
> The WPE releases actually use the WebKitGTK branches! They are shared 
> branches. I suppose that is pretty confusing, but naming things is hard.
> 
> Sounds like you already have this under control.
> 
> Michael
> 
> 
> ___
> webkit-dev mailing list
> webkit-dev@lists.webkit.org
> https://lists.webkit.org/mailman/listinfo/webkit-dev

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit is now on GitHub

[Michael Catanzaro via webkit-dev]

On Thu, Jun 23 2022 at 03:21:59 PM -0700, Jonathan Bedard 
 wrote:
I’m aware of the WebKitGTK branches, please reach out about the WPE 
ones, I’m not sure which ones those are.


The WPE releases actually use the WebKitGTK branches! They are shared 
branches. I suppose that is pretty confusing, but naming things is hard.


Sounds like you already have this under control.

Michael


___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit is now on GitHub

[Jonathan Bedard via webkit-dev]

I’m aware of the WebKitGTK branches, please reach out about the WPE ones, I’m 
not sure which ones those are.

Absolutely will make sure we’ve migrated everything before delete SVN for good, 
and there will be plenty of warning before we do anything destructive.

Jonathan

> On Jun 23, 2022, at 2:01 PM, Michael Catanzaro  wrote:
> 
> On Thu, Jun 23 2022 at 10:29:55 AM -0700, Jonathan Bedard via webkit-dev 
>  wrote:
>> Let me know if there is any fallout,
> 
> As far as I know, WebKitGTK and WPE WebKit stable branches have not yet been 
> migrated and are now read-only? Let's make sure not to delete SVN until we're 
> certain they have migrated.
> 
> Michael
> 
> 

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit is now on GitHub

[Adrian Perez de Castro via webkit-dev]

Hi Michael,

On Thu, 23 Jun 2022 16:01:11 -0500 Michael Catanzaro via webkit-dev 
 wrote:
> On Thu, Jun 23 2022 at 10:29:55 AM -0700, Jonathan Bedard via 
> webkit-dev  wrote:
> > Let me know if there is any fallout,
> 
> As far as I know, WebKitGTK and WPE WebKit stable branches have not yet 
> been migrated and are now read-only? Let's make sure not to delete SVN 
> until we're certain they have migrated.

Branches *will* be migrated, there has been a thread in Slack about this:

  https://webkit.slack.com/archives/C01C94S4C6M/p1655821161932009

(/me is a bit sad that with more people favoring Slack over mailing
lists important things can go unnoticed and not archived much more
easily)

Cheers,
—Adrián


signature.asc
Description: PGP signature
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit is now on GitHub

[Michael Catanzaro via webkit-dev]

On Thu, Jun 23 2022 at 10:29:55 AM -0700, Jonathan Bedard via 
webkit-dev  wrote:

Let me know if there is any fallout,


As far as I know, WebKitGTK and WPE WebKit stable branches have not yet 
been migrated and are now read-only? Let's make sure not to delete SVN 
until we're certain they have migrated.


Michael


___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] WebKit is now on GitHub

[Jonathan Bedard via webkit-dev]

r295779 is the last commit to WebKit’s Subversion repository. 
https://github.com/WebKit/WebKit is now the canonical home of the WebKit 
project! All commits must now go through Commit-Queue, Merge-Queue or 
Unsafe-Merge-Queue.

For the next few weeks, svn.webkit.org and trac.webkit.org will remain 
accessible in a read-only state so we can audit any content we intend to 
migrate to GitHub.

Let me know if there is any fallout,

Jonathan Bedard
WebKit Continuous Integration

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] webkit-patch land behavior change

[Jonathan Bedard via webkit-dev]

For now, `webkit-patch land-unsafe` would be the answer.

In the future, new contributors would need an existing committer to add the 
`merge-queue` label to a PR which adds the new contributor to contributors.json

Jonathan

> On Apr 27, 2022, at 12:16 AM, Manuel Rego Casasnovas  wrote:
> 
> 
> 
> On 26/04/2022 21:58, Jonathan Bedard via webkit-dev wrote:
>> As we move closer to transitioning away from Subversion, I’ve change 
>> ‘webkit-patch land’ to use commit-queue instead of directly committing a 
>> local change from a contributor’s machine 
>> (https://github.com/WebKit/WebKit/pull/392). ‘git-webkit land-unsafe’ will 
>> allow contributors to directly land to Subversion for the time being, 
>> although after we transition to GitHub, will also use commit-queue and 
>> prefix “fast-cq” to uploaded patches to bypass building and testing.
> 
> If I remember correctly when you're accepted as committer you have to do
> a first manual commit adding you to the contributors.json file; and I
> guess people are using "webkit-patch land" for that (see example [1]).
> 
> Would the new contributors be able to land that first commit with the
> commit-queue behavior?
> 
> Cheers,
>  Rego
> 
> [1] https://bugs.webkit.org/show_bug.cgi?id=237634

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] webkit-patch land behavior change

[Manuel Rego Casasnovas via webkit-dev]

On 26/04/2022 21:58, Jonathan Bedard via webkit-dev wrote:
> As we move closer to transitioning away from Subversion, I’ve change 
> ‘webkit-patch land’ to use commit-queue instead of directly committing a 
> local change from a contributor’s machine 
> (https://github.com/WebKit/WebKit/pull/392). ‘git-webkit land-unsafe’ will 
> allow contributors to directly land to Subversion for the time being, 
> although after we transition to GitHub, will also use commit-queue and prefix 
> “fast-cq” to uploaded patches to bypass building and testing.

If I remember correctly when you're accepted as committer you have to do
a first manual commit adding you to the contributors.json file; and I
guess people are using "webkit-patch land" for that (see example [1]).

Would the new contributors be able to land that first commit with the
commit-queue behavior?

Cheers,
  Rego

[1] https://bugs.webkit.org/show_bug.cgi?id=237634
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] webkit-patch land behavior change

[Jonathan Bedard via webkit-dev]

Hey folks,

As we move closer to transitioning away from Subversion, I’ve change 
‘webkit-patch land’ to use commit-queue instead of directly committing a local 
change from a contributor’s machine 
(https://github.com/WebKit/WebKit/pull/392). ‘git-webkit land-unsafe’ will 
allow contributors to directly land to Subversion for the time being, although 
after we transition to GitHub, will also use commit-queue and prefix “fast-cq” 
to uploaded patches to bypass building and testing.

Jonathan
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit and GitHub Update

[Michael Catanzaro via webkit-dev]

I guess I should create a feedback issue:

https://bugs.webkit.org/show_bug.cgi?id=239124


___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit and GitHub Update

[Michael Catanzaro via webkit-dev]

On Mon, Apr 11 2022 at 03:55:36 PM -0700, Jonathan Bedard via 
webkit-dev  wrote:

start creating some pull requests!


Hi,

For pull requests to find interested reviewers, we need a way to 
subscribe to labels. E.g. I want to receive notifications for pull 
requests with a WebKitGTK or WPE label. Another developer might want to 
watch Network, Multimedia, JavaScriptCore, Web Inspector, etc. This is 
super easy to do with GitLab, but GitHub does not have this 
functionality at all. I believe when we previously discussed this 
problem, somebody suggested running a bot that would allow us to 
emulate this functionality by subscribing to notifications from the 
bot. Does anybody remember what this bot was, or have another concrete 
suggestion on how to make this work?


(This will be a problem for issues as well, if we eventually move from 
Bugzilla to GitHub issues, but I imagine the solution would be the 
same.)


Michael


___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] WebKit and GitHub Update

[Jonathan Bedard via webkit-dev]

It is now the time to start widespread testing of pure git checkouts for 
WebKit. Commit queue has been reimplemented for GitHub, so you don't need a 
Subversion or git-svn checkout for changes to trunk/main that aren’t modifying 
SVN properties.

Over the past few months, we’ve been working on transitioning the WebKit 
project away from Subversion and to `git` hosted by GitHub. While we still have 
a few weeks of work left, we wanted to announce that the WebKit project now 
supports GitHub pull-requests for developing, reviewing and landing changes. 
We’d like to encourage folks to try out these new workflows to identify bugs 
and provide feedback.

To get started, migrate your local WebKit checkouts to the GitHub version 
(documentation is available at https://github.com/WebKit/WebKit/wiki/Migration 
), review our GitHub 
contribution documentation at 
https://github.com/WebKit/WebKit/wiki/Contributing#contributing-code 
, and 
start creating some pull requests!

We will be collecting bugs and feedback under our umbrella bug, 
https://bugs.webkit.org/show_bug.cgi?id=239082 
.

It is worth noting that while we are currently displaying EWS results via 
GitHub’s native checks UI, we have a plan underway to add a dynamic comment 
belonging to EWS that will contain information similar to the bubbles on 
bugs.webkit.org . 

Lastly, we have no plans yet to deprecate patch workflows.  As mentioned in the 
migration documentation, `webkit-patch` will continue to work inside GitHub 
checkouts, so it is possible to use both the pull-request workflow and patch 
workflow from the same checkout.

Jonathan Bedard
WebKit Continuous Integration

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Style: Whitespace for Objective-C protocols

[Myles Maxfield via webkit-dev]

I’ve posted a patch to make these changes official: 
https://bugs.webkit.org/show_bug.cgi?id=237406

> On Feb 24, 2022, at 9:09 AM, Darin Adler  wrote:
> 
> I personally prefer id, and would be happy to standardize on 
> that. I don’t really care that much about statistics about usage in our 
> existing code.
> 
> — Darin

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Style: Whitespace for Objective-C protocols

[Darin Adler via webkit-dev]

I personally prefer id, and would be happy to standardize on 
that. I don’t really care that much about statistics about usage in our 
existing code.

— Darin
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Style: Whitespace for Objective-C protocols

[Kimmo Kinnunen via webkit-dev]

For my subjective opinion and personal project of supporting clang-format, the 
spacing could be this:

  id

@interface WebSpeechRecognizerTaskImpl : 
NSObject 

On the grounds of:
1) No space for type declaration on the grounds that formatting the code would 
not need objective-c semantic analysis to work and it’s similar to other 
spacing rules related to angle brackets.
2) No space for the interface definition on the grounds that there’s no space 
for type declaration, so the rule “no space” is easier to remember.

So the categories of arguments would be roughly practicality, consistency and 
simplicity, evaluated very subjectively.

>  Or would the spacing help you understand that Baz is a protocol but Bar is 
> supplied as a generic type?


For me subjectively semantic spacing in form id  signifying “Foo is 
definitively protocol” would not improve readability. E.g. even if semantic 
spacing was reliable, I doubt I’d get much readability for knowing Baz is a 
protocol.

Discussing semantic spacing merits vs semantic spacing is reliability:

If I understand correctly, being able to rely on spacing you would read the 
latter part unambiguously:
Foo *> *  — Foo is a C++ template or Obj-C generic, Bar is a Obj-C 
class that conforms to Baz

Where as not having semantic spacing notation you would this declaration and 
this interpretation:
Foo*>* — Foo is a C++ template or Obj-C generic, Bar is a Obj-C class 
that conforms to Baz or a C++ template

E.g. semantic spacing is more unambiguous at the surface level, where as 
simpler spacing rule (“generally don’t put spaces near angle brackets or * or 
&") is more ambiguous.

However, unless the spacing is enforced programmatically, you cannot rely on 
semantic spacing. It tends to go wrong, as it has in WebKit currently.

Currently and for the foreseeable future, we don’t have programmatic formatting 
that has exact semantic awareness of the languages being formatted.

This means regardless of the style rules, you anyway have to resolve the 
ambiguity by knowing what Foo,Bar,Baz are, as you cannot trust that the code in 
question conforms to style. To me this would say that semantic spacing is not a 
strong readability argument.

Assuming semantic spacing is not reliable and thus not a readability argument: 

Contrasting cases:
Vector>
Vector>

I’m not sure there is readability argument that would support "space for 
protocols" and “no space for c++ templates” simultaneously.


> Would the inconsistent spacing annoying you? 

Only if there is style guide saying rules about it and review comments are 
enforcing it inconsistently.

This is related to other aspect of Obj-C spacing rules, which I opened a 
discussion end of last year and hope to get back closing it.. (Reminder to 
somebody objecting to obj-c parts to comment on that)

Br,
Kimmo


> On 21. Feb 2022, at 23.19, Myles Maxfield via webkit-dev 
>  wrote:
> 
> Hello!
> 
> I was working on a patch recently where I wanted to give an Objective-C 
> variable a type of “id that conforms to protocol Foo.”
> 
> Should this be spelled like this:
> 
> id  myVariable
> 
> Or like this:
> 
> id myVariable
> 
> I don’t see anything about this in the WebKit style guide 
> <https://webkit.org/code-style-guidelines/>.
> 
> The former appears in WebCore, WebKit, and WebKitLegacy 1035 times, whereas 
> the latter appears only 281 times. On the other hand, Apple’s documentation 
> <https://developer.apple.com/documentation/metal/1433401-mtlcreatesystemdefaultdevice?language=objc>
>  seems to prefer the latter.
> 
> Another consideration - This question is only about Objective-C protocols, 
> not Objective-C generics. We already have a longstanding practice of spelling 
> generics without the space, e.g. NSArray *. So, we could either 
> intentionally choose for protocols to look visually similar to generics, or 
> alternatively we could intentionally choose for protocols to look visually 
> distinct to generics. Consider seeing something like Foo *> *. 
> Would the inconsistent spacing annoying you? Or would the spacing help you 
> understand that Baz is a protocol but Bar is supplied as a generic type? 
> Maybe the * characters already make that clear?
> 
> What should the style guide say here?
> 
> Thanks,
> Myles
> ___
> webkit-dev mailing list
> webkit-dev@lists.webkit.org
> https://lists.webkit.org/mailman/listinfo/webkit-dev

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] WebKit Style: Whitespace for Objective-C protocols

[Myles Maxfield via webkit-dev]

Hello!

I was working on a patch recently where I wanted to give an Objective-C 
variable a type of “id that conforms to protocol Foo.”

Should this be spelled like this:

id  myVariable

Or like this:

id myVariable

I don’t see anything about this in the WebKit style guide 
.

The former appears in WebCore, WebKit, and WebKitLegacy 1035 times, whereas the 
latter appears only 281 times. On the other hand, Apple’s documentation 

 seems to prefer the latter.

Another consideration - This question is only about Objective-C protocols, not 
Objective-C generics. We already have a longstanding practice of spelling 
generics without the space, e.g. NSArray *. So, we could either 
intentionally choose for protocols to look visually similar to generics, or 
alternatively we could intentionally choose for protocols to look visually 
distinct to generics. Consider seeing something like Foo *> *. Would 
the inconsistent spacing annoying you? Or would the spacing help you understand 
that Baz is a protocol but Bar is supplied as a generic type? Maybe the * 
characters already make that clear?

What should the style guide say here?

Thanks,
Myles___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Objective-C++ style, pointer and reference placement

[Michael Catanzaro via webkit-dev]

On Tue, Dec 21 2021 at 02:08:42 PM +0200, Kimmo Kinnunen via webkit-dev 
 wrote:
* All C and Objective-C code should be formatted with rules 
consistent to the C++ rules


Unfortunately all of the WPE/GTK C code intentionally uses a space 
between the type and the asterisk * (for example, 
WebKit/Tools/MiniBrowser/gtk/BrowserWindow.c). I guess we could just 
omit all these files from style checker, or reformat them all, but it's 
going to be annoying to change either way.


Michael


___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] WebKit Objective-C++ style, pointer and reference placement

[Kimmo Kinnunen via webkit-dev]

Currently we have this:

https://webkit.org/code-style-guidelines/#pointers-and-references 


Pointers and References
Pointer types in non-C++ code
Pointer types should be written with a space between the type and the * (so the 
* is adjacent to the following identifier if any).

This is not what was originally intended, and I’m planning to fix the document. 

The original idea was to say: “Objective-C classes should have space between 
the type name and the *”.

I can update the document to reflect this. However, this rule is a bit 
difficult to enforce and quite difficult to format automatically. Also, 
subjectively for me, it is a bit hard to remember. Maybe also for other people, 
as current Objective-C++ is formatted inconsistently in this regard.

To enforce this, I’d imagine we hardcode a semi-comprehensive list of 
Objective-C class names to check-webkit-style. For automatic formatting, the 
scripts can fix up clang-format diffs based on the hardcoded list.

An alternative suggestion would be to change the rule and document as follows:
 * All pointers, references and rvalue-references in Objective-C++ are 
formatted as current C++ style mandates
 * All C and Objective-C code should be formatted with rules consistent to the 
C++ rules
 * The exception would be public Objective-C headers and WebKit SPI headers, 
which would be formatted as part of Apple internal API definition process

The change above would be fitting to programmatic formatting and format 
verification, as it simplifies the rules and avoids the need of semantic 
analysis of the code for the formatting purposes.

Please reply to this to discuss which way would be preferable.

The bug:
https://bugs.webkit.org/show_bug.cgi?id=234294 



Br,
Kimmo___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] WebKit SVN tree clousures (April 2021)

[Ling Ho via webkit-dev]

Hello WebKit,

One of the infrastruture maintenance works that was planned for early 
March has been rescheduled for the weekend starting April 2nd.
Our critical continuous integration services (EWS, post-commit bots, 
etc.) will be unavailable during:


*Begin*: Friday, April 2nd, 2021. 5pm (PDT)
*End*: Monday, April 5th, 2021. No later than 6pm (PDT)

To avoid accumulating difficult to diagnose regressions during this 
lengthy outage, *WebKit SVN tree will be closed*.


I will send out email if there is any change to the schedule.

Please contact us at ad...@webkit.org if you have any questions or concerns.

Thank you,

...
Ling Ho
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] WebKit SVN tree clousures (March 2021)

[Ling Ho via webkit-dev]

Hello WebKit,

Due to planned infrastructure maintenance, our critical continuous 
integration services (EWS and post-commit bots) will be unavailable 
during the following weekends:


*Dates*:
*Begin*: Friday, March 5th, 2021. 5pm (PST)
*End*: Monday, March 8th, 2021. No later than 6pm (PST)

*Begin*: Friday, March 19th, 2021. 5pm (PDT)
*End*: Monday, March 22nd, 2021. No later than 6pm (PDT)

To avoid accumulating difficult to diagnose regressions during this 
lengthy outage, *WebKit SVN tree will be closed*.


Please email ad...@webkit.org if you have any questions or concerns.

Thanks,

...
Ling Ho
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] Webkit MediaRecorder Timeslice functionality on Safari 14.0.2 Mojave

[youenn fablet via webkit-dev]

Hi Mark,

Thanks for reaching out.

For timeslice specific questions, it might be best to continue discussions
in https://bugs.webkit.org/show_bug.cgi?id=202233.

Timeslice support in older versions of MacOS and iOS is tricky.
On those OSes, including MacOS Mojave, MediaRecorder is not enabled by
default.

On the most recent BigSur and iOS versions, MediaRecorder should be enabled
by default and timeslice should be supported.

Hope this helps,
Y

Le lun. 1 févr. 2021 à 17:29, Gallery via webkit-dev <
webkit-dev@lists.webkit.org> a écrit :

> Hi Folks
>
> We are developing a streaming system which uses MediaRecorder with
> timeslice.
>
> It's clear that Safari only has MediaRecorder as developer experiment, and
> that older versions of Safari dont support timeslice anyway.
> However, a recent WebKit thread
> https://bugs.webkit.org/show_bug.cgi?id=202233
> Suggests that timeslice *is* implemented in Safari 14.0.2 and the author
> provided an example jsfiddle:  https://jsfiddle.net/hdwc2xzL/
>
> Our experience suggests all is not as expected:
>
> *On Big Sur (on Apple DTK)*
> *- Safari 14.02 * (with mediarecorder enabled in experimental features)
> does appear to work as expected.  MediaRecorder and timeslice all correct.
>
>
> *On macOS Mojave (on MacBook Pro intel)*
> -* Safari 13* - (with mediarecorder enabled in experimental features).
> MediaRecorder initialises OK and works as expected (but without timeslice
> callbacks)
> - *Safari 14.0.2* (with mediarecorder enabled in experimental features)
>  Throws an error when initialising MediaRecorder *"NotSupportedError: The
> MediaRecorder is unsupported on this platform”*
>
> Both our own mechanism. and the jsfiddle referenced above shows the same
> error;
> try
> {
> mediaRecorder = new MediaRecorder(window.stream, options);  *//
> options is just  {videoBitsPerSecond: 150} - hence allowing default
> mimetype, window.stream successful from getUserMedia*
> }
> catch (e)
> {
> console.error('navigator.getUserMedia error:', e);
> errorMsgElement.innerHTML = `navigator.getUserMedia error:${e.toString()}`;
>
> // fails: *"NotSupportedError: The MediaRecorder is unsupported on this
> platform”*
>
>  }
>
> so we dont even get as far as calling mediaRecorder.start(timeslice_ms)
> any more (as we did with Safari 13)
>
>
> *Could anyone explain this behaviour in Mojave ?   *
> *Should MediaRecorder work on the official shipping 14.02 downloaded on
> Mojave ?*
> *On a related note - what should we expect from mobile Safari with respect
> to timeslice MediaRecorder ?*
>
> *When might we see MediaRecorder enabled by default so we can use it for
> customer applications ???*
>
> *Many Thanks !*
>
>
>
> ___
> webkit-dev mailing list
> webkit-dev@lists.webkit.org
> https://lists.webkit.org/mailman/listinfo/webkit-dev
>
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] Webkit MediaRecorder Timeslice functionality on Safari 14.0.2 Mojave

[Gallery via webkit-dev]

Hi Folks

We are developing a streaming system which uses MediaRecorder with timeslice.

It's clear that Safari only has MediaRecorder as developer experiment, and that 
older versions of Safari dont support timeslice anyway.  
However, a recent WebKit thread https://bugs.webkit.org/show_bug.cgi?id=202233 

Suggests that timeslice *is* implemented in Safari 14.0.2 and the author 
provided an example jsfiddle:  https://jsfiddle.net/hdwc2xzL/ 


Our experience suggests all is not as expected:

On Big Sur (on Apple DTK)
- Safari 14.02  (with mediarecorder enabled in experimental features) does 
appear to work as expected.  MediaRecorder and timeslice all correct.


On macOS Mojave (on MacBook Pro intel)
- Safari 13 - (with mediarecorder enabled in experimental features).  
MediaRecorder initialises OK and works as expected (but without timeslice 
callbacks)
- Safari 14.0.2 (with mediarecorder enabled in experimental features)  Throws 
an error when initialising MediaRecorder "NotSupportedError: The MediaRecorder 
is unsupported on this platform”

Both our own mechanism. and the jsfiddle referenced above shows the same error;
try 
{
mediaRecorder = new MediaRecorder(window.stream, options);  // 
options is just  {videoBitsPerSecond: 150} - hence allowing default 
mimetype, window.stream successful from getUserMedia
}
catch (e) 
{
console.error('navigator.getUserMedia error:', e);
errorMsgElement.innerHTML = `navigator.getUserMedia 
error:${e.toString()}`;

// fails: "NotSupportedError: The MediaRecorder is unsupported on this platform”

 }

so we dont even get as far as calling mediaRecorder.start(timeslice_ms) any 
more (as we did with Safari 13)


Could anyone explain this behaviour in Mojave ?   
Should MediaRecorder work on the official shipping 14.02 downloaded on Mojave ?
On a related note - what should we expect from mobile Safari with respect to 
timeslice MediaRecorder ?

When might we see MediaRecorder enabled by default so we can use it for 
customer applications ???

Many Thanks !



___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] WebKit SVN Tree clousure (Dec 23, 2020 - Jan 5, 2021)

[Ling Ho via webkit-dev]

Hello WebKit,

Some of our critical continuous integration services will be unavailable 
due to planned underlying infrastructure maintenance.


Most EWS and post-commit bots will be down, so we will be closing the 
WebKit SVN tree to avoid accumulating difficult to diagnose regressions 
during this lengthy outage.


The planned closure of the tree will begin at *5 pm (PST) on Wednesday, 
Dec 23rd, 2020* until no later than *6 pm (PST) on Tuesday, Jan 5th**, 2021.


*Please email ad...@webkit.org if you have any questions or concerns.

Thanks,

...
Ling Ho
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

[webkit-dev] WebKit SVN Tree clousure (Nov 22nd - Nov 26th, 2020)

[Ling Ho via webkit-dev]

Hello WebKit,

Some of our critical continuous integration services will be unavailable 
due to planned underlying infrastructure maintenance.


Most EWS and post-commit bots will be down, so we will be closing the 
WebKit SVN tree to avoid accumulating difficult to diagnose regressions 
during this lengthy outage.


The planned closure of the tree will begin at *8 pm (PST) on Sunday, Nov 
22nd, 2020* until no later than *11 pm (PST) on Thursday, Nov 26th**, 2020.


*Please email ad...@webkit.org if you have any questions or concerns.

Thanks,

...
Ling Ho
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Maciej Stachowiak]

> On Oct 13, 2020, at 2:37 PM, Konstantin Tokarev  wrote:
> 
> 
> 
> 13.10.2020, 22:33, "Maciej Stachowiak" :
>>>  On Oct 2, 2020, at 10:59 AM, Michael Catanzaro  
>>> wrote:
>>> 
>>>  On Fri, Oct 2, 2020 at 6:36 pm, Philippe Normand  wrote:
  Would you also consider preventing merge commits in order to keep a
  clean mainline branch?
>>> 
>>>  Big +1 to blocking merge commits. Merge commits in a huge project like 
>>> WebKit would make commit archaeology very frustrating. (I assume this is 
>>> implied by the monotonic commit identifiers proposal, but it doesn't 
>>> exactly say that.)
>> 
>> I’m assuming your objection is to regular merges, but how do you feel about 
>> squash merges? Or do you think all PRs should be landed by rebasing?
> 
> I'm not Michael but will add my 2 dollars anyway :)
> 
> In these two approaches commits inside PR have different meaning, and 
> workflow is different.
> 
> Below I use a term "atomic change" to describe minimal code change which is a 
> self-contained work unit with following properties:
> * It implements well-defined task which can be summarized as a short English 
> sentence (typical soft limit is 60 characters)
> * It doesn't introduce defects (e.g. bugs, compilation breakages, style 
> errors, typos) which were discovered during review process
> * It doesn't include any code changes unrelated to main topic. This 
> separation is sometimes subjective, but it's usually recommended to split 
> refactoring and implementation of feature based on that, bug fix and new 
> feature, big style change and fix or feature.
> 
> AFAIU our current review process has similar requirements to patches 
> submitted to Bugzilla, though sometimes patches include unrelated changes. 
> This can be justified by weakness of webkit-patch/Bugzilla tooling which has 
> no support for patch series, and by fact that SVN doesn't support keeping 
> local patch series at all.
> 
> 1. Workflow 1 - "Squash merge" policy
> 
> * Whole PR is considered to be a single atomic change of WebKit source tree. 
> If work is supposed to be landed as a series of changes which depend on each 
> other (e.g. refactoring and feature based on it, or individual separate 
> features touching same parts of code), each change needs a separate PR, and, 
> as a consequence, only one of them can be efficiently reviewed at the moment 
> of time
> * Commits in PR represent review iterations or intermediate implementation 
> progress
> * Reviewers' comments are addressed by pushing new commits without rewriting 
> history, which works around GitHub's lack of "commit revisions". Also this 
> workflow has lower entry barrier for people who haven't mastered git yet, as 
> it requires only "git commit" and "git push" without rebases.
> 
> 2. Workflow 2 - "Rebase" ("cherry-pick")) or "Merge" policy
> 
> * PR is considered to be a series of atomic changes. If work consists of 
> several atomic changes, each commit represent an atomic change
> * Review iterations are done by fixing commits in place and reuploading 
> entire series using force push (of course if review discovers that 
> substantial part of work is missing it can be added as a new atomic commit to 
> the series)
> * It's possible to review each commit in the series separately
> * Workflow requires developers to have more discipline and experience with 
> using git rebase for history rewriting. Entry barrier can be lowered by 
> providing step by step instructions like e.g. [1]. 
> 
> 
> Workflow 1 is more like what we have now with Bugzilla.
> 
> Workflow 2 is used by many projects which use git for a long time and value 
> high-quality commit history. It's used e.g. by Linux kernel, or projects 
> which use Gerrit as a review tool (Chromium, Android, Qt, etc). It advantages 
> for developers (who can submit more work to review at the same time without 
> risk of mixing up unrelated changes together), reviewers (it's easier to 
> review atomic changes than those with too high or too low granularity), 
> maintainers of stable branches (they can pick bug reports and avoid at least 
> some unneeded refactorings, features and style improvements).
> 
> Workflow 1 is the most obvious way to use GitHub, because it doesn't make any 
> hints about existence of workflow 2. However, many projects which use GitHub 
> for code review and value high-quality history are using workflow 2. For 
> example, see Ryosuke's example with whatwg/html repo.
> 
> Workflow 2 is facilitated by Gerrit, which doesn't require using force pushes 
> and makes it immediately obvious for new user if they start adding new fixup 
> commits instead of editing those being reviewed.
> 
> Workflow 2 can use both rebase and merge strategies, and merge isn't so evil 
> in this case. However, using merge moves responsibility for solving conflicts 
> from contributor to repository maintainers, which doesn't scale well. 
> Projects which accept patches via mailing lists, like Linux kernel, imply 
> 

Re: [webkit-dev] WebKit Transition to Git

[Fujii Hironori]

According to this Jonathan's bugzilla comment, a new git repository will be
reconstructed.
https://bugs.webkit.org/show_bug.cgi?id=214957#c12

It'd be nice if commit-qu...@webkit.org is replaced by real authors.
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Tetsuharu OHZEKI]

On Fri, Oct 16, 2020 at 4:49 AM Konstantin Tokarev  wrote:
>
>
> Why would you want to do that?
>
> I think rich text in comments is evil, for the same reasons as HTML e-mail.
>
> Yes, with markdown you won't often see unreadably colored text (what happens
> with HTML e-mail), but still there is pretty much room for abuse of formatting
> (to attract attention or just because they can), or accidental formatting when
> non-markdown text is interpreted as markdown resulting in a total mess
> (which inexperienced users cannot fix and leave as is).
>
> BTW, GitHub recently added rich text UI controls to code review comments, so
> even those who don't know markdown can start abusing formatting there now...

Sorry, I'm not sure about that why you feel a bad emotion for rich
text format...

As my stance, I prefer to display a code snippet, quote and list as
formatted style with a discussion with BTS.

It's a bit hard to read a quote as styled `>` like this text email for
me, so I'd like to read a quote block as a styled format by default.

But this is my personal complaints.
I would not like to say that WebKit Bugzilla must support markdown in
the comment form immediately.

--
Tetsuharu OHZEKI
tetsuharu.ohz...@gmail.com

On Fri, Oct 16, 2020 at 4:49 AM Konstantin Tokarev  wrote:
>
>
>
> 14.10.2020, 16:52, "Tetsuharu OHZEKI" :
> > I feel from this discussion that everybody has their own best way and
> > we’re tackling to resolve them at once in this migration process.
> > I also feel it’s a bit difficult to conclude something.
> >
> > FWIW, I would like to write some my problems about the current
> > workflow to help figure out
> > what is a problem in the current workflow and what we should be
> > resolved in this or other future process.
> >
> > This would not propose an actual solution, but I believe this would
> > help to find a final solution and other people will also say your
> > problems to help.
> >
> > 1. Code review tools
> > WebKit Bugzilla’s code review tool is not a beautiful solution for today.
> > I would like to get a preview for markdown file or syntax highlights.
> >
> > 2. Bug Tracking System
> > I don’t feel a problem to use WebKit Bugzilla, and I doubt that using
> > Bugzilla is really a problem to collect a feedback from the webdev
> > community as other people said in this thread.
> > However, I have some complaints…
> >
> > * I’d like to write markdown as a comment for bugs.
>
> Why would you want to do that?
>
> I think rich text in comments is evil, for the same reasons as HTML e-mail.
>
> Yes, with markdown you won't often see unreadably colored text (what happens
> with HTML e-mail), but still there is pretty much room for abuse of formatting
> (to attract attention or just because they can), or accidental formatting when
> non-markdown text is interpreted as markdown resulting in a total mess
> (which inexperienced users cannot fix and leave as is).
>
> BTW, GitHub recently added rich text UI controls to code review comments, so
> even those who don't know markdown can start abusing formatting there now...
>
> --
> Regards,
> Konstantin
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Konstantin Tokarev]

14.10.2020, 16:52, "Tetsuharu OHZEKI" :
> I feel from this discussion that everybody has their own best way and
> we’re tackling to resolve them at once in this migration process.
> I also feel it’s a bit difficult to conclude something.
>
> FWIW, I would like to write some my problems about the current
> workflow to help figure out
> what is a problem in the current workflow and what we should be
> resolved in this or other future process.
>
> This would not propose an actual solution, but I believe this would
> help to find a final solution and other people will also say your
> problems to help.
>
> 1. Code review tools
> WebKit Bugzilla’s code review tool is not a beautiful solution for today.
> I would like to get a preview for markdown file or syntax highlights.
>
> 2. Bug Tracking System
> I don’t feel a problem to use WebKit Bugzilla, and I doubt that using
> Bugzilla is really a problem to collect a feedback from the webdev
> community as other people said in this thread.
> However, I have some complaints…
>
> * I’d like to write markdown as a comment for bugs.

Why would you want to do that?

I think rich text in comments is evil, for the same reasons as HTML e-mail.

Yes, with markdown you won't often see unreadably colored text (what happens
with HTML e-mail), but still there is pretty much room for abuse of formatting
(to attract attention or just because they can), or accidental formatting when
non-markdown text is interpreted as markdown resulting in a total mess
(which inexperienced users cannot fix and leave as is).

BTW, GitHub recently added rich text UI controls to code review comments, so
even those who don't know markdown can start abusing formatting there now...

-- 
Regards,
Konstantin
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Tetsuharu OHZEKI]

> The original goal mentionned at the start of the thread was encouraging
> more people to contribute to WebKit. From that side, what's important is
> trying to retain a patch submission workflow that's standardized. That can
> be github/gitlab style pull requests, or Gerrit which is a different one.
> There are probably others.
>
> If the workflow for submitting patches requires writing a changelog file,
> or other similar custom operations, I think that's more likely to turn
> potential contributors away (I can only speak for myself, here, of
course).
> Even if you automate it with a script, people will have to remember to
> use the script. Then it doesn't matter if you use Git or Github or some
> other tool under the hood: the patch submission process is a custom one.
>
> Starting from there, the question is more:
>
> Which of these existing workflows is more suitable?
>
> How much can we tweak them (with bots on Github, plugins
> on Gerrit, or pre-commit/pre-push hooks on developer machines, for
example)
> to make them better fit the existing things that will probably be kept?
> (I guess Apple internal bugtracker, possibly bugzilla as well, maybe some
> parts of the existing build infrastructure and builder machines?).
>
> Can these changes to the workflow be done and documented so that existing
> Git (and Github/Gitlab/Gerrit/...) users can handle them easily?


I agree that VCS is a one of the barriers to contribute to a new
project at this era
which is Git is a winner of VCS share.
For that means, I think it's nice goal that WebKit moves Git
even if we have been able to clone a repository by git-svn or
https://github.com/WebKit/webkit.

By contrast, I doubt GitHub or GitLab would reduce a barrier for a new
contributor.
Every project has some customs and we need to know them on contributing.
Especially, large projects have this tendency.

As a contributor, there is no difference between learning WebKit scripts and
pull requests conventions for each project hosted on GitHub.

Personally, for welcome a contributor,
it's important that a contributor can access a guide to such custom habit,
receive a reviewer's quickly feedback, and easily find a good-first-bug,
can access a design guide (This is best but I know it's hard), and etc.

For these points, I feel today's WebKit goes positively.

Of course, WebKit's testing has a strong habit and
bunch of documents about that in trac.webkit.org are complex.

However, for example, Ryosuke-san's guide was pretty helpful for me.
https://bugs.webkit.org/show_bug.cgi?id=217017.
Some WebKit blog's articles related to JSC are nice because they
usually talk about design details (I'm a fan of them!).
I have not contributed to JSC but they help me with reading code.

Overall, as a newcomer contributor, I think WebKit goes positively.

To be honest, I think that moving to GitHub cannot mean easily that to
be welcome a new contributor.



--
Tetsuharu OHZEKI
tetsuharu.ohz...@gmail.com





On Wed, Oct 14, 2020 at 11:12 PM Adrien Destugues
 wrote:
>
> > 3. Changelog
> > I don’t feel it's a big problem to write ChangeLog file.
> > Of course, this is tired thing but I don’t have a strong alternative
> > after reading this thread.
> >
> > However the current `prepare-Changelog` script does not fit with a
> > branch -based workflow on Git, I feel. There is a room to polish on
> > this Git migration.
> >
> > For example, I’d like to specify a branch as my working set in my
> > local machine, instead of commit or staged changes.
> >
> > Ordinary, I do these flows but it’s a bit tired…. (if you know more
> > good ways, could you tell me!):
> >
> > 1. Run `prepare-Changelog`
> > 2. Format ChangeLog file and remove duplicated entries added by _steps
1_.
> > 3. Fuse new changes into a single patch by `git add . && git commit
> > --ammend` or `git commit --fixup HEAD && git rebase master -i
> > --autosquash`
> > 4. Upload patches by `webkit-patch upload -g HEAD`
> >
> > I don’t have an objection that we merge a squashed patch into trunk to
> > simplify the history but we would have some chance to improve the
script.
> >
>
> The original goal mentionned at the start of the thread was encouraging
> more people to contribute to WebKit. From that side, what's important is
> trying to retain a patch submission workflow that's standardized. That can
> be github/gitlab style pull requests, or Gerrit which is a different one.
> There are probably others.
>
> If the workflow for submitting patches requires writing a changelog file,
> or other similar custom operations, I think that's more likely to turn
> potential contributors away (I can only speak for myself, here, of
course).
> Even if you automate it with a script, people will have to remember to
> use the script. Then it doesn't matter if you use Git or Github or some
> other tool under the hood: the patch submission process is a custom one.
>
> Starting from there, the question is more:
>
> Which of these existing workflows is more 

Re: [webkit-dev] WebKit Transition to Git (Merge Workflows)

[Jonathan Bedard]

To point something out with the squash merge vs rebase merge policies, we will 
definitely be enforcing squash merges at least initially because rebase merges 
require some extra EWS and commit-queue infrastructure.

Recall that WebKit does regression testing for every commit, even if these 
commits were landed at exactly the same time. With SVN, this fact is 
unimportant because commit-queue and EWS enforce every commit being atomic. If 
we wanted to support rebase merges, what we’re really saying is that we want 
EWS and commit-queue to run on each individual change in a PR, because at least 
some post-commit infrastructure will do the same. That’s something we could do, 
but it has some downsides, namely, if contributors are too commit-happy, we 
will end up using more compute time on each PR.

Jonathan___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Adrien Destugues]

> 3. Changelog
> I don’t feel it's a big problem to write ChangeLog file.
> Of course, this is tired thing but I don’t have a strong alternative
> after reading this thread.
> 
> However the current `prepare-Changelog` script does not fit with a
> branch -based workflow on Git, I feel. There is a room to polish on
> this Git migration.
> 
> For example, I’d like to specify a branch as my working set in my
> local machine, instead of commit or staged changes.
> 
> Ordinary, I do these flows but it’s a bit tired…. (if you know more
> good ways, could you tell me!):
> 
> 1. Run `prepare-Changelog`
> 2. Format ChangeLog file and remove duplicated entries added by _steps 1_.
> 3. Fuse new changes into a single patch by `git add . && git commit
> --ammend` or `git commit --fixup HEAD && git rebase master -i
> --autosquash`
> 4. Upload patches by `webkit-patch upload -g HEAD`
> 
> I don’t have an objection that we merge a squashed patch into trunk to
> simplify the history but we would have some chance to improve the script.
> 

The original goal mentionned at the start of the thread was encouraging
more people to contribute to WebKit. From that side, what's important is
trying to retain a patch submission workflow that's standardized. That can
be github/gitlab style pull requests, or Gerrit which is a different one.
There are probably others.

If the workflow for submitting patches requires writing a changelog file,
or other similar custom operations, I think that's more likely to turn
potential contributors away (I can only speak for myself, here, of course).
Even if you automate it with a script, people will have to remember to
use the script. Then it doesn't matter if you use Git or Github or some
other tool under the hood: the patch submission process is a custom one.

Starting from there, the question is more:

Which of these existing workflows is more suitable?

How much can we tweak them (with bots on Github, plugins
on Gerrit, or pre-commit/pre-push hooks on developer machines, for example)
to make them better fit the existing things that will probably be kept?
(I guess Apple internal bugtracker, possibly bugzilla as well, maybe some
parts of the existing build infrastructure and builder machines?).

Can these changes to the workflow be done and documented so that existing
Git (and Github/Gitlab/Gerrit/...) users can handle them easily?

-- 
Adrien.

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Tetsuharu OHZEKI]

ker. Bugzilla has served us well, but seems to be an impediment to 
> engaging with the open source community. We are interested in moving away 
> from Bugzilla and to GitHub Issues, allowing new developers to work with a 
> system they are likely already familiar with and to allow us closer 
> integration with repositories managed by W3C. Although GitHub Issues has had 
> performance problems in the past with projects that have many bugs, these 
> performance problems have been resolved to the satisfaction of a few large 
> projects hosted on GitHub that are of a comparable scale to WebKit. The 
> biggest blocker we are aware of is managing security bugs, since the security 
> advisory system used by GitHub is essentially the opposite of how WebKit 
> security bugs work. Moving to GitHub Issues, if it happens, will be the last 
> part of this transition, and we are interested in soliciting feedback from 
> our contributors on what the WebKit project’s integration with GitHub Issues 
> should look like.
>
> Look forward to hearing from all of you,
>
> Jonathan Bedard
> WebKit Operations
> ___
> webkit-dev mailing list
> webkit-dev@lists.webkit.org
> https://lists.webkit.org/mailman/listinfo/webkit-dev
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Ken Russell]

On Tue, Oct 13, 2020 at 2:37 PM Konstantin Tokarev 
wrote:

>
>
> 13.10.2020, 22:33, "Maciej Stachowiak" :
> >>  On Oct 2, 2020, at 10:59 AM, Michael Catanzaro 
> wrote:
> >>
> >>  On Fri, Oct 2, 2020 at 6:36 pm, Philippe Normand 
> wrote:
> >>>  Would you also consider preventing merge commits in order to keep a
> >>>  clean mainline branch?
> >>
> >>  Big +1 to blocking merge commits. Merge commits in a huge project like
> WebKit would make commit archaeology very frustrating. (I assume this is
> implied by the monotonic commit identifiers proposal, but it doesn't
> exactly say that.)
> >
> > I’m assuming your objection is to regular merges, but how do you feel
> about squash merges? Or do you think all PRs should be landed by rebasing?
>
> I'm not Michael but will add my 2 dollars anyway :)
>
> In these two approaches commits inside PR have different meaning, and
> workflow is different.
>
> Below I use a term "atomic change" to describe minimal code change which
> is a self-contained work unit with following properties:
> * It implements well-defined task which can be summarized as a short
> English sentence (typical soft limit is 60 characters)
> * It doesn't introduce defects (e.g. bugs, compilation breakages, style
> errors, typos) which were discovered during review process
> * It doesn't include any code changes unrelated to main topic. This
> separation is sometimes subjective, but it's usually recommended to split
> refactoring and implementation of feature based on that, bug fix and new
> feature, big style change and fix or feature.
>
> AFAIU our current review process has similar requirements to patches
> submitted to Bugzilla, though sometimes patches include unrelated changes.
> This can be justified by weakness of webkit-patch/Bugzilla tooling which
> has no support for patch series, and by fact that SVN doesn't support
> keeping local patch series at all.
>
> 1. Workflow 1 - "Squash merge" policy
>
> * Whole PR is considered to be a single atomic change of WebKit source
> tree. If work is supposed to be landed as a series of changes which depend
> on each other (e.g. refactoring and feature based on it, or individual
> separate features touching same parts of code), each change needs a
> separate PR, and, as a consequence, only one of them can be efficiently
> reviewed at the moment of time
> * Commits in PR represent review iterations or intermediate implementation
> progress
> * Reviewers' comments are addressed by pushing new commits without
> rewriting history, which works around GitHub's lack of "commit revisions".
> Also this workflow has lower entry barrier for people who haven't mastered
> git yet, as it requires only "git commit" and "git push" without rebases.
>
> 2. Workflow 2 - "Rebase" ("cherry-pick")) or "Merge" policy
>
> * PR is considered to be a series of atomic changes. If work consists of
> several atomic changes, each commit represent an atomic change
> * Review iterations are done by fixing commits in place and reuploading
> entire series using force push (of course if review discovers that
> substantial part of work is missing it can be added as a new atomic commit
> to the series)
> * It's possible to review each commit in the series separately
> * Workflow requires developers to have more discipline and experience with
> using git rebase for history rewriting. Entry barrier can be lowered by
> providing step by step instructions like e.g. [1].
>
>
> Workflow 1 is more like what we have now with Bugzilla.
>
> Workflow 2 is used by many projects which use git for a long time and
> value high-quality commit history. It's used e.g. by Linux kernel, or
> projects which use Gerrit as a review tool (Chromium, Android, Qt, etc). It
> advantages for developers (who can submit more work to review at the same
> time without risk of mixing up unrelated changes together), reviewers (it's
> easier to review atomic changes than those with too high or too low
> granularity), maintainers of stable branches (they can pick bug reports and
> avoid at least some unneeded refactorings, features and style improvements).
>

Slight correction: Chromium's Gerrit instance actually uses Workflow 1 -
the "squash merge" policy. The developer can have multiple Git commits on a
single branch and associated with a single Gerrit code review. Each time
the branch is uploaded into the review tool, all of those commits' diffs
are squashed together into the current patchset - the new version of the
review.

Some sub-projects' Gerrit instances, such as ANGLE
's, use Workflow 2. The
developer is expected to use "git commit --amend" each time to modify their
work. Each Git commit corresponds to exactly one code review on Gerrit.

Having gotten used to Workflow 1, and only rarely maintaining multiple
dependent CLs in flight, I find Workflow 1 generally easier to use.

-Ken


Workflow 1 is the most obvious way to use GitHub, because it doesn't make
> any 

Re: [webkit-dev] WebKit Transition to Git

[Manuel Rego Casasnovas]

On 14/10/2020 03:12, Ken Russell wrote:
> On Tue, Oct 13, 2020 at 2:37 PM Konstantin Tokarev  > wrote:
> 1. Workflow 1 - "Squash merge" policy
> 
> * Whole PR is considered to be a single atomic change of WebKit
> source tree. If work is supposed to be landed as a series of changes
> which depend on each other (e.g. refactoring and feature based on
> it, or individual separate features touching same parts of code),
> each change needs a separate PR, and, as a consequence, only one of
> them can be efficiently reviewed at the moment of time
> * Commits in PR represent review iterations or intermediate
> implementation progress
> * Reviewers' comments are addressed by pushing new commits without
> rewriting history, which works around GitHub's lack of "commit
> revisions". Also this workflow has lower entry barrier for people
> who haven't mastered git yet, as it requires only "git commit" and
> "git push" without rebases.
> 
> 2. Workflow 2 - "Rebase" ("cherry-pick")) or "Merge" policy
> 
> * PR is considered to be a series of atomic changes. If work
> consists of several atomic changes, each commit represent an atomic
> change
> * Review iterations are done by fixing commits in place and
> reuploading entire series using force push (of course if review
> discovers that substantial part of work is missing it can be added
> as a new atomic commit to the series)
> * It's possible to review each commit in the series separately
> * Workflow requires developers to have more discipline and
> experience with using git rebase for history rewriting. Entry
> barrier can be lowered by providing step by step instructions like
> e.g. [1].
> 
> 
> Workflow 1 is more like what we have now with Bugzilla.
> 
> Workflow 2 is used by many projects which use git for a long time
> and value high-quality commit history. It's used e.g. by Linux
> kernel, or projects which use Gerrit as a review tool (Chromium,
> Android, Qt, etc). It advantages for developers (who can submit more
> work to review at the same time without risk of mixing up unrelated
> changes together), reviewers (it's easier to review atomic changes
> than those with too high or too low granularity), maintainers of
> stable branches (they can pick bug reports and avoid at least some
> unneeded refactorings, features and style improvements).
> 
> 
> Slight correction: Chromium's Gerrit instance actually uses Workflow 1 -
> the "squash merge" policy. The developer can have multiple Git commits
> on a single branch and associated with a single Gerrit code review. Each
> time the branch is uploaded into the review tool, all of those commits'
> diffs are squashed together into the current patchset - the new version
> of the review.

Yeah this Workflow 1 has been working fine in Chromium since the fork,
and it's pretty similar to what we currently have in WebKit bugzila, so
I think it'd be the best option when WebKit is on Git too.

If I understood correctly, the only difference with Chromium's Gerrit
would be that you cannot mark dependencies between PRs, but that's not
something that people use every day (mostly is used when you want to
test your patches in advance against the tryjobs/EWS or the perfbots)
and as Ryosuke mentioned you could share that WIP commits in your own
branch, or even in a dummy PR if you need to check EWS results and
discard that afterwards once it's split in several PRs.

I also don't see the problem with creating a new bug entry for a small
change and make the change separately, I have asked for that kind of
things in WebKit bugzilla a few times when I reviewed a patch that had
some unrelated change that could be landed separately. I know that's not
always the case and sometimes we land bigger patches than it should, but
I think that's more on the author and reviewer considerations.

My 2 cents,
  Rego
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Ryosuke Niwa]

On Tue, Oct 13, 2020 at 4:12 PM Konstantin Tokarev  wrote:
>
>
>
> 14.10.2020, 02:01, "Ryosuke Niwa" :
> > On Tue, Oct 13, 2020 at 3:53 PM Konstantin Tokarev  
> > wrote:
> >>  14.10.2020, 01:45, "Ryosuke Niwa" :
> >>  > On Tue, Oct 13, 2020 at 3:40 PM Konstantin Tokarev  
> >> wrote:
> >>  >> 14.10.2020, 01:30, "Ryosuke Niwa" :
> >>  >> > On Tue, Oct 13, 2020 at 2:37 PM Konstantin Tokarev 
> >>  wrote:
> >>  >> >> 13.10.2020, 22:33, "Maciej Stachowiak" :
> >>  >> >> >> On Oct 2, 2020, at 10:59 AM, Michael Catanzaro 
> >>  wrote:
> >>  >> >> >>
> >>  >> >> >> On Fri, Oct 2, 2020 at 6:36 pm, Philippe Normand 
> >>  wrote:
> >>  >> >> >>> Would you also consider preventing merge commits in order to 
> >> keep a
> >>  >> >> >>> clean mainline branch?
> >>  >> >> >>
> >>  >> >> >> Big +1 to blocking merge commits. Merge commits in a huge 
> >> project like WebKit would make commit archaeology very frustrating. (I 
> >> assume this is implied by the monotonic commit identifiers proposal, but 
> >> it doesn't exactly say that.)
> >>  >> >> >
> >>  >> >> > I’m assuming your objection is to regular merges, but how do you 
> >> feel about squash merges? Or do you think all PRs should be landed by 
> >> rebasing?
> >>  >> >>
> >>  >> >> I'm not Michael but will add my 2 dollars anyway :)
> >>  >> >>
> >>  >> >> In these two approaches commits inside PR have different meaning, 
> >> and workflow is different.
> >>  >> >>
> >>  >> >> Below I use a term "atomic change" to describe minimal code change 
> >> which is a self-contained work unit with following properties:
> >>  >> >> * It implements well-defined task which can be summarized as a 
> >> short English sentence (typical soft limit is 60 characters)
> >>  >> >> * It doesn't introduce defects (e.g. bugs, compilation breakages, 
> >> style errors, typos) which were discovered during review process
> >>  >> >> * It doesn't include any code changes unrelated to main topic. This 
> >> separation is sometimes subjective, but it's usually recommended to split 
> >> refactoring and implementation of feature based on that, bug fix and new 
> >> feature, big style change and fix or feature.
> >>  >> >>
> >>  >> >> AFAIU our current review process has similar requirements to 
> >> patches submitted to Bugzilla, though sometimes patches include unrelated 
> >> changes. This can be justified by weakness of webkit-patch/Bugzilla 
> >> tooling which has no support for patch series, and by fact that SVN 
> >> doesn't support keeping local patch series at all.
> >>  >> >>
> >>  >> >> 1. Workflow 1 - "Squash merge" policy
> >>  >> >>
> >>  >> >> * Whole PR is considered to be a single atomic change of WebKit 
> >> source tree. If work is supposed to be landed as a series of changes which 
> >> depend on each other (e.g. refactoring and feature based on it, or 
> >> individual separate features touching same parts of code), each change 
> >> needs a separate PR, and, as a consequence, only one of them can be 
> >> efficiently reviewed at the moment of time
> >>  >> >> * Commits in PR represent review iterations or intermediate 
> >> implementation progress
> >>  >> >> * Reviewers' comments are addressed by pushing new commits without 
> >> rewriting history, which works around GitHub's lack of "commit revisions". 
> >> Also this workflow has lower entry barrier for people who haven't mastered 
> >> git yet, as it requires only "git commit" and "git push" without rebases.
> >>  >> >>
> >>  >> >> 2. Workflow 2 - "Rebase" ("cherry-pick")) or "Merge" policy
> >>  >> >>
> >>  >> >> * PR is considered to be a series of atomic changes. If work 
> >> consists of several atomic changes, each commit represent an atomic change
> >>  >> >> * Review iterations are done by fixing commits in place and 
> >> reuploading entire series using force push (of course if review discovers 
> >> that substantial part of work is missing it can be added as a new atomic 
> >> commit to the series)
> >>  >> >> * It's possible to review each commit in the series separately
> >>  >> >> * Workflow requires developers to have more discipline and 
> >> experience with using git rebase for history rewriting. Entry barrier can 
> >> be lowered by providing step by step instructions like e.g. [1].
> >>  >> >
> >>  >> > I really dislike this workflow due to its inherent complexity. Having
> >>  >> > to use Git is enough of a burden already. I don't want to deal with 
> >> an
> >>  >> > extra layer of complexity to deal with.
> >>  >>
> >>  >> There is simplified version of workflow 2 when you have only one 
> >> commit in PR. In this case you can easily edit this single commit with gic 
> >> commit --amend or GUI tools to address review comments. At the same time 
> >> those who are more comfortable with git can use longer patch series.
> >>  >
> >>  > Except that reviewers would still have to review each commit
> >>  > separately, and the time comes to revert someone's patch, we still
> >>  > need to remember how 

Re: [webkit-dev] WebKit Transition to Git

[Konstantin Tokarev]

14.10.2020, 02:01, "Ryosuke Niwa" :
> On Tue, Oct 13, 2020 at 3:53 PM Konstantin Tokarev  wrote:
>>  14.10.2020, 01:45, "Ryosuke Niwa" :
>>  > On Tue, Oct 13, 2020 at 3:40 PM Konstantin Tokarev  
>> wrote:
>>  >> 14.10.2020, 01:30, "Ryosuke Niwa" :
>>  >> > On Tue, Oct 13, 2020 at 2:37 PM Konstantin Tokarev  
>> wrote:
>>  >> >> 13.10.2020, 22:33, "Maciej Stachowiak" :
>>  >> >> >> On Oct 2, 2020, at 10:59 AM, Michael Catanzaro 
>>  wrote:
>>  >> >> >>
>>  >> >> >> On Fri, Oct 2, 2020 at 6:36 pm, Philippe Normand 
>>  wrote:
>>  >> >> >>> Would you also consider preventing merge commits in order to keep 
>> a
>>  >> >> >>> clean mainline branch?
>>  >> >> >>
>>  >> >> >> Big +1 to blocking merge commits. Merge commits in a huge project 
>> like WebKit would make commit archaeology very frustrating. (I assume this 
>> is implied by the monotonic commit identifiers proposal, but it doesn't 
>> exactly say that.)
>>  >> >> >
>>  >> >> > I’m assuming your objection is to regular merges, but how do you 
>> feel about squash merges? Or do you think all PRs should be landed by 
>> rebasing?
>>  >> >>
>>  >> >> I'm not Michael but will add my 2 dollars anyway :)
>>  >> >>
>>  >> >> In these two approaches commits inside PR have different meaning, and 
>> workflow is different.
>>  >> >>
>>  >> >> Below I use a term "atomic change" to describe minimal code change 
>> which is a self-contained work unit with following properties:
>>  >> >> * It implements well-defined task which can be summarized as a short 
>> English sentence (typical soft limit is 60 characters)
>>  >> >> * It doesn't introduce defects (e.g. bugs, compilation breakages, 
>> style errors, typos) which were discovered during review process
>>  >> >> * It doesn't include any code changes unrelated to main topic. This 
>> separation is sometimes subjective, but it's usually recommended to split 
>> refactoring and implementation of feature based on that, bug fix and new 
>> feature, big style change and fix or feature.
>>  >> >>
>>  >> >> AFAIU our current review process has similar requirements to patches 
>> submitted to Bugzilla, though sometimes patches include unrelated changes. 
>> This can be justified by weakness of webkit-patch/Bugzilla tooling which has 
>> no support for patch series, and by fact that SVN doesn't support keeping 
>> local patch series at all.
>>  >> >>
>>  >> >> 1. Workflow 1 - "Squash merge" policy
>>  >> >>
>>  >> >> * Whole PR is considered to be a single atomic change of WebKit 
>> source tree. If work is supposed to be landed as a series of changes which 
>> depend on each other (e.g. refactoring and feature based on it, or 
>> individual separate features touching same parts of code), each change needs 
>> a separate PR, and, as a consequence, only one of them can be efficiently 
>> reviewed at the moment of time
>>  >> >> * Commits in PR represent review iterations or intermediate 
>> implementation progress
>>  >> >> * Reviewers' comments are addressed by pushing new commits without 
>> rewriting history, which works around GitHub's lack of "commit revisions". 
>> Also this workflow has lower entry barrier for people who haven't mastered 
>> git yet, as it requires only "git commit" and "git push" without rebases.
>>  >> >>
>>  >> >> 2. Workflow 2 - "Rebase" ("cherry-pick")) or "Merge" policy
>>  >> >>
>>  >> >> * PR is considered to be a series of atomic changes. If work consists 
>> of several atomic changes, each commit represent an atomic change
>>  >> >> * Review iterations are done by fixing commits in place and 
>> reuploading entire series using force push (of course if review discovers 
>> that substantial part of work is missing it can be added as a new atomic 
>> commit to the series)
>>  >> >> * It's possible to review each commit in the series separately
>>  >> >> * Workflow requires developers to have more discipline and experience 
>> with using git rebase for history rewriting. Entry barrier can be lowered by 
>> providing step by step instructions like e.g. [1].
>>  >> >
>>  >> > I really dislike this workflow due to its inherent complexity. Having
>>  >> > to use Git is enough of a burden already. I don't want to deal with an
>>  >> > extra layer of complexity to deal with.
>>  >>
>>  >> There is simplified version of workflow 2 when you have only one commit 
>> in PR. In this case you can easily edit this single commit with gic commit 
>> --amend or GUI tools to address review comments. At the same time those who 
>> are more comfortable with git can use longer patch series.
>>  >
>>  > Except that reviewers would still have to review each commit
>>  > separately, and the time comes to revert someone's patch, we still
>>  > need to remember how to revert a sequence of commits that belong to a
>>  > single PR.
>>
>>  Workflow 2 assumes that you forget about PR after it was merged and operate
>>  on its commits as equal parts of history.
>>
>>  In this sequence of commits each one can be 

Re: [webkit-dev] WebKit Transition to Git

[Ryosuke Niwa]

On Tue, Oct 13, 2020 at 3:53 PM Konstantin Tokarev  wrote:
>
>
> 14.10.2020, 01:45, "Ryosuke Niwa" :
> > On Tue, Oct 13, 2020 at 3:40 PM Konstantin Tokarev  
> > wrote:
> >>  14.10.2020, 01:30, "Ryosuke Niwa" :
> >>  > On Tue, Oct 13, 2020 at 2:37 PM Konstantin Tokarev  
> >> wrote:
> >>  >> 13.10.2020, 22:33, "Maciej Stachowiak" :
> >>  >> >> On Oct 2, 2020, at 10:59 AM, Michael Catanzaro 
> >>  wrote:
> >>  >> >>
> >>  >> >> On Fri, Oct 2, 2020 at 6:36 pm, Philippe Normand  
> >> wrote:
> >>  >> >>> Would you also consider preventing merge commits in order to keep a
> >>  >> >>> clean mainline branch?
> >>  >> >>
> >>  >> >> Big +1 to blocking merge commits. Merge commits in a huge project 
> >> like WebKit would make commit archaeology very frustrating. (I assume this 
> >> is implied by the monotonic commit identifiers proposal, but it doesn't 
> >> exactly say that.)
> >>  >> >
> >>  >> > I’m assuming your objection is to regular merges, but how do you 
> >> feel about squash merges? Or do you think all PRs should be landed by 
> >> rebasing?
> >>  >>
> >>  >> I'm not Michael but will add my 2 dollars anyway :)
> >>  >>
> >>  >> In these two approaches commits inside PR have different meaning, and 
> >> workflow is different.
> >>  >>
> >>  >> Below I use a term "atomic change" to describe minimal code change 
> >> which is a self-contained work unit with following properties:
> >>  >> * It implements well-defined task which can be summarized as a short 
> >> English sentence (typical soft limit is 60 characters)
> >>  >> * It doesn't introduce defects (e.g. bugs, compilation breakages, 
> >> style errors, typos) which were discovered during review process
> >>  >> * It doesn't include any code changes unrelated to main topic. This 
> >> separation is sometimes subjective, but it's usually recommended to split 
> >> refactoring and implementation of feature based on that, bug fix and new 
> >> feature, big style change and fix or feature.
> >>  >>
> >>  >> AFAIU our current review process has similar requirements to patches 
> >> submitted to Bugzilla, though sometimes patches include unrelated changes. 
> >> This can be justified by weakness of webkit-patch/Bugzilla tooling which 
> >> has no support for patch series, and by fact that SVN doesn't support 
> >> keeping local patch series at all.
> >>  >>
> >>  >> 1. Workflow 1 - "Squash merge" policy
> >>  >>
> >>  >> * Whole PR is considered to be a single atomic change of WebKit source 
> >> tree. If work is supposed to be landed as a series of changes which depend 
> >> on each other (e.g. refactoring and feature based on it, or individual 
> >> separate features touching same parts of code), each change needs a 
> >> separate PR, and, as a consequence, only one of them can be efficiently 
> >> reviewed at the moment of time
> >>  >> * Commits in PR represent review iterations or intermediate 
> >> implementation progress
> >>  >> * Reviewers' comments are addressed by pushing new commits without 
> >> rewriting history, which works around GitHub's lack of "commit revisions". 
> >> Also this workflow has lower entry barrier for people who haven't mastered 
> >> git yet, as it requires only "git commit" and "git push" without rebases.
> >>  >>
> >>  >> 2. Workflow 2 - "Rebase" ("cherry-pick")) or "Merge" policy
> >>  >>
> >>  >> * PR is considered to be a series of atomic changes. If work consists 
> >> of several atomic changes, each commit represent an atomic change
> >>  >> * Review iterations are done by fixing commits in place and 
> >> reuploading entire series using force push (of course if review discovers 
> >> that substantial part of work is missing it can be added as a new atomic 
> >> commit to the series)
> >>  >> * It's possible to review each commit in the series separately
> >>  >> * Workflow requires developers to have more discipline and experience 
> >> with using git rebase for history rewriting. Entry barrier can be lowered 
> >> by providing step by step instructions like e.g. [1].
> >>  >
> >>  > I really dislike this workflow due to its inherent complexity. Having
> >>  > to use Git is enough of a burden already. I don't want to deal with an
> >>  > extra layer of complexity to deal with.
> >>
> >>  There is simplified version of workflow 2 when you have only one commit 
> >> in PR. In this case you can easily edit this single commit with gic commit 
> >> --amend or GUI tools to address review comments. At the same time those 
> >> who are more comfortable with git can use longer patch series.
> >
> > Except that reviewers would still have to review each commit
> > separately, and the time comes to revert someone's patch, we still
> > need to remember how to revert a sequence of commits that belong to a
> > single PR.
>
> Workflow 2 assumes that you forget about PR after it was merged and operate
> on its commits as equal parts of history.
>
> In this sequence of commits each one can be reverted on their own merits,
> like 

Re: [webkit-dev] WebKit Transition to Git

[Ryosuke Niwa]

On Tue, Oct 13, 2020 at 3:19 PM Michael Catanzaro  wrote:
>
> Detailed descriptions are very important. I don't think function-level
> changelogs are; documenting changes in individual functions is
> generally busywork to say what you can plainly see by just looking at
> the diff.

They certainly can be quite informative. e.g.
https://trac.webkit.org/changeset/268365/webkit/trunk/Source/WebCore/ChangeLog

It's true that you can certainly split each logical step into its own
commit but that seems like more of a busy work to me. I mostly use a
Subversion checkout to do my work, and even if I'm using a Git clone,
I normally wouldn't commit anything until the whole patch is written.
e.g. I wrote the entirety of https://trac.webkit.org/r268239 and
posted in one chunk other than a few WIP patches I had posted. Having
to go back & split that into multiple commits would be a total waste
of time.

> Regarding line-by-line commit review... well, it would be nice to have,
> of course.  But I don't think it's as important as you suggest.
> Problems with commit messages are usually general problems with the
> entire commit message rather than problems with a specific line of the
> commit message.

I disagree. I often have specific commentary on specific lines of
change logs like missing function-level comments or typos, or need
some elaboration on specific details.

- R. Niwa
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Konstantin Tokarev]

14.10.2020, 01:45, "Ryosuke Niwa" :
> On Tue, Oct 13, 2020 at 3:40 PM Konstantin Tokarev  wrote:
>>  14.10.2020, 01:30, "Ryosuke Niwa" :
>>  > On Tue, Oct 13, 2020 at 2:37 PM Konstantin Tokarev  
>> wrote:
>>  >> 13.10.2020, 22:33, "Maciej Stachowiak" :
>>  >> >> On Oct 2, 2020, at 10:59 AM, Michael Catanzaro  
>> wrote:
>>  >> >>
>>  >> >> On Fri, Oct 2, 2020 at 6:36 pm, Philippe Normand  
>> wrote:
>>  >> >>> Would you also consider preventing merge commits in order to keep a
>>  >> >>> clean mainline branch?
>>  >> >>
>>  >> >> Big +1 to blocking merge commits. Merge commits in a huge project 
>> like WebKit would make commit archaeology very frustrating. (I assume this 
>> is implied by the monotonic commit identifiers proposal, but it doesn't 
>> exactly say that.)
>>  >> >
>>  >> > I’m assuming your objection is to regular merges, but how do you feel 
>> about squash merges? Or do you think all PRs should be landed by rebasing?
>>  >>
>>  >> I'm not Michael but will add my 2 dollars anyway :)
>>  >>
>>  >> In these two approaches commits inside PR have different meaning, and 
>> workflow is different.
>>  >>
>>  >> Below I use a term "atomic change" to describe minimal code change which 
>> is a self-contained work unit with following properties:
>>  >> * It implements well-defined task which can be summarized as a short 
>> English sentence (typical soft limit is 60 characters)
>>  >> * It doesn't introduce defects (e.g. bugs, compilation breakages, style 
>> errors, typos) which were discovered during review process
>>  >> * It doesn't include any code changes unrelated to main topic. This 
>> separation is sometimes subjective, but it's usually recommended to split 
>> refactoring and implementation of feature based on that, bug fix and new 
>> feature, big style change and fix or feature.
>>  >>
>>  >> AFAIU our current review process has similar requirements to patches 
>> submitted to Bugzilla, though sometimes patches include unrelated changes. 
>> This can be justified by weakness of webkit-patch/Bugzilla tooling which has 
>> no support for patch series, and by fact that SVN doesn't support keeping 
>> local patch series at all.
>>  >>
>>  >> 1. Workflow 1 - "Squash merge" policy
>>  >>
>>  >> * Whole PR is considered to be a single atomic change of WebKit source 
>> tree. If work is supposed to be landed as a series of changes which depend 
>> on each other (e.g. refactoring and feature based on it, or individual 
>> separate features touching same parts of code), each change needs a separate 
>> PR, and, as a consequence, only one of them can be efficiently reviewed at 
>> the moment of time
>>  >> * Commits in PR represent review iterations or intermediate 
>> implementation progress
>>  >> * Reviewers' comments are addressed by pushing new commits without 
>> rewriting history, which works around GitHub's lack of "commit revisions". 
>> Also this workflow has lower entry barrier for people who haven't mastered 
>> git yet, as it requires only "git commit" and "git push" without rebases.
>>  >>
>>  >> 2. Workflow 2 - "Rebase" ("cherry-pick")) or "Merge" policy
>>  >>
>>  >> * PR is considered to be a series of atomic changes. If work consists of 
>> several atomic changes, each commit represent an atomic change
>>  >> * Review iterations are done by fixing commits in place and reuploading 
>> entire series using force push (of course if review discovers that 
>> substantial part of work is missing it can be added as a new atomic commit 
>> to the series)
>>  >> * It's possible to review each commit in the series separately
>>  >> * Workflow requires developers to have more discipline and experience 
>> with using git rebase for history rewriting. Entry barrier can be lowered by 
>> providing step by step instructions like e.g. [1].
>>  >
>>  > I really dislike this workflow due to its inherent complexity. Having
>>  > to use Git is enough of a burden already. I don't want to deal with an
>>  > extra layer of complexity to deal with.
>>
>>  There is simplified version of workflow 2 when you have only one commit in 
>> PR. In this case you can easily edit this single commit with gic commit 
>> --amend or GUI tools to address review comments. At the same time those who 
>> are more comfortable with git can use longer patch series.
>
> Except that reviewers would still have to review each commit
> separately, and the time comes to revert someone's patch, we still
> need to remember how to revert a sequence of commits that belong to a
> single PR.

Workflow 2 assumes that you forget about PR after it was merged and operate
on its commits as equal parts of history.

In this sequence of commits each one can be reverted on their own merits,
like separate (but consequential) Bugzilla patches in current workflow.
Sometimes it's not possible to revert one patch without reverting a few others
or solving conflicts, but you rarely think about reverting a whole range of
patches unless it becomes 

Re: [webkit-dev] WebKit Transition to Git

[Ryosuke Niwa]

On Tue, Oct 13, 2020 at 3:40 PM Konstantin Tokarev  wrote:
>
> 14.10.2020, 01:30, "Ryosuke Niwa" :
> > On Tue, Oct 13, 2020 at 2:37 PM Konstantin Tokarev  
> > wrote:
> >>  13.10.2020, 22:33, "Maciej Stachowiak" :
> >>  >> On Oct 2, 2020, at 10:59 AM, Michael Catanzaro  
> >> wrote:
> >>  >>
> >>  >> On Fri, Oct 2, 2020 at 6:36 pm, Philippe Normand  
> >> wrote:
> >>  >>> Would you also consider preventing merge commits in order to keep a
> >>  >>> clean mainline branch?
> >>  >>
> >>  >> Big +1 to blocking merge commits. Merge commits in a huge project like 
> >> WebKit would make commit archaeology very frustrating. (I assume this is 
> >> implied by the monotonic commit identifiers proposal, but it doesn't 
> >> exactly say that.)
> >>  >
> >>  > I’m assuming your objection is to regular merges, but how do you feel 
> >> about squash merges? Or do you think all PRs should be landed by rebasing?
> >>
> >>  I'm not Michael but will add my 2 dollars anyway :)
> >>
> >>  In these two approaches commits inside PR have different meaning, and 
> >> workflow is different.
> >>
> >>  Below I use a term "atomic change" to describe minimal code change which 
> >> is a self-contained work unit with following properties:
> >>  * It implements well-defined task which can be summarized as a short 
> >> English sentence (typical soft limit is 60 characters)
> >>  * It doesn't introduce defects (e.g. bugs, compilation breakages, style 
> >> errors, typos) which were discovered during review process
> >>  * It doesn't include any code changes unrelated to main topic. This 
> >> separation is sometimes subjective, but it's usually recommended to split 
> >> refactoring and implementation of feature based on that, bug fix and new 
> >> feature, big style change and fix or feature.
> >>
> >>  AFAIU our current review process has similar requirements to patches 
> >> submitted to Bugzilla, though sometimes patches include unrelated changes. 
> >> This can be justified by weakness of webkit-patch/Bugzilla tooling which 
> >> has no support for patch series, and by fact that SVN doesn't support 
> >> keeping local patch series at all.
> >>
> >>  1. Workflow 1 - "Squash merge" policy
> >>
> >>  * Whole PR is considered to be a single atomic change of WebKit source 
> >> tree. If work is supposed to be landed as a series of changes which depend 
> >> on each other (e.g. refactoring and feature based on it, or individual 
> >> separate features touching same parts of code), each change needs a 
> >> separate PR, and, as a consequence, only one of them can be efficiently 
> >> reviewed at the moment of time
> >>  * Commits in PR represent review iterations or intermediate 
> >> implementation progress
> >>  * Reviewers' comments are addressed by pushing new commits without 
> >> rewriting history, which works around GitHub's lack of "commit revisions". 
> >> Also this workflow has lower entry barrier for people who haven't mastered 
> >> git yet, as it requires only "git commit" and "git push" without rebases.
> >>
> >>  2. Workflow 2 - "Rebase" ("cherry-pick")) or "Merge" policy
> >>
> >>  * PR is considered to be a series of atomic changes. If work consists of 
> >> several atomic changes, each commit represent an atomic change
> >>  * Review iterations are done by fixing commits in place and reuploading 
> >> entire series using force push (of course if review discovers that 
> >> substantial part of work is missing it can be added as a new atomic commit 
> >> to the series)
> >>  * It's possible to review each commit in the series separately
> >>  * Workflow requires developers to have more discipline and experience 
> >> with using git rebase for history rewriting. Entry barrier can be lowered 
> >> by providing step by step instructions like e.g. [1].
> >
> > I really dislike this workflow due to its inherent complexity. Having
> > to use Git is enough of a burden already. I don't want to deal with an
> > extra layer of complexity to deal with.
>
> There is simplified version of workflow 2 when you have only one commit in 
> PR. In this case you can easily edit this single commit with gic commit 
> --amend or GUI tools to address review comments. At the same time those who 
> are more comfortable with git can use longer patch series.

Except that reviewers would still have to review each commit
separately, and the time comes to revert someone's patch, we still
need to remember how to revert a sequence of commits that belong to a
single PR.

I don't feel comfortable accepting this level of new complexity into
our contribution process in addition to being forced to use Git &
GitHub.

- R. Niwa
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Ryosuke Niwa]

On Tue, Oct 13, 2020 at 3:19 PM Michael Catanzaro  wrote:
>
> I suppose what I'm describing is Konstantin's Workflow 2, which is
> overwhelmingly popular.
>
> On Tue, Oct 13, 2020 at 2:19 pm, Ryosuke Niwa  wrote:
> > Not squashing only helps if each commit can stand on its own. At that
> > point, I'd suggest such a sequence of commits be made into multiple
> > PRs instead of multiple commits in a single PR, each of which requires
> > a separate code review.
>
> Commits are certainly expected to stand on their own (not introduce
> defects). If they can't, then they should be combined into another
> commit! Hence, we should not approve MRs if the MR contains commits
> that fail to meet our usual standards. Such commits should just fail
> code review. (But if you aren't willing to review MRs commit-by-commit,
> then indeed you'll never notice when such problems exist.)

Right, so this will be a problem unless we're gonna review each commit
separately. But if we're doing that, we might as well as create a
separate PR for each commit.

If we have 5-10 separate commits each of which make substantial
changes, we don't all of them to be landed / merged all at once into
the main branch even if they're logically related. Without
intermediate test runs & perf test results, we wouldn't be able to
pin-point what caused it, in which case, we'd be likely forced to
revert all of them anyway.

Furthermore, reverting a part of a sequence of commits coming from a
single PR would be very confusing just reverting just one of many
patches posted on Bugzilla would be confusing.

For all these reasons, I don't see much benefit in allowing multiple
commits from being merged from PR.

> If I have to open a separate MR for each change, though, I'm going to
> wind up combining multiple lightly-related changes into one big commit,
> because a new MR for every tiny cleanup I want to make requires effort.
> Such commits may be common in WebKit, but they would fail code review
> in most other open source projects. E.g. in
> https://trac.webkit.org/changeset/268394/webkit I snuck in a drive-by
> one-line fix that's unrelated to the rest of the commit. I would rarely
> dare to do that outside WebKit, knowing it would probably fail review,
> but we do it commonly in WebKit because we discourage multiple patches
> per bug and don't want to create new bugs for every small cleanup.

That seems totally okay. I land one line fix like that all the time though.

> > This to me is a show stopper. When I'm trying to bisect an issue,
> > etc..., the biggest obstacle I face is any intermediate revisions
> > where builds are broken or otherwise non-functional. I don't think we
> > should let anyone merge a commit into the main branch unless the
> > commit meets the same standards as a regular Bugzilla patch we land
> > today.
>
> I agree. But I would say that a MR with such history should fail
> review, and be rewritten to not suffer from these problems.

The problem is that you're presuming that all WebKit reviewers would
be able to and would be willing to do that review. I certainly do not
feel comfortable having to do that given how troublesome it has been
in WPT land.

- R. Niwa
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Konstantin Tokarev]

14.10.2020, 01:30, "Ryosuke Niwa" :
> On Tue, Oct 13, 2020 at 2:37 PM Konstantin Tokarev  wrote:
>>  13.10.2020, 22:33, "Maciej Stachowiak" :
>>  >> On Oct 2, 2020, at 10:59 AM, Michael Catanzaro  
>> wrote:
>>  >>
>>  >> On Fri, Oct 2, 2020 at 6:36 pm, Philippe Normand  
>> wrote:
>>  >>> Would you also consider preventing merge commits in order to keep a
>>  >>> clean mainline branch?
>>  >>
>>  >> Big +1 to blocking merge commits. Merge commits in a huge project like 
>> WebKit would make commit archaeology very frustrating. (I assume this is 
>> implied by the monotonic commit identifiers proposal, but it doesn't exactly 
>> say that.)
>>  >
>>  > I’m assuming your objection is to regular merges, but how do you feel 
>> about squash merges? Or do you think all PRs should be landed by rebasing?
>>
>>  I'm not Michael but will add my 2 dollars anyway :)
>>
>>  In these two approaches commits inside PR have different meaning, and 
>> workflow is different.
>>
>>  Below I use a term "atomic change" to describe minimal code change which is 
>> a self-contained work unit with following properties:
>>  * It implements well-defined task which can be summarized as a short 
>> English sentence (typical soft limit is 60 characters)
>>  * It doesn't introduce defects (e.g. bugs, compilation breakages, style 
>> errors, typos) which were discovered during review process
>>  * It doesn't include any code changes unrelated to main topic. This 
>> separation is sometimes subjective, but it's usually recommended to split 
>> refactoring and implementation of feature based on that, bug fix and new 
>> feature, big style change and fix or feature.
>>
>>  AFAIU our current review process has similar requirements to patches 
>> submitted to Bugzilla, though sometimes patches include unrelated changes. 
>> This can be justified by weakness of webkit-patch/Bugzilla tooling which has 
>> no support for patch series, and by fact that SVN doesn't support keeping 
>> local patch series at all.
>>
>>  1. Workflow 1 - "Squash merge" policy
>>
>>  * Whole PR is considered to be a single atomic change of WebKit source 
>> tree. If work is supposed to be landed as a series of changes which depend 
>> on each other (e.g. refactoring and feature based on it, or individual 
>> separate features touching same parts of code), each change needs a separate 
>> PR, and, as a consequence, only one of them can be efficiently reviewed at 
>> the moment of time
>>  * Commits in PR represent review iterations or intermediate implementation 
>> progress
>>  * Reviewers' comments are addressed by pushing new commits without 
>> rewriting history, which works around GitHub's lack of "commit revisions". 
>> Also this workflow has lower entry barrier for people who haven't mastered 
>> git yet, as it requires only "git commit" and "git push" without rebases.
>>
>>  2. Workflow 2 - "Rebase" ("cherry-pick")) or "Merge" policy
>>
>>  * PR is considered to be a series of atomic changes. If work consists of 
>> several atomic changes, each commit represent an atomic change
>>  * Review iterations are done by fixing commits in place and reuploading 
>> entire series using force push (of course if review discovers that 
>> substantial part of work is missing it can be added as a new atomic commit 
>> to the series)
>>  * It's possible to review each commit in the series separately
>>  * Workflow requires developers to have more discipline and experience with 
>> using git rebase for history rewriting. Entry barrier can be lowered by 
>> providing step by step instructions like e.g. [1].
>
> I really dislike this workflow due to its inherent complexity. Having
> to use Git is enough of a burden already. I don't want to deal with an
> extra layer of complexity to deal with.

There is simplified version of workflow 2 when you have only one commit in PR. 
In this case you can easily edit this single commit with gic commit --amend or 
GUI tools to address review comments. At the same time those who are more 
comfortable with git can use longer patch series.


-- 
Regards,
Konstantin
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Ryosuke Niwa]

On Tue, Oct 13, 2020 at 2:37 PM Konstantin Tokarev  wrote:
>
>
> 13.10.2020, 22:33, "Maciej Stachowiak" :
> >>  On Oct 2, 2020, at 10:59 AM, Michael Catanzaro  
> >> wrote:
> >>
> >>  On Fri, Oct 2, 2020 at 6:36 pm, Philippe Normand  wrote:
> >>>  Would you also consider preventing merge commits in order to keep a
> >>>  clean mainline branch?
> >>
> >>  Big +1 to blocking merge commits. Merge commits in a huge project like 
> >> WebKit would make commit archaeology very frustrating. (I assume this is 
> >> implied by the monotonic commit identifiers proposal, but it doesn't 
> >> exactly say that.)
> >
> > I’m assuming your objection is to regular merges, but how do you feel about 
> > squash merges? Or do you think all PRs should be landed by rebasing?
>
> I'm not Michael but will add my 2 dollars anyway :)
>
> In these two approaches commits inside PR have different meaning, and 
> workflow is different.
>
> Below I use a term "atomic change" to describe minimal code change which is a 
> self-contained work unit with following properties:
> * It implements well-defined task which can be summarized as a short English 
> sentence (typical soft limit is 60 characters)
> * It doesn't introduce defects (e.g. bugs, compilation breakages, style 
> errors, typos) which were discovered during review process
> * It doesn't include any code changes unrelated to main topic. This 
> separation is sometimes subjective, but it's usually recommended to split 
> refactoring and implementation of feature based on that, bug fix and new 
> feature, big style change and fix or feature.
>
> AFAIU our current review process has similar requirements to patches 
> submitted to Bugzilla, though sometimes patches include unrelated changes. 
> This can be justified by weakness of webkit-patch/Bugzilla tooling which has 
> no support for patch series, and by fact that SVN doesn't support keeping 
> local patch series at all.
>
> 1. Workflow 1 - "Squash merge" policy
>
> * Whole PR is considered to be a single atomic change of WebKit source tree. 
> If work is supposed to be landed as a series of changes which depend on each 
> other (e.g. refactoring and feature based on it, or individual separate 
> features touching same parts of code), each change needs a separate PR, and, 
> as a consequence, only one of them can be efficiently reviewed at the moment 
> of time
> * Commits in PR represent review iterations or intermediate implementation 
> progress
> * Reviewers' comments are addressed by pushing new commits without rewriting 
> history, which works around GitHub's lack of "commit revisions". Also this 
> workflow has lower entry barrier for people who haven't mastered git yet, as 
> it requires only "git commit" and "git push" without rebases.
>
> 2. Workflow 2 - "Rebase" ("cherry-pick")) or "Merge" policy
>
> * PR is considered to be a series of atomic changes. If work consists of 
> several atomic changes, each commit represent an atomic change
> * Review iterations are done by fixing commits in place and reuploading 
> entire series using force push (of course if review discovers that 
> substantial part of work is missing it can be added as a new atomic commit to 
> the series)
> * It's possible to review each commit in the series separately
> * Workflow requires developers to have more discipline and experience with 
> using git rebase for history rewriting. Entry barrier can be lowered by 
> providing step by step instructions like e.g. [1].

I really dislike this workflow due to its inherent complexity. Having
to use Git is enough of a burden already. I don't want to deal with an
extra layer of complexity to deal with.

- R. Niwa
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Michael Catanzaro]

I suppose what I'm describing is Konstantin's Workflow 2, which is 
overwhelmingly popular.


On Tue, Oct 13, 2020 at 2:19 pm, Ryosuke Niwa  wrote:

Not squashing only helps if each commit can stand on its own. At that
point, I'd suggest such a sequence of commits be made into multiple
PRs instead of multiple commits in a single PR, each of which requires
a separate code review.


Commits are certainly expected to stand on their own (not introduce 
defects). If they can't, then they should be combined into another 
commit! Hence, we should not approve MRs if the MR contains commits 
that fail to meet our usual standards. Such commits should just fail 
code review. (But if you aren't willing to review MRs commit-by-commit, 
then indeed you'll never notice when such problems exist.)


If I have to open a separate MR for each change, though, I'm going to 
wind up combining multiple lightly-related changes into one big commit, 
because a new MR for every tiny cleanup I want to make requires effort. 
Such commits may be common in WebKit, but they would fail code review 
in most other open source projects. E.g. in 
https://trac.webkit.org/changeset/268394/webkit I snuck in a drive-by 
one-line fix that's unrelated to the rest of the commit. I would rarely 
dare to do that outside WebKit, knowing it would probably fail review, 
but we do it commonly in WebKit because we discourage multiple patches 
per bug and don't want to create new bugs for every small cleanup.



This to me is a show stopper. When I'm trying to bisect an issue,
etc..., the biggest obstacle I face is any intermediate revisions
where builds are broken or otherwise non-functional. I don't think we
should let anyone merge a commit into the main branch unless the
commit meets the same standards as a regular Bugzilla patch we land
today.


I agree. But I would say that a MR with such history should fail 
review, and be rewritten to not suffer from these problems.



I disagree. Detailed descriptions and function-level change logs are
exactly what I use to dig up all the code history and figure out
what's causing the bug and how to fix in numerous occasions. Not
having that would be a massive regression.

- R. Niwa


Detailed descriptions are very important. I don't think function-level 
changelogs are; documenting changes in individual functions is 
generally busywork to say what you can plainly see by just looking at 
the diff. I'll submit 
https://gitlab.gnome.org/GNOME/glib/-/merge_requests/1686/commits as an 
example of my preferred commit granularity and verbosity. (We can 
pretend it is not currently failing CI. ;) Here the commits are 
lightly-related and could perhaps be split into multiple MRs, but 
honestly that becomes annoying and unwieldy, especially as some of the 
commits depend on each other and need to land in a particular order, 
and since creating new branches and MRs (or bugs on Bugzilla) for each 
commit becomes annoying. So it's nicer to do it all in one. One of 
these commits actually makes changes that are undone by a subsequent 
commit, and is primarily there just so that I could write a commit 
message about it and show the history in two steps rather than one! 
History like that would be lost in Konstantin's Workflow 1. I don't 
think ChangeLog-style function-level detail would be helpful in any of 
them; in WebKit, I usually ignore that anyway. But all of the commits 
do have a detailed commit message, except for "fix typo" and "fix 
whitespace" (can't expect an essay for those).


Regarding line-by-line commit review... well, it would be nice to have, 
of course.  But I don't think it's as important as you suggest. 
Problems with commit messages are usually general problems with the 
entire commit message rather than problems with a specific line of the 
commit message. An exception is typos. It is harder to point out typos 
without a line-by-line review tool. But still, it's not too hard to 
tell somebody to fix a typo without being able to highlight the right 
line.


Michael


___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Konstantin Tokarev]

13.10.2020, 22:33, "Maciej Stachowiak" :
>>  On Oct 2, 2020, at 10:59 AM, Michael Catanzaro  wrote:
>>
>>  On Fri, Oct 2, 2020 at 6:36 pm, Philippe Normand  wrote:
>>>  Would you also consider preventing merge commits in order to keep a
>>>  clean mainline branch?
>>
>>  Big +1 to blocking merge commits. Merge commits in a huge project like 
>> WebKit would make commit archaeology very frustrating. (I assume this is 
>> implied by the monotonic commit identifiers proposal, but it doesn't exactly 
>> say that.)
>
> I’m assuming your objection is to regular merges, but how do you feel about 
> squash merges? Or do you think all PRs should be landed by rebasing?

I'm not Michael but will add my 2 dollars anyway :)

In these two approaches commits inside PR have different meaning, and workflow 
is different.

Below I use a term "atomic change" to describe minimal code change which is a 
self-contained work unit with following properties:
* It implements well-defined task which can be summarized as a short English 
sentence (typical soft limit is 60 characters)
* It doesn't introduce defects (e.g. bugs, compilation breakages, style errors, 
typos) which were discovered during review process
* It doesn't include any code changes unrelated to main topic. This separation 
is sometimes subjective, but it's usually recommended to split refactoring and 
implementation of feature based on that, bug fix and new feature, big style 
change and fix or feature.

AFAIU our current review process has similar requirements to patches submitted 
to Bugzilla, though sometimes patches include unrelated changes. This can be 
justified by weakness of webkit-patch/Bugzilla tooling which has no support for 
patch series, and by fact that SVN doesn't support keeping local patch series 
at all.

1. Workflow 1 - "Squash merge" policy

* Whole PR is considered to be a single atomic change of WebKit source tree. If 
work is supposed to be landed as a series of changes which depend on each other 
(e.g. refactoring and feature based on it, or individual separate features 
touching same parts of code), each change needs a separate PR, and, as a 
consequence, only one of them can be efficiently reviewed at the moment of time
* Commits in PR represent review iterations or intermediate implementation 
progress
* Reviewers' comments are addressed by pushing new commits without rewriting 
history, which works around GitHub's lack of "commit revisions". Also this 
workflow has lower entry barrier for people who haven't mastered git yet, as it 
requires only "git commit" and "git push" without rebases.

2. Workflow 2 - "Rebase" ("cherry-pick")) or "Merge" policy

* PR is considered to be a series of atomic changes. If work consists of 
several atomic changes, each commit represent an atomic change
* Review iterations are done by fixing commits in place and reuploading entire 
series using force push (of course if review discovers that substantial part of 
work is missing it can be added as a new atomic commit to the series)
* It's possible to review each commit in the series separately
* Workflow requires developers to have more discipline and experience with 
using git rebase for history rewriting. Entry barrier can be lowered by 
providing step by step instructions like e.g. [1]. 


Workflow 1 is more like what we have now with Bugzilla.

Workflow 2 is used by many projects which use git for a long time and value 
high-quality commit history. It's used e.g. by Linux kernel, or projects which 
use Gerrit as a review tool (Chromium, Android, Qt, etc). It advantages for 
developers (who can submit more work to review at the same time without risk of 
mixing up unrelated changes together), reviewers (it's easier to review atomic 
changes than those with too high or too low granularity), maintainers of stable 
branches (they can pick bug reports and avoid at least some unneeded 
refactorings, features and style improvements).

Workflow 1 is the most obvious way to use GitHub, because it doesn't make any 
hints about existence of workflow 2. However, many projects which use GitHub 
for code review and value high-quality history are using workflow 2. For 
example, see Ryosuke's example with whatwg/html repo.

Workflow 2 is facilitated by Gerrit, which doesn't require using force pushes 
and makes it immediately obvious for new user if they start adding new fixup 
commits instead of editing those being reviewed.

Workflow 2 can use both rebase and merge strategies, and merge isn't so evil in 
this case. However, using merge moves responsibility for solving conflicts from 
contributor to repository maintainers, which doesn't scale well. Projects which 
accept patches via mailing lists, like Linux kernel, imply that reviewed patch 
series must apply to the tip of the tree, so while there is no explicit 
"rebase" it is implied.

In conclusion, I recommend using 2 with "rebase" policy, but YMMV.

[1] 

Re: [webkit-dev] WebKit Transition to Git

[Ryosuke Niwa]

On Tue, Oct 13, 2020 at 1:57 PM Michael Catanzaro  wrote:
>
> On Tue, Oct 13, 2020 at 12:32 pm, Maciej Stachowiak 
> wrote:
> > I’m assuming your objection is to regular merges, but how do you
> > feel about squash merges? Or do you think all PRs should be landed by
> > rebasing?
>
> If we want a linear history (we do), all PRs ultimately have to land as
> fast-forward merges, one way or the other. I think rebasing is the
> simplest way to accomplish that, but squashes work too if all your
> changes are sufficiently self-contained to land as one commit.
>
> I suggest leaving this up to the discretion of the developer and
> reviewer rather than mandating one way or the other, because there are
> advantages and disadvantages to both approaches. If your local commit
> history is a mess, sometimes squashing it all into one commit is an
> easy way to make it acceptable for upstream. If you hate rewriting
> history to make it look good, and your MR isn't too huge, a squash
> might be appropriate. But more often than not, I'd say that would
> result in a worse commit history.

FWIW, I think we should always squash all commits and have a single
change log entry / commit message for all changes.

In the case we want to rebase and keep multiple commits, then we
should have a change log / descriptive commit message that follows the
current change log format for each commit, rather than a short
description of each change.

> > My own preference would be to require squash merge, because it keeps
> > the history simple for the main branch, but does not risk putting
> > intermediate revisions which may work or even build on the main
> > branch.
>
> The disadvantage is that if you squash before merging, you encourage
> fewer, bigger commits that might be harder to read and potentially much
> less fun to discover at the end of a bisect.

Not squashing only helps if each commit can stand on its own. At that
point, I'd suggest such a sequence of commits be made into multiple
PRs instead of multiple commits in a single PR, each of which requires
a separate code review.

> On the other hand, if you don't squash, it's indeed possible that your
> commit history might be messy, e.g. intermediate commits might break
> tests fixed by subsequent commits, or intermediate commits might not
> build at all.

This to me is a show stopper. When I'm trying to bisect an issue,
etc..., the biggest obstacle I face is any intermediate revisions
where builds are broken or otherwise non-functional. I don't think we
should let anyone merge a commit into the main branch unless the
commit meets the same standards as a regular Bugzilla patch we land
today.

> Sometimes I see the
> opposite, where too many changes are bundled into one big commit. (This
> is more common in WebKit, since we normally try to have one patch per
> bug, and splitting changes into multiple bugs is inconvenient.) But
> usually the developer submitting a MR has found a good balance between
> the two extremes. Ultimately, what's most important is landing a clean
> commit history with reviewable commits. Again, the scope of commits is
> subject to review just like code changes are.

I often review test changes in WPT or spec changes in WHATWG / W3C,
and I often find a PR with multiple commits to be annoying to review.
I'd rather have each PR have a single large commit to review. In
practice, I'd never review commit by commit because I need to see the
whole picture to review what's happening.

> Instead, I suggest
> developers should aggressively use 'git add -p' and 'git rebase -i' to
> selectively commit, rewrite, and reorder history to look good before
> opening the MR. This isn't optional for most open source projects: if
> you propose an MR with ugly commit history, it won't be merged until
> fixed. For a typical MR of moderate complexity, I'll use 'git rebase
> -i' at least a couple times before the history is clean enough for a
> MR, and to make fixup commits disappear into the most-appropriate
> commit in the sequence.

I'm afraid that this will still result in random intermediary commits
being merged into the main branch because there is no mechanical
enforcement.

> Regarding commit messages, I don't understand why there's any
> expectation that they need to be checked into files in order to be
> detailed and complete. If a commit message doesn't adequately describe
> what it's fixing, then the reviewer should open a review thread to
> complain and request more detailed commit messages.

The problem is that I've seen multiple projects which moved to Git and
did this, and their commit log message's quality materially degraded.
If GitHub and other tools allowed inline comments being added for each
line of the commit message, I have less of concern. Github doesn't.

> If a change is very
> straightforward and obvious, sometimes a quick sentence might suffice,
> but usually a good commit message should be at least a paragraph or
> two, and often more. Function-level 

Re: [webkit-dev] WebKit Transition to Git

[Michael Catanzaro]

On Tue, Oct 13, 2020 at 12:32 pm, Maciej Stachowiak  
wrote:
I’m assuming your objection is to regular merges, but how do you 
feel about squash merges? Or do you think all PRs should be landed by 
rebasing?


If we want a linear history (we do), all PRs ultimately have to land as 
fast-forward merges, one way or the other. I think rebasing is the 
simplest way to accomplish that, but squashes work too if all your 
changes are sufficiently self-contained to land as one commit.


I suggest leaving this up to the discretion of the developer and 
reviewer rather than mandating one way or the other, because there are 
advantages and disadvantages to both approaches. If your local commit 
history is a mess, sometimes squashing it all into one commit is an 
easy way to make it acceptable for upstream. If you hate rewriting 
history to make it look good, and your MR isn't too huge, a squash 
might be appropriate. But more often than not, I'd say that would 
result in a worse commit history.


My own preference would be to require squash merge, because it keeps 
the history simple for the main branch, but does not risk putting 
intermediate revisions which may work or even build on the main 
branch.


The disadvantage is that if you squash before merging, you encourage 
fewer, bigger commits that might be harder to read and potentially much 
less fun to discover at the end of a bisect. E.g. consider a very 
common case: developer wants to fix a handful of separate but related 
bugs in a particular section of code. We could land all the fixes in 
one huge commit, but that's inevitably going to be harder to read, 
harder to deal with if it introduces a regression, and will certainly 
have a more confusing commit message (either because it gives less 
detail about the changes, or because it's very long describing multiple 
related changes that could have been separate commits). We could split 
it up into different MRs for the different commits, but that becomes 
annoying when the commits are related, and hard to keep the different 
MRs in order. So I don't normally squash (except when committing small 
fixup commits via the web UI), because the disadvantages generally 
outweigh the benefits.


On the other hand, if you don't squash, it's indeed possible that your 
commit history might be messy, e.g. intermediate commits might break 
tests fixed by subsequent commits, or intermediate commits might not 
build at all. Squashing before merging does eliminate those risks, but 
I recommend code review instead: commit history and style is subject to 
review just like code changes are. Sometimes I see a merge request with 
a messy commit history that just begs for two or more commits to be 
squashed together. (This is common for students new to open source. 
WebKit does not have this problem currently.) Sometimes I see the 
opposite, where too many changes are bundled into one big commit. (This 
is more common in WebKit, since we normally try to have one patch per 
bug, and splitting changes into multiple bugs is inconvenient.) But 
usually the developer submitting a MR has found a good balance between 
the two extremes. Ultimately, what's most important is landing a clean 
commit history with reviewable commits. Again, the scope of commits is 
subject to review just like code changes are.


I agree that we don't want to merge WIP commits of any form, and 
reviewers should complain if these appear in a MR. E.g. if making an 
API change that requires updates in 200 files, we surely want them all 
updated in one commit, because we don't want broken intermediate 
commits on master that would break bisections. So sometimes huge 
commits are unavoidable. Similarly, if an intermediate commit is known 
to break a test, that's not good either because it could mess up 
bisects. (I don't think we necessarily need to run tests on every 
intermediate commit -- that might be too much for our infrastructure -- 
but we could if desired.) What we don't want is to wind up merging 
low-quality stream-of-consciousness style commits that looks like they 
were committed in the order the code was written. I think that's what 
you're trying to avoid by suggesting squashes. Instead, I suggest 
developers should aggressively use 'git add -p' and 'git rebase -i' to 
selectively commit, rewrite, and reorder history to look good before 
opening the MR. This isn't optional for most open source projects: if 
you propose an MR with ugly commit history, it won't be merged until 
fixed. For a typical MR of moderate complexity, I'll use 'git rebase 
-i' at least a couple times before the history is clean enough for a 
MR, and to make fixup commits disappear into the most-appropriate 
commit in the sequence.


Regarding commit messages, I don't understand why there's any 
expectation that they need to be checked into files in order to be 
detailed and complete. If a commit message doesn't adequately describe 
what it's fixing, then the reviewer should open a 

Re: [webkit-dev] WebKit Transition to Git

[Maciej Stachowiak]

e things. We've definitely heard of people
>> complaining or refusing to create a Bugzilla account to report bugs.
>> I've gotta say I'm very much concerned about getting rid of change
>> logs when we move to Git. We put a lot of useful information about
>> what was causing the bug, how we fixed it, and why we fixed the way we
>> did in a change log. I've seen a few projects which transitioned to
>> Git and somehow lost the rigor in maintaining an equally high quality
>> commit message, partly because most code review tools don't let you
>> add inline comments to commit messages.
>> 
>> - R. Niwa
>> ___
>> webkit-dev mailing list
>> webkit-dev@lists.webkit.org <mailto:webkit-dev@lists.webkit.org>
>> https://lists.webkit.org/mailman/listinfo/webkit-dev 
>> <https://lists.webkit.org/mailman/listinfo/webkit-dev>
> ___
> webkit-dev mailing list
> webkit-dev@lists.webkit.org <mailto:webkit-dev@lists.webkit.org>
> https://lists.webkit.org/mailman/listinfo/webkit-dev 
> <https://lists.webkit.org/mailman/listinfo/webkit-dev>
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Maciej Stachowiak]

> On Oct 2, 2020, at 10:59 AM, Michael Catanzaro  wrote:
> 
> On Fri, Oct 2, 2020 at 6:36 pm, Philippe Normand  wrote:
>> Would you also consider preventing merge commits in order to keep a
>> clean mainline branch?
> 
> Big +1 to blocking merge commits. Merge commits in a huge project like WebKit 
> would make commit archaeology very frustrating. (I assume this is implied by 
> the monotonic commit identifiers proposal, but it doesn't exactly say that.)

I’m assuming your objection is to regular merges, but how do you feel about 
squash merges? Or do you think all PRs should be landed by rebasing?

My own preference would be to require squash merge, because it keeps the 
history simple for the main branch, but does not risk putting intermediate 
revisions which may work or even build on the main branch.

 - Maciej

> 
> I'm sure transition to git and GitHub should go well. I would have selected 
> GitLab myself -- it's nicer and also overwhelmingly popular -- but whatever. 
> (Does GitHub have merge request approvals? Replicating our reviewer/owner 
> permissions with GitLab merge request approvals would be easy.)
> 
> One downside is that using github.com might actually make it *too* easy to 
> spam us with low-quality issue reports and merge requests. We've historically 
> been pretty bad at maintaining a clean issue tracker -- the quantity of 
> untriaged issues on Bugzilla is very high -- and GitHub will make this worse. 
> That's not an issue with the GitHub platform, though. Just something to stay 
> on top of.
> 
> Michael
> 
> 
> ___
> webkit-dev mailing list
> webkit-dev@lists.webkit.org
> https://lists.webkit.org/mailman/listinfo/webkit-dev

___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Michael[tm] Smith]

Adrian Perez de Castro , 2020-10-08 00:49 +0300:
> ...
> Also with Git{Hub,Lab} it's an annoyance that one has to go through the web
> interface to create a “pull request”.

But it’s not hard to create tooling that completely eliminates the need to
ever use the GitHub web UI to create pull requests, right? And specifically,
I think we already have some good examples of automating integration of pull-
request creation into existing workflows for browser-project engineers.

https://github.com/web-platform-tests/wpt/pulls for example, is one well-known
place in the overall browser-project world where PR creation is hooked closely
into existing browser-project workflows and automation/CI; specifically:

* https://github.com/web-platform-tests/wpt/pulls/chromium-wpt-export-bot
* https://github.com/web-platform-tests/wpt/pulls/moz-wptsync-bot

Those are the pull-request histories for all tests that have been automatically
upstreamed from the Chromium and Firefox projects to WPT through PRs.

And yeah those are PRs for tests, not browser source-code patches, but it’s easy
to imagine how patch handling too — or any part of a browser-project workflow
that makes use of pull requests — could be integrated into a GitHub repo without
the need for engineers to use the GitHub web UI to do PR creation directly.

  –Mike

P.S. As far as whether it’s ever necessary to use the GitHub web UI for PR
creation even in the general case: I create a lot of GitHub PRs for a
variety of projects, and I pretty much never use the GitHub Web UI to
create them. Instead I just use https://hub.github.com/ from the command
line. And there’s https://cli.github.com/ and other CLI tools for doing it.

-- 
Michael[tm] Smith https://people.w3.org/mike


signature.asc
Description: PGP signature
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Adrian Perez de Castro]

On Tue, 06 Oct 2020 11:15:05 -0700 Jonathan Bedard  wrote:

> Seems like most large projects are using some sort of bot or action to solve
> this problem: https://github.com/isaacs/github/issues/581
> .

Wow, “there's a bot for that” seems to be the “there's an app for that” of
the GitHub ecosystem 

> > On Oct 6, 2020, at 11:07 AM, Michael Catanzaro  wrote:
> > 
> > On Wed, Oct 7, 2020 at 2:22 am, Tetsuharu OHZEKI 
> >  wrote:
> >> If we move to GitHub Issue, compared to bugzilla, that does not have
> >> "component watching".
> >> (I don't know the case of GitLab's Issue)
> >> We only can watch all issues or not for the repository.
> > 
> > Oh dear. I had assumed that you could easily subscribe to particular labels 
> > (as you can in GitLab) but, poking around in GitHub's UI, I indeed don't 
> > see any way to do that. :/
> > 
> > That's no good. E.g. multimedia developers expect to be able to subscribe 
> > only to multimedia bugs, WebKitGTK developers will want to watch only GTK 
> > bugs, etc.
> > 
> > Michael


pgpGPdP1onlz3.pgp
Description: PGP signature
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Adrian Perez de Castro]

Hi there,

There is one more annoyance I am adding below Konstantin's list…

On Tue, 06 Oct 2020 03:13:32 +0300 Konstantin Tokarev 
wrote:
 
> 05.10.2020, 23:41, "Yusuke Suzuki" :
> > I think security component is special in terms of how to handle it already
> > (e.g. not posting a test with the patch etc.) To me, handling non-security
> > issues in GitHub and security issues in Bugzilla is OK.  By nature,
> > security issues are not open. Since one of our motivation of moving to
> > GitHub is openness for feedback collection, security issue in Bugzilla
> > does not matter for this motivation.  Ideally, handling both in GitHub is
> > better. But to me, rather than continuing using Bugzilla, using GitHub for
> > non security issues sounds improvement.
> 
> To me it sounds as a huge step backwards. Asides from situation with
> security issues, it has other significant drawbacks in domain of issue
> triaging and management:
> 
> 1. Sub-par support for linking issues to each other
> 
> 
> Traditional bug tracking systems (like Bugzilla or JIRA) have support of
> "related" or "linked" issues. Most important relations are
> 
> * A depends on B (B blocks A) - blockers and umbrella issues
>
> * B is duplicate of A
>
> * A and B are related in other unspecified way
> 
> All GitHub can offer here now is mentions (and, to some extent, milestones
> for case of "umbrella issues" [1]). Mention is created every time someone
> uses "#" (e.g. "#123") in the text of issue or in the comment, where
> number is a sequential number of issue or pull request [2]. When comment is
> published in issue A which mentions issue B, there is a pseudo-comment added
> to B, and subscribers of B receive email notification.
> 
> At first glance this naive approach seems to work, but
> 
> * There is no easily visible list of relations: if you are not closely
>   following all activity on A, to find all issues related to it you have
>   to browse through all its (pseudo-)comments, which in some cases might
>   be long.
>
> * There is no *stateful* list of relations: if A was believed to have
>   common source with B, but then it was discovered they are not related,
>   you cannot delete relationship between A and B because there is no
>   relationship, just a set of comments.
>
> * "#" is not a safe reference format. Sometimes users' comments
>   may have other data in "#" format with a different
>   meaning than references to GitHub issues. For example, may the force be
>   with you if someone pastes gdb or lldb backtrace into comment without
>   escaping it into markdown raw text block (```). Also, GitHub parses
>   mentions in git commit messages, so care must be taken to avoid any
>   occurrences of "#" with a meaning different from reference to
>   issue number.
> 
> ---
> 
> [1] Milestones are not issues themselves, but they establish true two-way
> stateful relation between issues and their "parent" milestone.  [2] For some
> reason they have shared numbering, which means sometimes you may not know
> what kind of reference is in front of you until you look up its URL or
> navigate
> 
> 
> 2. Sub-par issue categorization and search
> --
> 
> In traditional bug tracking systems every issue has properties like status,
> resolution, component, severity/issue type, priority. When new bug is
> created, user chooses values of these properties, which can be later
> adjusted by the person doing triaging. They also are used in user-friendly
> search dialog like [1].
> 
> All GitHub can offer here are custom labels. While in theory they are
> sufficient to replace pre-defined issue properties, they require disciplined
> use to be efficient, for example issue must not have mutually exclusive
> labels. To avoid chaos, GitHub allows setting issue labels only to
> contributors. However, this puts more work on triagers, and they cannot
> triage only certain kinds of issues which match their interests by going
> through results of search query.
> 
> [1] https://bugs.webkit.org/query.cgi
> 
> 
> 3. Sub-par attachments
> --
> 
> Traditional bug trackers allow attaching files to issue. GitHub goes further
> and allows to attach files to every comment. Enjoy the progress -  now you
> can look for attached test cases and proposed patches through all comment
> feed, instead of having them in one place at the top.
> 
> Also, on test cases. You probably like this feature of Bugzilla when you can
> attach self-contained HTML file to the issue and then simply open it by URL
> in any browser including your build of WebKit to try it out. Forget this -
> GitHub simply forbids HTML or JS attachments (without wrapping them in
> archive):
> 
> "We don’t support that file type. with a GIF, JPEG, JPG, PNG, DOCX, GZ,
> LOG, PDF, PPTX, TXT, XLSX or ZIP."
> 
> And yes, take care not to use tar.xz or tar.bz2 or any other 

Re: [webkit-dev] WebKit Transition to Git

[Adrian Perez de Castro]

On Sun, 04 Oct 2020 02:00:02 +0300 Konstantin Tokarev  wrote:
 
> 03.10.2020, 21:49, "Adrien Destugues" :
> > Yes that's why I didn't elaborate much. Whichever tool you pick, there
> > will always be people unhappy about it.
> 
> Right. For example, I have negative bias against GitLab, because this
> company have bought its open source competitor (Gitorious, which was
> quite popular service those days) just to shut it down.

I personally have negative bias against both GitHub *and* GitLab.

In the case of GitHub, apart of the reasons already mentioned by others,
yesterday I started getting a new popup asking consent to being tracked
even more.

In the case of GitLab, it's a bloated kitchen sink which does not inspire
trust in me when its official documentation has pearls [1] like this:

  “GitLab has memory leaks. These memory leaks manifest themselves in
   long-running processes, such as Unicorn workers. (The Unicorn master
   process is not known to leak memory, probably because it does not
   handle user requests.)

   To make these memory leaks manageable, GitLab comes with the
   unicorn-worker-killer gem. This gem monkey-patches the Unicorn workers to
   do a memory self-check after every 16 requests. If the memory of the
   Unicorn worker exceeds a pre-set limit then the worker process exits. The
   Unicorn master then automatically replaces the worker process.”

Also GitLab has contracts with ICE (like GitHub), and not only explicitly
decided to continue them, but also attempted to silence their employees
on political matters:

  https://www.theregister.com/2019/10/16/gitlab_employees_gagged/
  https://www.theregister.com/2019/10/17/gitlab_reverse_ferret/

Cheers,
—Adrián

---
[1] 
https://docs.gitlab.com/ee/administration/operations/unicorn.html#unicorn-worker-killer


pgp4KjNmxjOrc.pgp
Description: PGP signature
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Adrian Perez de Castro]

Hello,

On Fri, 02 Oct 2020 13:48:56 -0700 Ken Russell  wrote:

> Excited about this migration! One comment inline.
> 
> On Fri, Oct 2, 2020 at 9:43 AM Jonathan Bedard  wrote:
> 
> > *Patches to Pull Requests*
> > In the coming months, more automation will start using the git version of
> > the repository instead of the Subversion version. Even immediately after we
> > switch, the patch review workflow will remain what it is now (EWS bots
> > mostly already use a git clone as their checkout). We do, however, intend
> > to switch from a system of patch review to a system of pull requests. This
> > process will be incremental and the patch review system will remain alive
> > as long as Bugzilla does.
> >
> > *GitHub Issues*
> > The last part of transitioning away from Subversion is to re-evaluate our
> > bug tracker. Bugzilla has served us well, but seems to be an impediment to
> > engaging with the open source community. We are interested in moving away
> > from Bugzilla and to GitHub Issues, allowing new developers to work with a
> > system they are likely already familiar with and to allow us closer
> > integration with repositories managed by W3C. Although GitHub Issues has
> > had performance problems in the past with projects that have many bugs,
> > these performance problems have been resolved to the satisfaction of a few
> > large projects hosted on GitHub that are of a comparable scale to WebKit.
> > The biggest blocker we are aware of is managing security bugs, since the
> > security advisory system used by GitHub is essentially the opposite of how
> > WebKit security bugs work. Moving to GitHub Issues, if it happens, will be
> > the last part of this transition, and we are interested in soliciting
> > feedback from our contributors on what the WebKit project’s integration
> > with GitHub Issues should look like.
> 
> Github's code review UI has a couple of feature gaps in my opinion. It's
> difficult to look at earlier versions of the pull request, in particular to
> verify that issues found during code review have been fixed. I remember it
> also being difficult to figure out whether all comments on earlier versions
> have been addressed.

There is also one annoyance which has been slowly grinding my gears: the
GitHub diff viewer (including in reviews) hides “big diffs” for some arbitrary
and unknown definition of “big”, forcing a reviewer to manually click in a
“Load diff” link, for each hidden diff, every time. In a few cases I ran into
“very big” diffs or diff hunks which could not even be displayed that way and
had to fetch the branch locally to review the changes. Truth be told: it has
been a good while since I haven't found any diff which could not be loaded
at all, so maybe that issue has been fixed by now.

Now, GitLab's diff viewer has its own set of similar-but-not-quite-same
annoyances. Instead of hiding “big” diff hunks, it hides “random” hunks:
typically big ones, but sometimes small ones as well. A positive point for
GitLab is that at least they can always be loaded using that pesky “Load
diff” link.

Why none of Git{Hub,Lab} would have an option “gimme all the diffs” user
option, or at least remember which reviews I visited before where the “Load
diff” links have been used is something inexplicable. Or they could just
show the diffs ¯\_(ツ)_/¯ 

> Gerrit code review has worked well in my experience. It explicitly manages
> different versions of the same patch set, and prominently shows whether all
> code review comments have been addressed.

One point for Gerrit: I never ran into a diff that it would not show.

Regards,
—Adrián


pgpstt94v6F6n.pgp
Description: PGP signature
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Adrian Perez de Castro]

Hello,

On Sun, 04 Oct 2020 01:57:56 -0700 Yusuke Suzuki  wrote:

> GitHub is planning to have review revisions in 2020/Q4.
> So, when WebKit repository is migrated, we already have that in GitHub 
> builtin review tool :)
> 
> https://github.com/github/roadmap/issues/54 
> 

It's not clear from the description in that issue that using a “rebase and
force-push” strategy to update patch sets to be will be supported and that the
differences between versions will be available. Rebases are not mentioned at
all, so I would not count on this workflow working even with the upcoming
improvements in 2020/Q4.
 
> > On Oct 3, 2020, at 5:18 PM, Michael Catanzaro  wrote:
> > 
> > On Sat, Oct 3, 2020 at 9:52 pm, Konstantin Tokarev  
> > wrote:
> >> If I understand correctly, there is no way in GitHub UI to see a 
> >> difference between
> >> patches submitted at step 1 and step 3. It's still possible to see old 
> >> version of patches
> >> if you navigate to old commit hash, but that's not for long as they can be 
> >> garbage
> >> collected by GitHub because they don't belong to git branch anymore.
> > 
> > If we are really seriously concerned about this... it's not a problem with
> > GitLab. At least, I can still view diffs between different revisions of
> > merge requests from two years ago, and the changes seem to be stored
> > forever. At least I still can view diffs from years ago. E.g.:
> > 
> > https://gitlab.gnome.org/GNOME/epiphany/-/merge_requests/62/diffs?diff_id=27669_sha=0c020384b602c9e1f0e8ec9e491d1951e8feadf7
> >
> > Unfortunately it's sometimes less useful than I might have hoped, because
> > rebases bring in a bunch of totally unrelated changes, e.g.:
> >
> > https://gitlab.gnome.org/GNOME/epiphany/-/merge_requests/62/diffs?diff_id=28036_sha=043b5fc32f4f9263d393c9de83e1b33123c5

This is the kind of thing that Gerrit is *designed* to solve :]

Cheers,
—Adrián


pgpd479NRitRQ.pgp
Description: PGP signature
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev

Re: [webkit-dev] WebKit Transition to Git

[Adrian Perez de Castro]

Hi,

On Tue, 06 Oct 2020 03:42:11 +0300 Konstantin Tokarev  wrote:
 
> 05.10.2020, 13:26, "Frédéric Wang" :
> > One thing to take into account is that WebKit's repository is big and
> > public GitHub/GitLab prevent creating large repository by default. This
> > means it might not be possible for contributors to actually fork
> > WebKit's repository on their account and then create a pull request
> > (which is the standard way IIUC).
> 
> Every repository which is already present on GitHub can be forked by
> anyone without any restrictions.
> 
> There are restrictions for repositories which are not forks, e.g. if you
> create new repo on your account and try to push whole WebKit there,
> you'll get an error.
> 
> > Instead, we would probably end up
> > doing like web-platform-tests and give contributors the permission to
> > create branches to the WebKit account and make Pull Request to the
> > master branch. 
> 
> This is not needed and should be avoided - private development branches
> in main repo will confuse users and will be copied into all forks.
 
While I agree that having private development branches in the main repository
can be confusing for people not used to that, OTOH it is awkward to have to
“fork” [1] the repository to one's user area, then add an extra remote to
one's local clone of the upstream (main) repository, just to be able to submit
a “pull request” [2].

Also with Git{Hub,Lab} it's an annoyance that one has to go through the web
interface to create a “pull request”. Being able to do “webkit-patch upload”
saves a non negligible amount of developer time. It is even better with
Gerrit: do “git push” directly to a remote ref and a changeset will be
automatically created for review [3].

> >Probably, we should forbid people to commit to the master
> > branch directly (I think someone broke WPT's master branch that way last
> > year)...
> 
> I have to admit that ability to make small unreviewed commit for thing like 
> typo fix or change in personal watchlist is rather useful...

I suppose this could be solved by still making a “pull request” and tagging
it with some label to be merged automatically by some bot. It won't be as
fast as directly landing a patch, but on the upside all patches (including
unreviewed ones) would be landed in the same way.

As a side note, Gerrit can be configured to allow direct pushes that bypass
the review process.

Cheers,
—Adrián

---
[1] I put “fork” in between quotes because it's a perversion of the term: what
it does is create a clone of the repository in Git{Hub,Lab}'s own servers
which happens to be accessible remotely with one's credentials.
[2] GitHub's usage of the “pull request” term is yet another perversion: Git
has had a pull requests (produced by a command) long before GitHub even
existed, see https://git-scm.com/docs/git-request-pull
[3] 
https://gerrit-documentation.storage.googleapis.com/Documentation/3.2.3/intro-user.html#upload-change


pgpEp7XcmnUrw.pgp
Description: PGP signature
___
webkit-dev mailing list
webkit-dev@lists.webkit.org
https://lists.webkit.org/mailman/listinfo/webkit-dev