I think we need both of these things, and I don't think they should be mutually exclusive. Having motivation/design/details/gotchas go into a "changelog" accompanying a commit is very useful when blaming code.
- Saam > On Apr 18, 2022, at 6:49 PM, Fujii Hironori via webkit-dev > <webkit-dev@lists.webkit.org> wrote: > > > On Tue, Apr 19, 2022 at 6:55 AM Yusuke Suzuki via webkit-dev > <webkit-dev@lists.webkit.org <mailto:webkit-dev@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 > > <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. > > _______________________________________________ > 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
