Below are some of the modifications made, which were submitted as a patch: Chapter 1 (Introduction): The word "targetted" was corrected to "targeted"; Chapter 2. (Why upgrade kernel?): The title was modified to read as "Why upgrade the kernel?" Chapter 3. (Obtaining the newer sources through Portage): After code listing 3.2, "...my new kernel..." should read "...the new kernel..." Given the context, it does not make sense for the author to move the focus away from the reader/user. Chapter 4. (Updating the /usr/src/linux symbolic link): It is possible that the symbolic link is not pointing to the sources of the running kernel. Therefore, the sentence just before code listing 4.1, which begins with "In this case..." should read "In any case..." Chapter 5. (Configuring, compiling and installing the new kernel): After code listing 5.2, it says: "For more info, follow the Gentoo Linux Genkernel Guide, or refer to the handbook". What HANDBOOK??? If it is the gentoo handbook, spelling that out is STRONGLY recommended. Here, and right after code listings 5.3 and 5.4, 'handbook' should be hyperlinked. Chapters 6 & 7 required restructuring of some sentences. Details on all these and more are in the diff file included with this report. The patch is pasted in the 'Additonal Information' section below. The actual file is available upon request. Reproducible: Always Steps to Reproduce: 1. 2. 3. --- ../doc/en/kernel-upgrade.xml 2005-04-06 11:10:49.000000000 -0400 +++ kernel-upgrade.xml 2005-05-20 00:06:28.143808464 -0400 @@ -17,8 +17,8 @@ <!-- See http://creativecommons.org/licenses/by-sa/2.0 --> <license/> -<version>0.1.2</version> -<date>2005-04-06</date> +<version>0.1.3</version> +<date>2005-05-20</date> <chapter> <title>Introduction</title> @@ -33,7 +33,7 @@ </p> <p> -Although this guide is targetted at users upgrading from one kernel release +Although this guide is targeted at users upgrading from one kernel release to another, it will also be useful for users migrating from one kernel package to another. </p> @@ -48,15 +48,15 @@ </chapter> <chapter> -<title>Why upgrade kernel?</title> +<title>Why upgrade the kernel?</title> <section> <body> <p> Generally, upgrading from one minor kernel release to the next won't bring any -major differences. Reasons for upgrading kernel are generally either to take -advantage of a specific new feature or driver, to be protected against a -security vulnerability, or just to maintain an up-to-date and healthy system. +major differences. There are several reasons to upgrade the kernel. One is to +take advantage of a specific new feature or driver; another is to be protected +against a security vulnerability, or just to maintain an up-to-date and healthy system. </p> <p> @@ -76,7 +76,7 @@ <body> <p> -You upgrade the kernel sources like you would upgrade any other package - +You upgrade the kernel sources like you would upgrade any other package -- using the <c>emerge</c> utility. It will probably be the case that you want to upgrade your kernel when you see the upgrade appearing on your world updates list. For example: @@ -104,7 +104,7 @@ <p> The kernel sources will then be installed into a subdirectory of -<path>/usr/src</path>. In the above example, my new kernel sources will be +<path>/usr/src</path>. In the above example, the new kernel sources will be installed at <path>/usr/src/linux-2.6.9-gentoo-r2</path>. </p> @@ -124,7 +124,7 @@ </p> <p> -In this case, we need to update the symbolic link to point at the kernel +In any case, we need to update the symbolic link to point at the kernel sources that we are about to upgrade to. Continuing our example: </p> @@ -146,7 +146,7 @@ For either of these options, you should refer to the instructions given in the <uri link="http://www.gentoo.org/doc/en/handbook/index.xml">Gentoo Handbook</uri> relating to <e>Configuring the Kernel</e> and <e>Configuring -the Bootloader</e>. A quick summary is provided here. +the Bootloader</e>. Below is an outline of the required actions: </p> </body> @@ -182,7 +182,10 @@ <p> For more info, follow the <uri link="http://www.gentoo.org/doc/en/genkernel.xml">Gentoo Linux Genkernel -Guide</uri>, or refer to the handbook. +Guide</uri>, or refer to the +<uri link="http://www.gentoo.org/doc/en/handbook/index.xml">Gentoo +Handbook</uri>. Many of the options can be set in the configuration file for +Genkernel, <c>/etc/genkernel.conf</c>. </p> </body> @@ -201,15 +204,20 @@ </pre> <p> -Select the options required for your hardware and operating environment. Refer -to the <e>Gentoo Handbook</e> for additional guidance on this. +Select the options required for your hardware and operating environment. For +additional information on kernel configuration, refer to the chapter entitled +<e>Configuring the Kernel</e> +of the <uri link="http://www.gentoo.org/doc/en/handbook/index.xml">Gentoo +Handbook</uri>. </p> <p> Next, compile your kernel and copy it over to your boot partition. Again, -follow the handbook instructions here, but don't forget to mount your /boot -partition first! In the initial installation, you would have already mounted -this at a much earlier stage. +follow the <uri link="http://www.gentoo.org/doc/en/handbook/index.xml"> +handbook</uri> instructions outlined in the chapter on <e>Configuring the +Bootloader</e>. If /boot is a separate partition, ensure it is mounted before +copying the compiled kernel to this directory! Failing to do so would keep you +from booting the system with your new kernel. </p> <pre caption="Compiling and installing the new kernel"> @@ -222,8 +230,9 @@ <p> Finally, you should update your bootloader config, adding an entry for the new kernel (don't delete the old one just yet!) and unmount the -<path>/boot</path> partition. Again, refer to the handbook for instructions -here. +<path>/boot</path> partition. Again, refer to the +<uri link="http://www.gentoo.org/doc/en/handbook/index.xml">handbook</uri> +for detailed instructions on this procedure. </p> </body> @@ -237,14 +246,16 @@ <p> If you use any kernel modules that are not included in the kernel source tree -but are provided elsewhere in portage (e.g. Nvidia or ATI graphics drivers), -then you must reinstall these on every kernel upgrade. This is as simple as -re-merging the packages involved. Refer again to the -<uri link="http://www.gentoo.org/doc/en/handbook/index.xml">Gentoo -Handbook</uri> <e>Configuring the Kernel</e> chapter for more info here. -Re-merging these packages will ensure they build against the source tree at -<path>/usr/src/linux</path> - therefore they will actually being installed -for the kernel we just compiled. +but are provided elsewhere in portage (e.g. NVIDIA or ATI graphics drivers), +then you must reinstall these after upgrading the kernel. This is as simple as +re-merging the packages involved. For more information, refer to the chapter on +<e>Configuring the Kernel</e> in the +<uri link="http://www.gentoo.org/doc/en/handbook/index.xml">Gentoo +Handbook</uri>. +To ensure these packages will build against the source tree at +<path>/usr/src/linux</path>, first uninstall the packages, then re-merge them. +If old sources for these packages are kept by portage, this uninstall/re-merge +procedure will make sure that they are rebuilt to work with the new kernel. </p> </body> @@ -258,23 +269,24 @@ <p> Next, close all applications and reboot your system. If you followed the above -instructions correctly, you will see an entry for your new kernel on your -bootloader. Select the new kernel and let the system boot. +instructions correctly, the bootloader menu should include an entry for the +new kernel. Select the new kernel and let the system boot. </p> <p> -Hopefully, your system will boot without problem and you can log in and start -working as usual. If everything is working, then the upgrade is complete at -this stage. +Hopefully, your system successfully boots with the new kernel, and you can log +in to resume whatever you were doing. If this is the case, then the upgrade is +complete. </p> <p> -If you have made a mistake and your system will not boot into the new kernel, -then you can simply reboot and boot into your previous working kernel. You can -then restart from the <uri link="#install">Configuring, compiling, and -installing the new kernel</uri> stage - making the appropriate changes to -correct your mistake. In some cases (e.g. you just missed a network driver) -then you might not even need to reboot to do this. +If you made a mistake and the system fails to boot with the new kernel, reboot +the system and select the entry from the bootloader that corresponds to the +last known working kernel. You can then restart from the <uri link="#install"> +Configuring, compiling, and installing the new kernel</uri> stage -- making +the appropriate changes to correct your mistake. In some cases, you might not +even need to reboot to do this (e.g. you missed a driver for an audio device, +ethernet adapter, etc.) </p> </body> @@ -288,7 +300,7 @@ <p> You may have noticed, that when installing the sources for your newer kernel, -the sources for your existing kernel were not removed. This is by-design and +the sources for your existing kernel were not removed. This is by design -- it allows you to easily switch between running different kernels. </p> @@ -313,8 +325,8 @@ Continuing on from the last section, you may be happy with your new kernel and not have any need to keep older kernel versions around. To easily remove all sources for a particular kernel except for the newest one, you can take -advantages of emerge's <e>prune</e> option. Continuing the example using -gentoo-sources: +advantage of <e>prune</e> option available through <c>emerge</c>. Continuing the +example using <e>gentoo-sources</e>: </p> <pre caption="Pruning old versions"> @@ -338,7 +350,7 @@ Finally, you can mount your <path>/boot</path> partition and remove the <path>bzImage</path> and <path>System.map</path> files for the kernel(s) you are pruning. You should also edit your bootloader config so that it -no longer references this kernel. +no longer references such kernel(s). </p> </body> @@ -353,7 +365,7 @@ <p> It is sometimes possible to save time by re-using the configuration file from your old kernel when configuring the new one. Note that this is generally -unsafe - too many changes between every kernel release for this to be a +unsafe -- too many changes between every kernel release for this to be a reliable upgrade path. </p>
Created attachment 59345 [details, diff] kernel-upgrade patch Jimi, thanks for the patch. Would be ideal if you attach the patch to the Bug like this the next time around, instead of putting it inline with the comment. Ensure that the Content Type is patch (when attaching it). I've just put the inline thing as a patchfile, no modifications.
(In reply to comment #1) > Created an attachment (id=59345) [edit] > kernel-upgrade patch > > Jimi, thanks for the patch. Would be ideal if you attach the patch to the Bug > like this the next time around, instead of putting it inline with the comment. > Ensure that the Content Type is patch (when attaching it). > > I've just put the inline thing as a patchfile, no modifications. > Thanks for the reply. When you say 'Content Type', do you mean that I should just have .patch as the extension for the submitted file (e.g filename.patch)?
(In reply to comment #2) > Thanks for the reply. When you say 'Content Type', do you mean that I should > just have .patch as the extension for the submitted file (e.g filename.patch)? No, the Content Type is selected when you're about to submit an attachment, on that form. For this bug, that form would be https://bugs.gentoo.org/attachment.cgi?bugid=93289&action=enter which is basically the Create a New Attachement Link below Summary and Keywords
Fixed in CVS. I've also removed some more spelling mistakes.
