On Fri, Aug 9, 2024 at 10:11 PM Yunseong Kim <yskelg@xxxxxxxxx> wrote: > > Hello everyone, > > I’ve migrated the content from > > Link: https://perf.wiki.kernel.org/ > > to markdown format. > > You can now access it here: > > Link: https://perfwiki.github.io/main/ > > All the pages listed under have been migrated. > Link: https://perf.wiki.kernel.org/index.php?title=Special%3AAllPages&from=&to=&namespace=0 > > We haven’t been able to log in or sign up on > > perf.wiki.kernel.org > > for several months now, despite it being a valuable resource for many > Linux users. I don’t know much about how the perf wiki is managed, > including any automated backups or the updates of man pages to the wiki. > > Using the mkdocs framework, my knowledge of markdown, my keyboard, > and my efforts of finger, I’ve converted the MediaWiki format documentation > from perf.wiki.kernel.org into markdown. I think this is great Yunseong, thank you for doing it! Sorry for not seeing your email earlier! 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 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 believe this was a worthwhile effort for me, especially > considering that it serves as a backup of the valuable content on > the perf wiki at this point in time. > > Linus once said, "Talk is cheap. Show me the code." While I haven’t > been around for long, I understand that telling others what to do without > taking action oneself is not the best way to give feedback. When I looked > into it, the last edits, aside from the bot-built manual documents, > were made in May. Someone can check the recently changed pages, although > I found that it’s not easy to review the past change of history in MediaWiki. > > 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. > 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. > 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 > If you find any discrepancies or issues with the migrated documents > compared to the originals, please let me know. While migrating, I > also fixed some errors in the original documents. If the original is > correct and the migrated document seems off, it’s likely due to a > mistake on my part—no AI was involved, just my fingers. Or perhaps I > was just tired. :) > > I wasn’t sure if GitHub or GitLab was better, so for now, it’s > hosted on GitHub. I plan to mirror it on GitLab as well: > > perfwiki.gitlab.io/main/ > > The CI pipeline for building man pages still needs to be > implemented. I’ll work on that when I have time. > > I’d appreciate any feedback and would love to hear any ideas for > improvement. > > P.S. I also think it would be great if the markdown documents from > the perf wiki could be viewed offline in a TUI. 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 > Warm regards, > Yunseong Kim
