From: Josh Marshall <joshua.r.marshall.1991@gmail.com>
To: "Bilbao, Carlos" <carlos.bilbao@amd.com>
Cc: ngn <ngn@ngn.tf>,
linux-newbie@vger.kernel.org,
"linux-doc@vger.kernel.org" <linux-doc@vger.kernel.org>,
Jonathan Corbet <corbet@lwn.net>,
pranjal.singh4370@gmail.com, "bilbao@vt.edu" <bilbao@vt.edu>
Subject: Re: Feedback on my development setup
Date: Thu, 25 Apr 2024 10:54:39 -0400 [thread overview]
Message-ID: <CAFkJGRfPinGR30oRJNxiYpib5JCaA3f5D672noR-x_3Gq2UBSA@mail.gmail.com> (raw)
In-Reply-To: <e47385b9-cbab-465e-8c8d-3bbad57415aa@amd.com>
Hello Carlos,
This is a generational shift. For my peers, we understand the benefit
of keeping everything in a thread. But at some point it becomes so
verbose and cumbersome as to defeat the purpose. The size of the text
I'm working with and the number of text changes it has seen meets that
level. And so I've kept it in git and referenced that.
1) I'm sending this out to people well outside of the mailing list.
It has gotten around.
2) Ubuntu. That's why it has an explicit callout. However, in my
research RHEL does not have this issue. So I added text calling out
this difference.
3) There is some assumed knowledge. If a reader doesn't know those
commands, honestly, I don't think it is safe for them to start Kernel
development. As stated in the preamble, this is targeted towards
upper level CS university students and above.
4) I'm considering changing citations to sources. It might be more
representative. There's no specific text taken from them, but there
is knowledge referenced from them used to create the document which I
did not already possess or, in the case of the VM image, a big ol'
file.
On Thu, Apr 25, 2024 at 10:36 AM Bilbao, Carlos <carlos.bilbao@amd.com> wrote:
>
> Hello Josh,
>
> On 4/25/2024 12:37 AM, Josh Marshall wrote:
> > Hello everyone,
> >
> > Last draft before I send in a patch. Big change is an added preamble
> > to set tone and intent. Also some stuff up top setting forth the
> > structure of the document. Carlos, I tried figuring out what you
> > meant by troubles with KVM, but all that boiled down to was scant
> > documentation on use cases people rarely venture into. I think that
> > is a different document from what I am trying to write, although I
> > might now be qualified to write it. Pranjal, sorry man, more words :)
> >
>
> Exactly. Since you found the KVM documentation to be lacking in detail,
> that's an excellent opportunity to expand upon it. That's what I was
> suggesting: improving the documentation for these niche cases adds value
> and could be included in your potential patch.
>
> Before I talk about specifics of the document, have you thought about where
> this text belongs in the broader kernel documentation? It's an important
> part of your potential patch. I suggested incorporating it into 'A Guide to
> the Kernel Development Process.' Have you had a chance to consider that?
>
> > https://gitlab.com/anadon/getting-started-on-kernel-dev-guide-workspace/-/blob/main/Linux%20basic%20dev%20setup.rst?ref_type=heads
> >
>
> It's difficult for us to discuss the details of your draft like this. It
> would be more better if you paste the text directly into the email, and I
> can provide inline responses. I'll paste the parts I need.
>
> "
> [...]
> This document has been viewed through many perspectives from many reviewers,
> each wanting a conflicting adaptation. [...]
> "
>
> Really? According to your GitLab history, the commit "Draft 1 complete and
> ready for the first round of peer reviews!" was 2 days ago. What am I
> missing?
>
> "
> [...]
> `NOTE: On some distributions, kernels (/boot/vmlinuz\*) lack global read
> permissions. Administrator permissions are required to make the kernel chosen by
> ``guestmount`` to be readable. There is debate about the effectiveness of this
> security decision. On some distributions like Ubuntu, this will cause a
> problem. In the context of changing a one-off system, having this file globally
> read-only is considered safe.`
> [...]
> "
>
> Please specify the distro you used to prepare this doc.
>
> "
> [...]
> .. code:: bash
>
> mkdir -p "$HOME/Documents/linux-workspace/kernel-dev"
> cd "$HOME/Documents/linux-workspace/kernel-dev"
> export LINUX_REPO_PATH="$(pwd)/linux"
> [...]
> "
>
> Please explain to the reader what these commands are doing and continue to
> do so for subsequent commands, as you've already done in some cases.
>
> "
> [...]
> .. code:: bash
>
> make -j
> [...]
> "
>
> s/-j/-j (num cores)
>
> "
> [...]
> Citations
> ---------
>
> - https://github.com/archlinux/arch-boxes
> [...]
> "
>
> Citations should be numbered and cited in the text where appropriate.
>
> > On Tue, Apr 23, 2024 at 1:43 PM Josh Marshall
> > <joshua.r.marshall.1991@gmail.com> wrote:
> >>
> >> Hello Carlos,
> >>
> >> My intention right now is still to gather feedback on the draft!
> >> Everything, including if it should be sliced and diced into other
> >> places, is up for consideration. The final intent is a patch into the
> >> central doc tree and not remote documentation. I'll wait longer to
> >> gather more input before replying to particular points.
> >>
> >> On Tue, Apr 23, 2024 at 12:40 PM Bilbao, Carlos <carlos.bilbao@amd.com> wrote:
> >>>
> >>> Hello Josh,
> >>>
> >>> On 4/23/2024 10:34 AM, Josh Marshall wrote:
> >>>> I have a draft document which I would like broader review on, which
> >>>> currently lives here:
> >>>> https://gitlab.com/anadon/getting-started-on-kernel-dev-guide-workspace.
> >>>> This document is to ease the setup of Kernel Development. I intend to
> >>>> send this in as a patch to the mainline doc tree once it gets by a
> >>>> suitable number of reviewers.
> >>>
> >>> It's great that you're interested in improving the documentation. I've CCed
> >>> linux-doc list for visibility.
> >>>
> >>> However, please note that we already have existing documentation, and it
> >>> might be better to extend what's already there rather than creating
> >>> something entirely new. You can refer to:
> >>>
> >>> https://www.kernel.org/doc/html/latest/process/development-process.html
> >>>
> >>> If you still feel the need to start a new document and host it remotely, I
> >>> suggest updating:
> >>>
> >>> https://www.kernel.org/doc/html/v6.1/process/kernel-docs.html
> >>>
> >>> If I may offer a suggestion, focusing on documenting the challenges you've
> >>> encountered with KVM, etc., could be more valuable that trying to cover
> >>> everything.
> >>>
> >>>>
> >>>> On Fri, Apr 19, 2024 at 12:15 PM ngn <ngn@ngn.tf> wrote:
> >>>>>
> >>>>> On Thu, Apr 18, 2024 at 05:40:20PM -0400, Josh Marshall wrote:
> >>>>>> Looks like breakpoints aren't working? https://paste.debian.net/1314501/
> >>>>>>
> >>>>>
> >>>>> This maybe caused by Kernel Address Space Randomization (KASLR), try
> >>>>> disabling it by adding nokaslr option to the boot options.
> >>>
> >>> Thanks,
> >>> Carlos
>
> Thanks,
> Carlos
next prev parent reply other threads:[~2024-04-25 14:54 UTC|newest]
Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-04-16 12:38 Feedback on my development setup Josh Marshall
2024-04-16 14:56 ` ngn
2024-04-16 15:03 ` Josh Marshall
2024-04-16 15:21 ` ngn
2024-04-17 16:11 ` Josh Marshall
[not found] ` <CAPzh0z8RySn429XYQHoP_c9UA+pb6SLHGhH40vQDhc3P2xiysQ@mail.gmail.com>
2024-04-17 21:18 ` Josh Marshall
2024-04-18 15:35 ` ngn
2024-04-18 19:15 ` Josh Marshall
2024-04-18 19:27 ` Josh Marshall
2024-04-18 19:52 ` Josh Marshall
2024-04-18 21:40 ` Josh Marshall
2024-04-19 16:14 ` ngn
2024-04-23 15:34 ` Josh Marshall
2024-04-23 16:08 ` Pranjal Singh
2024-04-23 16:39 ` Bilbao, Carlos
2024-04-23 17:43 ` Josh Marshall
2024-04-25 5:37 ` Josh Marshall
2024-04-25 14:36 ` Bilbao, Carlos
2024-04-25 14:54 ` Josh Marshall [this message]
2024-04-25 15:14 ` Jonathan Corbet
[not found] ` <CAFkJGReoq2s+LR1kj1hj8QvsKsEhk+CLYtCXV=DQTjTqan3DOg@mail.gmail.com>
2024-04-25 16:59 ` Carlos Bilbao
2024-04-25 17:08 ` Josh Marshall
2024-04-25 20:14 ` Theodore Ts'o
2024-04-25 20:02 ` Theodore Ts'o
2024-04-25 14:32 ` Thomas Bertschinger
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CAFkJGRfPinGR30oRJNxiYpib5JCaA3f5D672noR-x_3Gq2UBSA@mail.gmail.com \
--to=joshua.r.marshall.1991@gmail.com \
--cc=bilbao@vt.edu \
--cc=carlos.bilbao@amd.com \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-newbie@vger.kernel.org \
--cc=ngn@ngn.tf \
--cc=pranjal.singh4370@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).