[bootlin/training-materials updates] master: kernel-contributing: Drop the chapter by moving some of its internals elsewhere (23d24c76)
Miquel Raynal
miquel.raynal at bootlin.com
Fri Jul 28 15:25:38 CEST 2023
Repository : https://github.com/bootlin/training-materials
On branch : master
Link : https://github.com/bootlin/training-materials/commit/23d24c769a02e9e0b2ad94abc0e8a251f6356b24
>---------------------------------------------------------------
commit 23d24c769a02e9e0b2ad94abc0e8a251f6356b24
Author: Miquel Raynal <miquel.raynal at bootlin.com>
Date: Fri Jul 28 11:53:19 2023 +0200
kernel-contributing: Drop the chapter by moving some of its internals elsewhere
Let's talk about reporting bugs in the debugging chapter.
Let's encourage people to contribute in the "after the course" part.
Let's drop some parts that were already removed in the sysdev training.
Signed-off-by: Miquel Raynal <miquel.raynal at bootlin.com>
>---------------------------------------------------------------
23d24c769a02e9e0b2ad94abc0e8a251f6356b24
mk/linux-kernel.mk | 1 -
slides/kernel-contribution/kernel-contribution.tex | 223 ---------------------
.../kernel-driver-development-debugging.tex | 21 ++
.../kernel-resources-references.tex | 30 +++
4 files changed, 51 insertions(+), 224 deletions(-)
diff --git a/mk/linux-kernel.mk b/mk/linux-kernel.mk
index 2257b53d..07ac43bd 100644
--- a/mk/linux-kernel.mk
+++ b/mk/linux-kernel.mk
@@ -35,7 +35,6 @@ LINUX_KERNEL_SLIDES = \
kernel-driver-development-debugging \
kernel-porting \
kernel-power-management \
- kernel-contribution \
kernel-resources-references \
last-slides \
kernel-backup-slides-title \
diff --git a/slides/kernel-contribution/kernel-contribution.tex b/slides/kernel-contribution/kernel-contribution.tex
deleted file mode 100644
index 45e844ce..00000000
--- a/slides/kernel-contribution/kernel-contribution.tex
+++ /dev/null
@@ -1,223 +0,0 @@
-\subsection{Contributing to the Linux kernel}
-
-\begin{frame}
- \frametitle{Getting help and reporting bugs}
- \begin{itemize}
- \item If you are using a custom kernel from a hardware vendor, contact
- that company. The community will have less interest supporting
- a custom kernel.
- \item Otherwise, or if this doesn't work, try to reproduce the
- issue on the latest version of the kernel.
- \item Make sure you investigate the issue as much as you can: see
- \kdochtml{admin-guide/bug-bisect}
- \item Check for previous bugs reports. Use web search engines,
- accessing public mailing list archives.
- \item If you're the first to face the issue, it's very useful for
- others to report it, even if you cannot investigate it further.
- \item If the subsystem you report a bug on has a mailing list, use
- it. Otherwise, contact the official maintainer (see the
- \kfile{MAINTAINERS} file). Always give as many useful details as
- possible.
- \end{itemize}
-\end{frame}
-
-\begin{frame}
- \frametitle{How to Become a Kernel Developer?}
- Recommended resources
- \begin{itemize}
- \item See \kdochtml{process/submitting-patches} for guidelines
- and \url{https://kernelnewbies.org/UpstreamMerge} for very
- helpful advice to have your changes merged upstream (by Rik van
- Riel).
- \item Watch the \emph{Write and Submit your first Linux kernel
- Patch} talk by Greg. K.H:
- \url{https://www.youtube.com/watch?v=LLBrBBImJt4}
- \item How to Participate in the Linux Community (by Jonathan
- Corbet). A guide to the kernel development process
- \url{https://j.mp/tX2Ld6}
- \end{itemize}
-\end{frame}
-
-\begin{frame}
- \frametitle{Contribute to the Linux Kernel (1)}
- \begin{itemize}
- \item Clone Linus Torvalds' tree:
- \begin{itemize}
- \item
- \code{git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux}
- \end{itemize}
- \item Keep your tree up to date
- \begin{itemize}
- \item \code{git pull}
- \end{itemize}
- \item Look at the master branch and check whether your issue /
- change hasn't been solved / implemented yet. Also check the
- maintainer's git tree and mailing list (see the \kfile{MAINTAINERS}
- file).You may miss submissions that are not in mainline yet.
- \item If the maintainer has its own git tree, create a remote branch
- tracking this tree. This is much better than creating another
- clone (doesn't duplicate common stuff):
- \begin{itemize}
- \item
- \code{git remote add linux-omap https://git.kernel.org/pub/scm/linux/kernel/git/tmlind/linux-omap}
- \item \code{git fetch linux-omap}
- \end{itemize}
- \end{itemize}
-\end{frame}
-
-\begin{frame}
- \frametitle{Contribute to the Linux Kernel (2)}
- \begin{itemize}
- \item Either create a new branch starting from the current commit in
- the master branch:
- \begin{itemize}
- \item \code{git checkout -b feature}
- \end{itemize}
- \item Or, if more appropriate, create a new branch starting from the
- maintainer's master branch:
- \begin{itemize}
- \item \code{git checkout -b feature linux-omap/master} (remote
- tree / remote branch)
- \end{itemize}
- \item In your new branch, implement your changes.
- \item Test your changes (must at least compile them).
- \item Run \code{git add} to add any new files to the index.
- \end{itemize}
-\end{frame}
-
-\begin{frame}
- \frametitle{Configure git send-email}
- \begin{itemize}
- \item Make sure you already have configured your name and e-mail
- address (should be done before the first commit).
- \begin{itemize}
- \item \code{git config --global user.name 'My Name'}
- \item \code{git config --global user.email me at mydomain.net}
- \end{itemize}
- \item Configure your SMTP settings. Example for a Google Mail
- account:
- \begin{itemize}
- \item \code{git config --global sendemail.smtpserver smtp.googlemail.com}
- \item \code{git config --global sendemail.smtpserverport 587}
- \item \code{git config --global sendemail.smtpencryption tls}
- \item \code{git config --global sendemail.smtpuser jdoe at gmail.com}
- \item \code{git config --global sendemail.smtppass xxx}
- \end{itemize}
- \end{itemize}
-\end{frame}
-
-\begin{frame}[fragile]
- \frametitle{Contribute to the Linux Kernel (3)}
- \begin{itemize}
- \item Group your changes by sets of logical changes, corresponding
- to the set of patches that you wish to submit.
- \item Commit and sign these groups of changes (signing required by
- Linux developers).
- \begin{itemize}
- \item \code{git commit -s}
- \item Make sure your first description line is a useful summary
- and starts with the name of the modified subsystem. This first
- description line will appear in your e-mails
- \end{itemize}
- \item The easiest way is to look at previous commit summaries on the
- main file you modify
- \begin{itemize}
- \item \code{git log --pretty=oneline <path-to-file>}
- \end{itemize}
- \item Examples subject lines (\code{[PATCH]} omitted):
-\begin{verbatim}
-Documentation: prctl/seccomp_filter
-PCI: release busn when removing bus
-ARM: add support for xz kernel decompression
-\end{verbatim}
- \end{itemize}
-\end{frame}
-
-\begin{frame}
- \frametitle{Contribute to the Linux Kernel (4)}
- \begin{itemize}
- \item Remove previously generated patches
- \begin{itemize}
- \item \code{rm 00*.patch}
- \end{itemize}
- \item Have git generate patches corresponding to your branch
- (assuming it is the current branch)
- \begin{itemize}
- \item If your branch is based on mainline
- \begin{itemize}
- \item \code{git format-patch master}
- \end{itemize}
- \item If your branch is based on a remote branch
- \begin{itemize}
- \item \code{git format-patch <remote>/<branch>}
- \end{itemize}
- \end{itemize}
- \item Make sure your patches pass \code{checkpatch.pl} checks:
- \begin{itemize}
- \item \code{scripts/checkpatch.pl --strict 00*.patch}
- \end{itemize}
- \item Now, send your patches to yourself
- \begin{itemize}
- \item \code{git send-email --compose --to me at mydomain.com 00*.patch}
- \end{itemize}
- \item If you have just one patch, or a trivial patch, you can remove
- the empty line after \code{In-Reply-To:}. This way, you won't add
- a summary e-mail introducing your changes (recommended otherwise).
- \end{itemize}
-\end{frame}
-
-\begin{frame}[fragile]
- \frametitle{Contribute to the Linux Kernel (5)}
- \begin{itemize}
- \item Check that you received your e-mail properly, and that it
- looks good.
- \item Now, find the maintainers for your patches
-{\scriptsize
-\begin{verbatim}
-scripts/get_maintainer.pl ~/patches/00*.patch
-Russell King <linux at arm.linux.org.uk> (maintainer:ARM PORT)
-Nicolas Pitre <nicolas.pitre at linaro.org>
-(commit_signer:1/1=100%)
-linux-arm-kernel at lists.infradead.org (open list:ARM PORT)
-linux-kernel at vger.kernel.org (open list)
-\end{verbatim}
-}
- \item Now, send your patches to each of these people and lists
- \begin{itemize}
- \item \code{git send-email --compose --to linux at arm.linux.org.uk
- --to nicolas.pitre at linaro.org --cc linux-arm-kernel at lists.infradead.org
- --cc linux-kernel at vger.kernel.org 00*.patch}
- \end{itemize}
- \item Wait for replies about your changes, take the comments into
- account, and resubmit if needed, until your changes are eventually
- accepted.
- \end{itemize}
-\end{frame}
-
-\begin{frame}
- \frametitle{Contribute to the Linux Kernel (6)}
- \begin{itemize}
- \item If you use \code{git format-patch} to produce your patches,
- you will need to update your branch and may need to group your
- changes in a different way (one patch per commit).
- \item Here's what we recommend
- \begin{itemize}
- \item Update your master branch
- \begin{itemize}
- \item \code{git checkout master; git pull}
- \end{itemize}
- \item Back to your branch, implement the changes taking community
- feedback into account. Commit these changes.
- \item Still in your branch: reorganize your commits and commit messages
- \begin{itemize}
- \item \code{git rebase --interactive origin/master}
- \item \code{git rebase} allows to rebase (replay) your changes
- starting from the latest commits in master. In interactive
- mode, it also allows you to merge, edit and even reorder
- commits, in an interactive way.
- \end{itemize}
- \item Third, generate the new patches with \code{git format-patch}.
- \end{itemize}
- \end{itemize}
-\end{frame}
-
diff --git a/slides/kernel-driver-development-debugging/kernel-driver-development-debugging.tex b/slides/kernel-driver-development-debugging/kernel-driver-development-debugging.tex
index 50451ddf..93a78f83 100644
--- a/slides/kernel-driver-development-debugging/kernel-driver-development-debugging.tex
+++ b/slides/kernel-driver-development-debugging/kernel-driver-development-debugging.tex
@@ -170,6 +170,27 @@
\end{itemize}
\end{frame}
+\begin{frame}
+ \frametitle{Getting help and reporting bugs}
+ \begin{itemize}
+ \item If you are using a custom kernel from a hardware vendor, contact
+ that company. The community will have less interest supporting
+ a custom kernel.
+ \item Otherwise, or if this doesn't work, try to reproduce the
+ issue on the latest version of the kernel.
+ \item Make sure you investigate the issue as much as you can: see
+ \kdochtml{admin-guide/bug-bisect}
+ \item Check for previous bugs reports. Use web search engines,
+ accessing public mailing list archives.
+ \item If you're the first to face the issue, it's very useful for
+ others to report it, even if you cannot investigate it further.
+ \item If the subsystem you report a bug on has a mailing list, use
+ it. Otherwise, contact the official maintainer (see the
+ \kfile{MAINTAINERS} file). Always give as many useful details as
+ possible.
+ \end{itemize}
+\end{frame}
+
\setuplabframe
{Kernel debugging}
{
diff --git a/slides/kernel-resources-references/kernel-resources-references.tex b/slides/kernel-resources-references/kernel-resources-references.tex
index e614f789..bc1d576e 100644
--- a/slides/kernel-resources-references/kernel-resources-references.tex
+++ b/slides/kernel-resources-references/kernel-resources-references.tex
@@ -118,3 +118,33 @@
\end{itemize}
\end{columns}
\end{frame}
+
+\begin{frame}
+ \frametitle{Contribute your changes}
+ Recommended resources
+ \begin{itemize}
+ \item See \kdochtml{process/submitting-patches} for guidelines
+ and \url{https://kernelnewbies.org/UpstreamMerge} for very
+ helpful advice to have your changes merged upstream (by Rik van
+ Riel).
+ \item Watch the \emph{Write and Submit your first Linux kernel
+ Patch} talk by Greg. K.H:
+ \url{https://www.youtube.com/watch?v=LLBrBBImJt4}
+ \item How to Participate in the Linux Community (by Jonathan
+ Corbet). A guide to the kernel development process
+ \url{https://j.mp/tX2Ld6}
+ \end{itemize}
+ General advices:
+ \begin{itemize}
+ \item Play with \code{git commit --fixup=} and \code{git rebase -i}
+ \item Send new versions of your changes formatted with \code{git
+ format-patch}
+ \begin{itemize}
+ \item Include a cover letter if you have more than one patch
+ (\code{--cover-letter})
+ \item Don't forget to add a changelog and use \code{-vX} to generate
+ your next iteration
+ \end{itemize}
+ \item Don't be discouraged by the feedback you get
+ \end{itemize}
+\end{frame}
More information about the training-materials-updates
mailing list