Add the Rawhide page

releases/modules/ROOT/nav.adoc

@@ -1 +1,3 @@
 * xref:lifecycle.adoc[Release Life Cycle]
+* Development Releases
+** xref:releases/rawhide.adoc[Rawhide]

releases/modules/ROOT/pages/releases/rawhide.adoc

@@ -0,0 +1,197 @@
+= Rawhide
+
+"Rawhide" is the name given to the current development version of Fedora Linux.
+It consists of a xref:quick-docs:repositories.adoc[package repository] called "rawhide" and contains the latest build of all Fedora Linux packages updated on a daily basis.
+Each day, the build system attempts to create a full set of deliverables (installation images and so on), and all that compose successfully are included in the Rawhide tree for that day.
+
+Rawhide is sometimes called "development" or "main" (as it's the "main" branch in package git repositories). 
+
+== Goals
+
+Rawhide has the following Goals: 
+
+* To allow package maintainers to integrate the newest _usable_ versions of their packages into Fedora. 
+* To allow advanced users access to the newest _usable_ packages in a rolling manner.
+* To allow incremental changes to packages that are either too minor or major to go to stable Fedora releases.
+* To identify and fix issues with packages before they reach a stable release of Fedora.
+* To allow a place where certain low-level packages (approved by FESCo), including (but not limited to) glibc and gcc, can gain real-world testing of pre-release versions.
+
+== Audience
+
+Rawhide is targeted at advanced users, testers, and package maintainers. 
+
+As a Rawhide consumer, you should: 
+
+* Be willing to update on an almost daily basis.
+Rawhide gets hundreds of updates a day, and applying those updates on a regular basis allows you to more easily isolate when a bug appeared and what package(s) are responsible.
+* Be willing and able to troubleshoot problems.
+From time to time there are problems with Rawhide packages, and you will need strong troubleshooting skills and the ability to gather information for bug reports.
+You need a good understanding of dnf and how to downgrade packages, as well as boot time troubleshooting.
+* Have time and desire to learn new interfaces and changes.
+Rawhide packages stick closely to upstream projects, so interfaces and command-line options are subject to frequent changes.
+* Be willing to reboot frequently to test new kernel versions and confirm functionality of the boot process.
+If you can't reboot often, consider using a stable release instead.
+* Be willing and able to report bugs to bugzilla as you find them and help maintainers gather information to fix them. 
+
+If the above doesn't match you, you may wish to instead follow the xref:branched.adoc[Branched] release (depending on the point in the https://fedorapeople.org/groups/schedule/[release cycle]) or use regular stable Fedora releases.
+
+== Using Rawhide
+
+See the https://fedoraproject.org/wiki/Template:Rawhide_branched_install_methods[wiki template] for instructions on installing and using Rawhide.
+
+== Discussing Rawhide
+
+There are a number of ways to communicate with other Rawhide users: 
+
+=== IRC
+
+Rawhide discussion is on topic and welcome in both the https://web.libera.chat/?channels=#fedora-devel[#fedora-devel] and https://web.libera.chat/?channels=#fedora-qa[#fedora-qa] IRC channels.
+
+=== Mailing Lists
+
+Rawhide discussion is on topic and welcome in both the https://lists.fedoraproject.org/admin/lists/test@lists.fedoraproject.org/[test] and https://lists.fedoraproject.org/admin/lists/devel@lists.fedoraproject.org/[devel] lists.
+
+=== Bugzilla
+
+Rawhide bugs should be reported against the _Fedora_ product, _rawhide_ version and the affected component.
+Please do follow https://fedoraproject.org/wiki/Bugs_and_feature_requests[best practices] when filing.
+Remember that IRC and mailing lists are useful to help narrow down if some behavior is a bug or where to report it, but are themselves not bug reporting channels.
+Always file bugs in http://bugzilla.redhat.com[Bugzilla].
+
+Note that broken dependencies are mailed to maintainers for each daily Rawhide compose where a package has such broken dependencies.
+Therefore, it's usually not worth filing a bug for broken dependencies unless they don't appear in the daily report, or you have a fix or improvement to suggest.
+
+== Producing Rawhide
+
+Package owners must build for Rawhide using koji just like you would any other build; you do not go through the Bodhi process and the build becomes available almost immediately.
+
+The Rawhide repository is composed every day starting at 05:15UTC.
+All rawhide builds in the buildsystem at that time are included in the compose attempt.
+The compose process also attempts to build all the standard Fedora 'deliverables' (live and install images, ARM and Cloud disk images, container images and so on).
+If any release-blocking image fails to build as part of the compose, the compose is considered to have failed.
+If the compose completes successfully, the compose will be 'synced out' to the mirror system.
+(A system where the sync only happens if a set of automated tests run on it passes is planned, but not yet fully implemented).
+
+Rawhide is under `development/rawhide` on the mirrors.
+You can find a local "development" mirror on the http://mirrors.fedoraproject.org/publiclist/Fedora/development/[public mirror list]. Compose time varies depending on number of changes but is typically between 5 and 8 hours. 
+
+Composes are done in a rawhide chroot using the 'pungi' tool called from https://pagure.io/pungi-fedora/blob/master/f/nightly.sh[a script maintained by Fedora Release engineering].
+If the base set of packages in Rawhide needed to compose Rawhide are broken, the daily compose may fail. 
+
+A report for each Rawhide compose is sent to to the https://lists.fedoraproject.org/admin/lists/test@lists.fedoraproject.org/[test] and https://lists.fedoraproject.org/admin/lists/devel@lists.fedoraproject.org/[devel] lists.
+This report contains output from the repodiff tool from the previous compose as well as a broken dependency report for packages with broken dependencies.
+Additionally, private email is sent to maintainers with packages containing broken dependencies. 
+
+Package maintainers should read and follow the xref:fesco:Updates_Policy.adoc#rawhide[Rawhide updates policy] for building any packages in Rawhide.
+
+If needed and approved by xref:fesco:index.adoc[FESCo], mass rebuilds are done by Release Engineering in Rawhide a month or so before the next release branches from it.
+Typically these are done for a global change over all packages such as a new gcc release, or rpm package format. 
+
+== Questions and Answers
+
+*Doesn't rawhide eat babies / kill pets / burn down houses / break constantly?*
+
+No.
+Please stop telling everyone that. 
+
+*So Rawhide is very stable and we can all use it?*
+
+No. See audience above.
+There are things that break from time to time, but if you are able to downgrade or troubleshoot such issues aren't too severe.
+Most users should still stick to stable Fedora releases, but Rawhide is a viable option for enthusiasts to experiment with.
+
+*I'm using a Stable Fedora release, but I want a newer package version that's only available in Rawhide. Can I just `dnf install` it?*
+
+No
+Mixing releases like this is a bad idea. Better options are: 
+
+* Ask the Fedora maintainer in a bug report to update the stable version if permitted by policy.
+If not, there may be a http://copr.fedoraproject.org/[Copr repository] that provides the updated version.
+See the COPR page for more details.
+* Obtain the src.rpm for the package you wish and try and to `rpmbuild --rebuild` it (which may or may not work depending on dependencies).
+
+*I want to run the Rawhide kernel on my stable Fedora machine. Can I do that?*
+
+Sometimes yes.
+The kernel is more self-contained than other Rawhide packages and you also can easily boot your older kernel if the Rawhide kernel goes wrong.
+Download and `dnf install` the package.
+However, note that Rawhide kernels often have debugging code enabled, which results in them performing noticeably worse than release kernels (they will be slower and consume more memory).
+
+*Is Rawhide a "rolling release"?*
+
+It depends on how you define that, but yes.
+
+*How can I tell when the Rawhide compose for the day has finished?*
+
+Check the for the reports sent to the https://lists.fedoraproject.org/admin/lists/test@lists.fedoraproject.org/[test] and https://lists.fedoraproject.org/admin/lists/devel@lists.fedoraproject.org/[devel] lists, or watch fedora-messaging for the `org.fedoraproject.prod.pungi.compose.status.change` topic.
+
+*What happens during branching, does it affect my Rawhide release somehow?*
+
+No, you're still on Rawhide and no action is required.
+(This was handled differently in the past).
+
+*How do I get out of Rawhide again? I want to switch to the Branched release or a stable release.*
+
+Note that downgrading your system to a lower release is not supported, not tested, not a good idea, and definitely _at your own risk_.
+The safest approach is to reinstall the system.
+If you really want to downgrade, at least make a filesystem snapshot first (if you use the default Btrfs filesystem).
+
+One common use case is to switch your system to Branched right after it is created (split from Rawhide).
+In this case, the sooner you do it (after branching), the safer and easier it is—the difference between systems is minimal at that point.
+Downgrading after a long time, or downgrading to a stable release (which is completely different from Rawhide) will be more problematic.
+
+You can (attempt to) downgrade to Branched or a stable release using xref:quick-docs:dnf-system-upgrade.adoc[DNF system upgrade] (the same approach as for upgrades).
+However, because Rawhide uses a different set of system repositories, you need to explicitly disable those during the download phase, and explicitly enable the set or repositories used on non-Rawhide systems.
+So the download command would look like this (this will disable and enable the correct repositories, and if you have some additional (including third-party) repositories installed, it will keep them enabled or disabled as they are currently; replace `NN` with the target release number): `sudo dnf system-upgrade download --releasever=NN --disablerepo='rawhide,rawhide-modular' --enablerepo='fedora,fedora-modular,updates,updates-modular'`
+
+Everything else should be unchanged, you can use the rest of the aforelinked guide to proceed.
+There is a higher chance of encountering broken dependencies when downgrading, because while package dependencies must work correctly when going up in versions.
+They don't need to work when going down.
+In that case, you can try `--skip-broken` or removing the offending packages (if possible), otherwise you're mostly out of luck.
+
+*As a package maintainer do I have to build rawhide packages or does the nightly compose take care of that?*
+
+You must build for Rawhide yourself (using Koji).
+The nightly compose only collects packages already built and marked with the appropriate target (rawhide) in koji.
+
+*Are rawhide packages signed?*
+
+All of them are now signed.
+Make sure you have gpgcheck=1 set in your repo file to take advantage of this.
+
+== Hints and Tips
+
+* Your package management system can be of great help in diagnosing and working around issues you find. Do read up and understand:
+** `dnf downgrade`
+** `dnf history`
+** `dnf update --skip-broken`
+** `koji download-build`
+* If you are using a immutable variant like Silverblue, you should make good use of the features of OSTree like:
+** `rpm-ostree rollback`
+** `ostree admin config-diff`
+** `ostree admin pin 0`
+* You should update frequently (preferably every day).
+This allows you to more easily narrow down when a problem or issue appeared.
+If you apply a week of Rawhide updates at once you have many more packages to examine to narrow down issues. 
+* Reboot often (preferably whenever new kernels arrive).
+This allows you to test the boot up process and packages related to it, as well as newer kernels.
+Read and understand the Dracut troubleshooting steps. 
+* Follow the https://lists.fedoraproject.org/admin/lists/test@lists.fedoraproject.org/[test] and https://lists.fedoraproject.org/admin/lists/devel@lists.fedoraproject.org/[devel] lists for Rawhide issues.
+Try to at least skim them before doing your daily Rawhide updates.
+Look for '[rawhide]' subjects or reports of issues.
+Additionally if you find a problem and are not sure what to file bugs against you can open a discussion there. 
+* Rawhide kernels are often built with varying degrees of debugging code enabled, which will result in worse performance and increased resource usage. See https://fedoraproject.org/wiki/KernelDebugStrategy[Kernel Debugging Strategy] for details on exactly what debugging code is enabled for which kernel builds.
+You can disable SLUB debugging for those builds for which it is enabled by passing `slub_debug=-` to your kernel command line in `/etc/default/grub` (and re-generating your grub config, or just adding it directly).
+Additionally, you can run kernels in the https://fedoraproject.org/wiki/RawhideKernelNodebug[Rawhide Kernel Nodebug] repo that have all debugging disabled.
+* If you are using a graphical desktop environment in your Rawhide install, you may wish to install several of them.
+This allows you to still login and troubleshoot when your primary desktop environment is not working for some reason.
+* Have rescue media handy of the current stable Fedora release for emergencies.
+
+== History
+
+Red Hat Linux "Raw Hide" http://lwn.net/1998/0820/rawhide.html[announcement]
+
+The name might come from the http://en.wikipedia.org/wiki/Rawhide_%28song%29[song with the same name] that starts with "Rolling, rolling, rolling, ..."
+
+At one time, Rawhide would freeze before release milestones.
+This was changed with the https://fedoraproject.org/wiki/No_Frozen_Rawhide_Proposal[No Frozen Rawhide Proposal] and Branched process which we now follow.