publish: perfwiki.github.io/main

publish: perfwiki.github.io/main

[Yunseong Kim]

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

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.

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.

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.


Warm regards,
Yunseong Kim

Re: publish: perfwiki.github.io/main

[Ian Rogers]

On Fri, Aug 9, 2024 at 10:11 PM Yunseong Kim <yskelg@gmail.com> 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

Re: publish: perfwiki.github.io

[Yunseong Kim]

Hi Ian,

On 8/25/24 2:06 오후, Ian Rogers wrote:
> On Fri, Aug 9, 2024 at 10:11 PM Yunseong Kim <yskelg@gmail.com> 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

Re: publish: perfwiki.github.io/main

[Howard Chu]

[Resend because didn’t cc the mailing list]
Hello Yunseong,

On Sat, Aug 10, 2024 at 1:11 PM Yunseong Kim <yskelg@gmail.com> 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.

Thank you so much, absolutely amazing work.

Just sent a pull request to the perfwiki github page for some minor
improvements, can you please take a look?

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

Cool.

Thanks,
Howard
>
>
> Warm regards,
> Yunseong Kim
>

On Sun, Aug 25, 2024 at 1:06 PM Ian Rogers <irogers@google.com> wrote:
>
> On Fri, Aug 9, 2024 at 10:11 PM Yunseong Kim <yskelg@gmail.com> 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
>

Re: publish: perfwiki.github.io/main

[Yunseong Kim]

Hi Howard,

> Thank you so much, absolutely amazing work.
> 
> Just sent a pull request to the perfwiki github page for some minor
> improvements, can you please take a look?

Thank you so much for comparing and updating the main page!

Your pull request was the first one for perf wiki mkdocs version, thank you for updating the documentation!
Link: https://github.com/perfwiki/main/pull/5

> Cool.
> 
> Thanks,
> Howard

Best regards,
Yunseong Kim