Hi Ian, On 8/25/24 2:06 오후, Ian Rogers wrote: > On Fri, Aug 9, 2024 at 10:11 PM Yunseong Kim <yskelg@xxxxxxxxx> wrote: >> Link: https://perfwiki.github.io/main/ > > I think this is great Yunseong, thank you for doing it! Sorry for not > seeing your email earlier! Thank you so much for your encouragement. I was truly happy to receive your reply. Namhyung also offered a lot of encouragement through discord. :) I also appreciate you taking the time to read through my lengthy mail. I've currently added Namhyung, Ian, and Arnaldo as owners on perfwiki Github. Feel free to update the perfwiki markdown contents whenever it’s convenient for you. > Can you explain a little on how to create updates to the pages? For > example, I see the topdown markdown here: > https://github.com/perfwiki/main/blob/main/docs/top-down-analysis.md I'm open to receiving contributions via GitHub Pull Requests Link: https://github.com/perfwiki/main/pulls Similarly, if someone have any discussions or requests, anyone can leave them as issues Link: https://github.com/perfwiki/main/issues or contact me via email. I’ve written a guide on this topic in the README.md file. Link: https://github.com/perfwiki/main?tab=readme-ov-file#automated-deployment-from-markdown > It looks like if I update the markdown, in a fork, I then need to > generate the HTML: > https://github.com/perfwiki/main/blob/main/site/top-down-analysis/index.html > Presumably I send a pull request containing the HTML and the mark down? I took some time to review the deployment process for MkDocs. Link: https://www.mkdocs.org/user-guide/deploying-your-docs/#project-pages The branch used for deploying to the actual website is this one: "gh-pages" branch. Link: https://github.com/perfwiki/main/tree/gh-pages You can make changes to the markdown files in "main" branch directly. I’ve already deleted the site directory from the main branch where I previously made an incorrect push. >> I noticed from the perf mailing list that there were issues with >> logging in, and it seems the door lock is still broken with no sign >> of it being fixed. This motivated me to start this migration. > > Log in problems to the wiki have definitely been an issue. I think > using github is a sensible way to resolve this. Thank you for your feedback. Once the mirroring to GitLab is set up as planned, it will be even better, as anyone will be able to access the repository even if GitHub is down. :) >> I wasn’t sure how long we’d have to wait to regain login access. >> I hope you see this in a positive work and not as an act of rebellion >> against using the original wiki. I genuinely believe this was the >> best action I could take. >> >> This situation also made me wonder: Is it really a good idea for a >> wiki, which is linked to the kernel and serves as an official >> reference, to be updated without review from others through the >> mailing list? >> >> While it might be convenient, during the migration, >> I found quite a few documents that were linked for future additions >> but never actually created. > > Agreed, the wiki has been a work in progress for a long time. It is > quite sad the corners haven't been filled out and the documentation > that is there slowly bitrots. Yes, as you mentioned, I will make the issue entries I identified during this migration as issues so that others can be informed as well. >> With a review process through the >> mailing list, I believe the documentation could have been more >> systematically organized. >> >> One thing we need to check is the licensing of the original wiki >> content. The existing documents do not clearly specify their licenses. > > Agreed. Are there examples we can learn from? For example, libbpf is > active on github: > https://github.com/libbpf/libbpf Thank you Ian for providing the reference information. It would be great to have a guide with improved accessibility and easily accessible questions, similar to "libbpf" project. Going forward, when issues arise, I plan to refer to how popular opensource projects label issues for open source contributors. > Agreed. The perf documentation itself, largely the man pages, is a > fork from the git source code 15 years ago. I did a round of deleting > documentation that related to git and not to perf. I'm not sure how > you'd propose packaging the documentation if it were part of the perf > tool. I believe the thought in the wiki was to remove the burden that > exists sending things to LKML. It is also for the best that the build > not have external dependencies (such as downloading files) and is > reproducible. An issue with the man pages was that they defaulted to > placing the current date in them, I modified this so that we use the > git last modified date and it thereby made builds reproducible. > > Thanks, > Ian You're right. I completely agree. It's definitely best to avoid external dependencies. Currently, there’s no specific packaging plan, and I’m just planning to link to the perf man documentation in the kernel repository for now. If you think there’s anything else I should work on or if I missed something, please let me know. Thank you for taking the time to read my long email. Please feel free to reach out anytime. Best regards, Yunseong Kim
