diff --git a/docs/Developer Resources/OpenZFS Exceptions.rst b/docs/Developer Resources/illumos Exceptions.rst similarity index 98% rename from docs/Developer Resources/OpenZFS Exceptions.rst rename to docs/Developer Resources/illumos Exceptions.rst index a9ac449ea..212eb60c8 100644 --- a/docs/Developer Resources/OpenZFS Exceptions.rst +++ b/docs/Developer Resources/illumos Exceptions.rst @@ -1,31 +1,30 @@ -OpenZFS Exceptions +illumos Exceptions ================== Commit exceptions used to explicitly reference a given Linux commit. These exceptions are useful for a variety of reasons. **This page is used to generate** -`OpenZFS Tracking `__ +`illumos Tracking `__ **page.** Format: ^^^^^^^ -- ``|-|`` - The OpenZFS commit isn't applicable - to Linux, or the OpenZFS -> ZFS on Linux commit matching is unable to +- ``|-|`` - The illumos commit isn't applicable + to OpenZFS, or the illumos -> OpenZFS commit matching is unable to associate the related commits due to lack of information (denoted by a -). -- ``||`` - The fix was merged to Linux - prior to their being an OpenZFS issue. +- ``||`` - The fix was merged to OpenZFS + prior to their being an illumos issue. - ``|!|`` - The commit is applicable but not applied for the reason described in the comment. +------------------+-------------------+-----------------------------+ -| OpenZFS issue id | status/ZFS commit | comment | +| illumos issue id | OpenZFS commit | comment | +==================+===================+=============================+ | 11453 | ! | check_disk() on illumos | -| | | isn't available on ZoL / | -| | | OpenZFS 2.0 | +| | | isn't available on OpenZFS | +------------------+-------------------+-----------------------------+ | 11276 | da68988 | | +------------------+-------------------+-----------------------------+ @@ -102,9 +101,7 @@ Format: +------------------+-------------------+-----------------------------+ | 9466 | 272b5d73 | | +------------------+-------------------+-----------------------------+ -| 9440 | f664f1e | Illumos ticket 9440 never | -| | | landed in openzfs/openzfs, | -| | | but in ZoL / OpenZFS 2.0 | +| 9440 | f664f1e | | +------------------+-------------------+-----------------------------+ | 9433 | 0873bb63 | | +------------------+-------------------+-----------------------------+ @@ -167,7 +164,7 @@ Format: +------------------+-------------------+-----------------------------+ | 8521 | ee6370a7 | | +------------------+-------------------+-----------------------------+ -| 8502 | ! | Apply when porting OpenZFS | +| 8502 | ! | Apply when porting illumos | | | | 7955 | +------------------+-------------------+-----------------------------+ | 9485 | 1258bd7 | | @@ -279,7 +276,7 @@ Format: +------------------+-------------------+-----------------------------+ | 7542 | - | The Linux libshare code | | | | differs significantly from | -| | | the upstream OpenZFS code. | +| | | the illumos code. | | | | Since this change doesn't | | | | address a Linux specific | | | | issue it doesn't need to be | @@ -394,7 +391,7 @@ Format: +------------------+-------------------+-----------------------------+ | 6250 | - | Linux handles crash dumps | | | | in a fundamentally | -| | | different way than Illumos. | +| | | different way than illumos. | | | | The proposed changes are | | | | not needed. | +------------------+-------------------+-----------------------------+ diff --git a/docs/Developer Resources/OpenZFS Patches.rst b/docs/Developer Resources/illumos Patches.rst similarity index 66% rename from docs/Developer Resources/OpenZFS Patches.rst rename to docs/Developer Resources/illumos Patches.rst index fa622bd7c..cb545bbc8 100644 --- a/docs/Developer Resources/OpenZFS Patches.rst +++ b/docs/Developer Resources/illumos Patches.rst @@ -1,76 +1,63 @@ -OpenZFS Patches +illumos Patches =============== -The ZFS on Linux project is an adaptation of the upstream `OpenZFS -repository `__ designed to work in -a Linux environment. This upstream repository acts as a location where -new features, bug fixes, and performance improvements from all the -OpenZFS platforms can be integrated. Each platform is responsible for -tracking the OpenZFS repository and merging the relevant improvements -back in to their release. - -For the ZFS on Linux project this tracking is managed through an -`OpenZFS tracking `__ -page. The page is updated regularly and shows a list of OpenZFS commits -and their status in regard to the ZFS on Linux master branch. - -This page describes the process of applying outstanding OpenZFS commits -to ZFS on Linux and submitting those changes for inclusion. As a -developer this is a great way to familiarize yourself with ZFS on Linux +OpenZFS tracks illumos ZFS patches at the +`illumos Tracking `__ +page. The page shows a list of illumos commits and their status in regard to +the OpenZFS master branch. This page is no longer regularly updated. + +This page describes the process of applying outstanding illumos commits +to OpenZFS and submitting those changes for inclusion. As a +developer this is a great way to familiarize yourself with OpenZFS and to begin quickly making a valuable contribution to the project. The following guide assumes you have a `github account `__, are familiar with git, and are used to developing in a Linux environment. -Porting OpenZFS changes to ZFS on Linux ---------------------------------------- +Porting illumos changes to OpenZFS +---------------------------------- Setup the Environment ~~~~~~~~~~~~~~~~~~~~~ **Clone the source.** Start by making a local clone of the -`spl `__ and -`zfs `__ repositories. +`zfs `__ repository. :: - $ git clone -o zfsonlinux https://github.com/zfsonlinux/spl.git $ git clone -o zfsonlinux https://github.com/zfsonlinux/zfs.git **Add remote repositories.** Using the GitHub web interface `fork `__ the `zfs `__ repository in to your personal GitHub account. Add your new zfs fork and the -`openzfs `__ repository as remotes -and then fetch both repositories. The OpenZFS repository is large and -the initial fetch may take some time over a slow connection. +`illumos-gate `__ repository as +remotes and then fetch both repositories. The illumos-gate repository is large +and the initial fetch may take some time over a slow connection. :: $ cd zfs $ git remote add git@github.com:/zfs.git - $ git remote add openzfs https://github.com/openzfs/openzfs.git + $ git remote add illumos-gate https://github.com/illumos/illumos-gate.git $ git fetch --all -**Build the source.** Compile the spl and zfs master branches. These -branches are always kept stable and this is a useful verification that +**Build the source.** Compile the zfs master branch. This branch +is always kept stable and this is a useful verification that you have a full build environment installed and all the required dependencies are available. This may also speed up the compile time latter for small patches where incremental builds are an option. :: - $ cd ../spl - $ sh autogen.sh && ./configure --enable-debug && make -s -j$(nproc) - $ $ cd ../zfs $ sh autogen.sh && ./configure --enable-debug && make -s -j$(nproc) Pick a patch ~~~~~~~~~~~~ -Consult the `OpenZFS +Consult the `illumos tracking `__ page and select a patch which has not yet been applied. For your first patch you will want to select a small patch to familiarize yourself with the @@ -123,7 +110,7 @@ Download the script: ./openzfs-merge.sh -d path_to_zfs_folder -c openzfs_commit_hash This command will fetch all repositories, create a new branch -``autoport-ozXXXX`` (XXXX - OpenZFS issue number), try to cherry-pick, +``autoport-ozXXXX`` (XXXX - illumos issue number), try to cherry-pick, compile and check cstyle on success. If it succeeds without any merge conflicts - go to ``autoport-ozXXXX`` @@ -161,21 +148,21 @@ Manual merge ^^^^^^^^^^^^ **Create a new branch.** It is important to create a new branch for -every commit you port to ZFS on Linux. This will allow you to easily +every commit you port to OpenZFS. This will allow you to easily submit your work as a GitHub pull request and it makes it possible to work on multiple OpenZFS changes concurrently. All development branches -need to be based off of the ZFS master branch and it's helpful to name +need to be based off of the OpenZFS master branch and it's helpful to name the branches after the issue number you're working on. :: - $ git checkout -b openzfs- master + $ git checkout -b illumos- master **Generate a patch.** One of the first things you'll notice about the -ZFS on Linux repository is that it is laid out differently than the -OpenZFS repository. Organizationally it is much flatter, this is +OpenZFS repository is that it is laid out differently than the +illumos-gate repository. Organizationally it is much flatter, this is possible because it only contains the code for OpenZFS not an entire OS. -That means that in order to apply a patch from OpenZFS the path names in +That means that in order to apply a patch from illumos the path names in the patch must be changed. A script called zfs2zol-patch.sed has been provided to perform this translation. Use the ``git format-patch`` command and this script to generate a patch. @@ -197,51 +184,54 @@ cleanly while preserving the its original intent. :: - $ git am ./openzfs-.diff + $ git am ./illumos-.diff **Update the commit message.** By using ``git format-patch`` to generate the patch and then ``git am`` to apply it the original comment and authorship will be preserved. However, due to the formatting of the -OpenZFS commit you will likely find that the entire commit comment has +illumos commit you will likely find that the entire commit comment has been squashed in to the subject line. Use ``git commit --amend`` to cleanup the comment and be careful to follow `these standard guidelines `__. -The summary line of an OpenZFS commit is often very long and you should +The summary line of an illumos commit is often very long and you should truncate it to 50 characters. This is useful because it preserves the correct formatting of ``git log --pretty=oneline`` command. Make sure to leave a blank line between the summary and body of the commit. Then -include the full OpenZFS commit message wrapping any lines which exceed +include the full illumos commit message wrapping any lines which exceed 72 characters. Finally, add a ``Ported-by`` tag with your contact -information and both a ``OpenZFS-issue`` and ``OpenZFS-commit`` tag with +information and both a ``illumos-issue`` and ``illumos-commit`` tag with appropriate links. You'll want to verify your commit contains all of the following information: -- The subject line from the original OpenZFS patch in the form: - "OpenZFS - short description". +- The subject line from the original illumos patch in the form: + "illumos - short description". - The original patch authorship should be preserved. -- The OpenZFS commit message. +- The illumos commit message. - The following tags: - **Authored by:** Original patch author - - **Reviewed by:** All OpenZFS reviewers from the original patch. - - **Approved by:** All OpenZFS reviewers from the original patch. + - **Reviewed by:** All illumos reviewers from the original patch. + - **Approved by:** All illumos reviewers from the original patch. - **Ported-by:** Your name and email address. - - **OpenZFS-issue:** https ://www.illumos.org/issues/issue - - **OpenZFS-commit:** https - ://github.com/openzfs/openzfs/commit/hash + - **illumos-issue:** https ://www.illumos.org/issues/issue + - **illumos-commit:** https + ://github.com/illumos/illumos-gate/commit/hash - **Porting Notes:** An optional section describing any changes required when porting. -For example, OpenZFS issue 6873 was `applied to -Linux `__ from this -upstream `OpenZFS -commit `__. +For example, illumos issue 6873 was `applied to +OpenZFS `__ from this +upstream `illumos +commit `__. Note +that this example predates the OpenZFS renaming, so the real commit uses +"OpenZFS" instead of "illumos"; the example below show how it should look +if done today. :: - OpenZFS 6873 - zfs_destroy_snaps_nvl leaks errlist + illumos 6873 - zfs_destroy_snaps_nvl leaks errlist Authored by: Chris Williamson Reviewed by: Matthew Ahrens @@ -251,8 +241,8 @@ commit `__. lzc_destroy_snaps() returns an nvlist in errlist. zfs_destroy_snaps_nvl() should nvlist_free() it before returning. - OpenZFS-issue: https://www.illumos.org/issues/6873 - OpenZFS-commit: https://github.com/openzfs/openzfs/commit/ee06391 + illumos-issue: https://www.illumos.org/issues/6873 + illumos-commit: https://github.com/openzfs/openzfs/commit/ee06391 Testing a Patch ~~~~~~~~~~~~~~~ @@ -275,7 +265,7 @@ checker, the command should return without printing any output. style checks `open a new pull request `__. The pull request will be queued for `automated -testing `__. As part of the +testing `__. As part of the testing the change is built for a wide range of Linux distributions and a battery of functional and stress tests are run to detect regressions. @@ -285,10 +275,10 @@ a battery of functional and stress tests are run to detect regressions. **Fix any issues.** Testing takes approximately 2 hours to fully complete and the results are posted in the GitHub `pull -request `__. All the tests +request `__. All the tests are expected to pass and you should investigate and resolve any test failures. The `test -scripts `__ +scripts `__ are all available and designed to run locally in order reproduce an issue. Once you've resolved the issue force update the pull request to trigger a new round of testing. Iterate until all the tests are passing. @@ -302,17 +292,8 @@ trigger a new round of testing. Iterate until all the tests are passing. Merging the Patch ~~~~~~~~~~~~~~~~~ -**Review.** Lastly one of the ZFS on Linux maintainers will make a final +**Review.** Lastly one of the OpenZFS maintainers will make a final review of the patch and may request additional changes. Once the maintainer is happy with the final version of the patch they will add their signed-off-by, merge it to the master branch, mark it complete on the tracking page, and thank you for your contribution to the project! - -Porting ZFS on Linux changes to OpenZFS ---------------------------------------- - -Often an issue will be first fixed in ZFS on Linux or a new feature -developed. Changes which are not Linux specific should be submitted -upstream to the OpenZFS GitHub repository for review. The process for -this is described in the `OpenZFS -README `__. diff --git a/docs/Developer Resources/index.rst b/docs/Developer Resources/index.rst index 3b5d62b74..57c46733b 100644 --- a/docs/Developer Resources/index.rst +++ b/docs/Developer Resources/index.rst @@ -11,8 +11,8 @@ Developer Resources Buildbot Status Buildbot Issue Tracking Buildbot Options - OpenZFS Tracking - OpenZFS Patches - OpenZFS Exceptions + illumos Tracking + illumos Patches + illumos Exceptions OpenZFS Documentation Git and GitHub for beginners