--- /dev/null
+This directory contains the patches needed to convert ext4 into ldiskfs.
+They are applied automatically during the ldiskfs build process and
+should not be applied to the core kernel directly.
+
+We need to be able to create a version of ldiskfs from the ext4 source
+code found in multiple versions of the kernel. That ext4 source code can
+vary quite a bit between different versions of the kernel, which means
+that it is impossible to maintain one set of patches that will cleanly
+apply to all versions of ext4.
+
+Where to put a new patch
+------------------------
+
+Therefore, we split the patches into multiple subdirectories in the
+"kernel_patches/patches" directory. These subdirecotories are named
+after the version of the Linux distribution against which they were
+developed. For instance, "patches/rhel6.3" and "patches/sles11sp1".
+
+When creating a new patch, put it in the subdirectory for the
+distribution for which it was first created.
+
+Sharing patches
+---------------
+
+Often a patch will apply cleanly to multiple kernel's ext4 code.
+
+If a patch from a different distribution's subdirectory applies cleanly,
+it should be included directly in that distribution's series file rather
+than making a copy of the patch. As an example, lets consider two
+distribution directories:
+
+ patches/rhel6.3
+ patches/sles11sp1
+
+If a patch named "patches/rhel6.3/foo.patch" applies cleanly and is
+needed by the sles11sp1 ext4 code, the sles11sp1 series file should
+directly list "patches/rhel6.3/foo.patch". A copy of the same patch
+should only be made when the patch will not apply without changes.
+
+Updating patches for a new kernel/distribution
+------------------------------------------------
+
+When adding support for a new OS distribution release and its new
+version of the kernel, it is common to begin by copying the patch
+series file from a similar OS release. For instance, when beginning
+to add support for the RHEL 6.4 kernel, one might copy the
+kernel_patches/series/ldiskfs-2.6-rhel6.3.series file to the new name
+kernel_patches/series/ldiskfs-2.6-rhel6.4.series.
+
+When applying that series, some patches are likely to succeed and others
+to fail to apply. When a patch fails to apply, a copy of it should be
+made into a new distribution subdirectory before refreshing that patch.
+In this way, support for the new kernel may be added without breaking
+support for the previous kernel. As an example, if the patch:
+
+ patches/rhel6.3/foo.patch
+
+fails to apply as part of series/ldiskfs-2.6-rhel6.4.series, the developer
+would copy the patch to:
+
+ patches/rhel6.4/foo.patch
+
+The next step would be to edit series/ldiskfs-2.6-rhel6.4.series to point
+to the new patch. Finally, the developer may edit files and "quilt refresh"
+the new patch.
+
+Detecting which patch series to apply
+-------------------------------------
+
+If a new kernel/distro is being added, in order for these patches to be
+applied during the build process, the kernel version needs to map to a
+specific series. This is done in config/lustre-build-ldiskfs.m4 in the
+LDISKFS_LINUX_SERIES check.
git://git.whamcloud.com / fs / lustre-release.git / blobdiff