-
Notifications
You must be signed in to change notification settings - Fork 195
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
WIP: Reference illumos instead of OpenZFS #235
Open
rlaager
wants to merge
1
commit into
master
Choose a base branch
from
illumos-tracking
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,76 +1,63 @@ | ||
| OpenZFS Patches | ||
| illumos Patches | ||
| =============== | ||
|
|
||
| The ZFS on Linux project is an adaptation of the upstream `OpenZFS | ||
| repository <https://github.com/openzfs/openzfs/>`__ 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 <http://build.zfsonlinux.org/openzfs-tracking.html>`__ | ||
| 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 <http://build.zfsonlinux.org/openzfs-tracking.html>`__ | ||
| 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 <https://help.github.com/articles/signing-up-for-a-new-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 <https://github.com/zfsonlinux/spl>`__ and | ||
| `zfs <https://github.com/zfsonlinux/zfs>`__ repositories. | ||
| `zfs <https://github.com/zfsonlinux/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 <https://help.github.com/articles/fork-a-repo/>`__ the | ||
| `zfs <https://github.com/zfsonlinux/zfs>`__ repository in to your | ||
| personal GitHub account. Add your new zfs fork and the | ||
| `openzfs <https://github.com/openzfs/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 <https://github.com/illumos/illumos-gat/>`__ 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 <your-github-account> [email protected]:<your-github-account>/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 <http://build.zfsonlinux.org/openzfs-tracking.html>`__ 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-<issue-nr> master | ||
| $ git checkout -b illumos-<issue-nr> 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-<commit-nr>.diff | ||
| $ git am ./illumos-<commit-nr>.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 <http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`__. | ||
|
|
||
| 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 <issue-nr> - short description". | ||
| - The subject line from the original illumos patch in the form: | ||
| "illumos <issue-nr> - 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 <https://github.com/zfsonlinux/zfs/commit/b3744ae>`__ from this | ||
| upstream `OpenZFS | ||
| commit <https://github.com/openzfs/openzfs/commit/ee06391>`__. | ||
| For example, illumos issue 6873 was `applied to | ||
| OpenZFS <https://github.com/openzfs/openzfs/commit/b3744ae>`__ from this | ||
| upstream `illumos | ||
| commit <https://github.com/illumos/illumos-gate/commit/ee06391>`__. 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 <[email protected]> | ||
| Reviewed by: Matthew Ahrens <[email protected]> | ||
|
|
@@ -251,8 +241,8 @@ commit <https://github.com/openzfs/openzfs/commit/ee06391>`__. | |
| 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 <https://help.github.com/articles/creating-a-pull-request/>`__. | ||
| The pull request will be queued for `automated | ||
| testing <https://github.com/zfsonlinux/zfs-buildbot/>`__. As part of the | ||
| testing <https://github.com/openzfs/zfs-buildbot/>`__. 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 <https://github.com/zfsonlinux/zfs/pull/4594>`__. All the tests | ||
| request <https://github.com/openzfs/zfs/pull/4594>`__. All the tests | ||
| are expected to pass and you should investigate and resolve any test | ||
| failures. The `test | ||
| scripts <https://github.com/zfsonlinux/zfs-buildbot/tree/master/scripts>`__ | ||
| scripts <https://github.com/openzfs/zfs-buildbot/tree/master/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 <https://github.com/openzfs/openzfs/>`__. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.