[webkit-dev] ChangeLog Deprecation Plans

[Ryosuke Niwa]

On Mon, Apr 18, 2022 at 18:50 Fujii Hironori via webkit-dev <
webkit-dev at lists.webkit.org> wrote:

>
> On Tue, Apr 19, 2022 at 6:55 AM Yusuke Suzuki via webkit-dev <
> webkit-dev at lists.webkit.org> wrote:
>
>> I think this is important. We are using commit message / ChangeLog as a
>> document tied to the change, and we are writing very detailed description
>> to make the intention / design of the change clear and making it as a good
>> document when we read the change via git-blame, bisect, using that header,
>> investigating how it works etc.
>> To make / keep this commit message / ChangeLog helpful, we need review,
>> and I think reviewing of these messages is critical to keep usefulness of
>> them.
>>
>
>
> I don't think commit messages and ChangeLogs are the best place for
> technical descriptions.
> We use them because we don't have a better place.
>
> libpas added the technical document in the repository in markdown.
>
> https://github.com/WebKit/WebKit/blob/main/Source/bmalloc/libpas/Documentation.md
>
> This makes it possible to change code and update the document in a single
> commit, and get reviewed.
> markdown is better than plain text. Updated documents are more useful than
> the historical wiki pages.
> It'd be nice if more documents are migrated into the repository.
>

Documentation gets obsolete relatively quickly. Code is the source of
truth. A lot of comments in WebKit are either outdated, incorrect, and/or
misleading. Change logs describe a change and thereby a specific point in
time of the repository and wouldn't carry the same issue.

It's also particularly useful to be able to see why a given line of code
was written. Was it an oversight? On purpose? Or perhaps the required
behavior different then and now? It's impractical and unproductive to add
such a comment on every line of our codebase, and that level of online
comment will add so much clutter to the codebase and would make it harder
to read the code.

- R. Niwa
-- 
- R. Niwa
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20220418/a16d5ec7/attachment.htm>