delete Workflow-* pages, until this section will be ready
Signed-off-by: George Melikov <mail@gmelikov.ru>
This commit is contained in:
George Melikov
@@ -1,11 +0,0 @@
|
|||||||
Accept a PR
|
|
||||||
===========
|
|
||||||
|
|
||||||
After a PR is generated, it is available to be commented upon by project
|
|
||||||
members. They may request additional changes, please work with them.
|
|
||||||
|
|
||||||
In addition, project members may accept PRs; this is not an automatic
|
|
||||||
process. By convention, PRs aren't accepted for at least a day, to allow
|
|
||||||
all members a chance to comment.
|
|
||||||
|
|
||||||
After a PR has been accepted, it is available to be merged.
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
Close a PR
|
|
||||||
==========
|
|
||||||
@@ -1,24 +0,0 @@
|
|||||||
Commit Often
|
|
||||||
============
|
|
||||||
|
|
||||||
When writing complex code, it is strongly suggested that developers save
|
|
||||||
their changes, and commit those changes to their local repository, on a
|
|
||||||
frequent basis. In general, this means every hour or two, or when a
|
|
||||||
specific milestone is hit in the development. This allows you to easily
|
|
||||||
*checkpoint* your work.
|
|
||||||
|
|
||||||
Details of this process can be found in the `Commit the
|
|
||||||
changes <https://github.com/zfsonlinux/zfs/wiki/Workflow-Commit>`__
|
|
||||||
page.
|
|
||||||
|
|
||||||
In addition, it is suggested that the changes be pushed to your forked
|
|
||||||
Github repository with the ``git push`` command at least every day, as a
|
|
||||||
backup. Changes should also be pushed prior to running a test, in case
|
|
||||||
your system crashes. This project works with kernel software. A crash
|
|
||||||
while testing development software could easily cause loss of data.
|
|
||||||
|
|
||||||
For developers who want to keep their development branches clean, it
|
|
||||||
might be useful to
|
|
||||||
`squash <https://github.com/zfsonlinux/zfs/wiki/Workflow-Squash>`__
|
|
||||||
commits from time to time, even before you're ready to `create a
|
|
||||||
PR <https://github.com/zfsonlinux/zfs/wiki/Workflow-Create-PR>`__.
|
|
||||||
@@ -1,76 +0,0 @@
|
|||||||
Commit the Changes
|
|
||||||
==================
|
|
||||||
|
|
||||||
In order for your changes to be merged into the ZFS on Linux project,
|
|
||||||
you must first send the changes made in your *topic* branch to your
|
|
||||||
*local* repository. This can be done with the ``git commit -sa``. If
|
|
||||||
there are any new files, they will be reported as *untracked*, and they
|
|
||||||
will not be created in the *local* repository. To add newly created
|
|
||||||
files to the *local* repository, use the ``git add (file-name) ...``
|
|
||||||
command.
|
|
||||||
|
|
||||||
The ``-s`` option adds a *signed off by* line to the commit. This
|
|
||||||
*signed off by* line is required for the ZFS on Linux project. It
|
|
||||||
performs the following functions:
|
|
||||||
|
|
||||||
- It is an acceptance of the `License
|
|
||||||
Terms <https://github.com/zfsonlinux/zfs/blob/master/COPYRIGHT>`__ of
|
|
||||||
the project.
|
|
||||||
- It is the developer's certification that they have the right to
|
|
||||||
submit the patch for inclusion into the code base.
|
|
||||||
- It indicates agreement to the `Developer's Certificate of
|
|
||||||
Origin <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>`__.
|
|
||||||
|
|
||||||
The ``-a`` option causes all modified files in the current branch to be
|
|
||||||
*staged* prior to performing the commit. A list of the modified files in
|
|
||||||
the *local* branch can be created by the use of the ``git status``
|
|
||||||
command. If there are files that have been modified that shouldn't be
|
|
||||||
part of the commit, they can either be rolled back in the current
|
|
||||||
branch, or the files can be manually staged with the
|
|
||||||
``git add (file-name) ...`` command, and the ``git commit -s`` command
|
|
||||||
can be run without the ``-a`` option.
|
|
||||||
|
|
||||||
When you run the ``git commit`` command, an editor will appear to allow
|
|
||||||
you to enter the commit messages. The following requirements apply to a
|
|
||||||
commit message:
|
|
||||||
|
|
||||||
- The first line is a title for the commit, and must be bo longer than
|
|
||||||
50 characters.
|
|
||||||
- The second line should be blank, separating the title of the commit
|
|
||||||
message from the body of the commit message.
|
|
||||||
- There may be one or more lines in the commit message describing the
|
|
||||||
reason for the changes (the body of the commit message). These lines
|
|
||||||
must be no longer than 72 characters, and may contain blank lines.
|
|
||||||
|
|
||||||
- If the commit closes an Issue, there should be a line in the body
|
|
||||||
with the string ``Closes``, followed by the issue number. If
|
|
||||||
multiple issues are closed, multiple lines should be used.
|
|
||||||
|
|
||||||
- After the body of the commit message, there should be a blank line.
|
|
||||||
This separates the body from the *signed off by* line.
|
|
||||||
- The *signed off by* line should have been created by the
|
|
||||||
``git commit -s`` command. If not, the line has the following format:
|
|
||||||
|
|
||||||
- The string "Signed-off-by:"
|
|
||||||
- The name of the developer. Please do not use any no pseudonyms or
|
|
||||||
make any anonymous contributions.
|
|
||||||
- The email address of the developer, enclosed by angle brackets
|
|
||||||
("<>").
|
|
||||||
- An example of this is
|
|
||||||
``Signed-off-by: Random Developer <random@developer.example.org>``
|
|
||||||
|
|
||||||
- If the commit changes only documentation, the line
|
|
||||||
``Requires-builders: style`` may be included in the body. This will
|
|
||||||
cause only the *style* testing to be run. This can save a significant
|
|
||||||
amount of time when Github runs the automated testing. For
|
|
||||||
information on other testing options, please see the `Buildbot
|
|
||||||
options <https://github.com/zfsonlinux/zfs/wiki/Buildbot-Options>`__
|
|
||||||
page.
|
|
||||||
|
|
||||||
For more information about writing commit messages, please visit `How to
|
|
||||||
Write a Git Commit
|
|
||||||
Message <https://chris.beams.io/posts/git-commit/>`__.
|
|
||||||
|
|
||||||
After the changes have been committed to your *local* repository, they
|
|
||||||
should be pushed to your *forked* repository. This is done with the
|
|
||||||
``git push`` command.
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
Fix Conflicts
|
|
||||||
=============
|
|
||||||
@@ -1,32 +0,0 @@
|
|||||||
Create a Branch
|
|
||||||
===============
|
|
||||||
|
|
||||||
With small projects, it's possible to develop code as commits directly
|
|
||||||
on the *master* branch. In the ZFS-on-Linux project, that sort of
|
|
||||||
development would create havoc and make it difficult to open a PR or
|
|
||||||
rebase the code. For this reason, development in the ZFS-on-Linux
|
|
||||||
project is done on *topic* branches.
|
|
||||||
|
|
||||||
The following commands will perform the required functions:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ cd zfs
|
|
||||||
$ git fetch upstream master
|
|
||||||
$ git checkout master
|
|
||||||
$ git merge upstream/master
|
|
||||||
$ git branch (topic-branch-name)
|
|
||||||
$ git checkout (topic-branch-name)
|
|
||||||
|
|
||||||
1. Navigate to your *local* repository.
|
|
||||||
2. Fetch the updates from the *upstream* repository.
|
|
||||||
3. Set the current branch to *master*.
|
|
||||||
4. Merge the fetched updates into the *local* repository.
|
|
||||||
5. Create a new *topic* branch on the updated *master* branch. The name
|
|
||||||
of the branch should be either the name of the feature (preferred for
|
|
||||||
development of features) or an indication of the issue being worked
|
|
||||||
on (preferred for bug fixes).
|
|
||||||
6. Set the current branch to the newly created *topic* branch.
|
|
||||||
|
|
||||||
**Pro Tip**: The ``git checkout -b (topic-branch-name)`` command can be
|
|
||||||
used to create and checkout a new branch with one command.
|
|
||||||
@@ -1,18 +0,0 @@
|
|||||||
Create a Github Account
|
|
||||||
=======================
|
|
||||||
|
|
||||||
This page goes over how to create a Github account. There are no special
|
|
||||||
settings needed to use your Github account on the `ZFS on Linux
|
|
||||||
Project <https://github.com/zfsonlinux>`__.
|
|
||||||
|
|
||||||
Github did an excellent job of documenting how to create an account. The
|
|
||||||
following link provides everything you need to know to get your Github
|
|
||||||
account up and running.
|
|
||||||
|
|
||||||
`https://help.github.com/articles/signing-up-for-a-new-github-account/ <https://help.github.com/articles/signing-up-for-a-new-github-account/>`__
|
|
||||||
|
|
||||||
In addition, the following articles might be useful:
|
|
||||||
|
|
||||||
- `https://help.github.com/articles/keeping-your-account-and-data-secure/ <https://help.github.com/articles/keeping-your-account-and-data-secure/>`__
|
|
||||||
- `https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/ <https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/>`__
|
|
||||||
- `https://help.github.com/articles/adding-a-fallback-authentication-method-with-recover-accounts-elsewhere/ <https://help.github.com/articles/adding-a-fallback-authentication-method-with-recover-accounts-elsewhere/>`__
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
Create a New Test
|
|
||||||
=================
|
|
||||||
@@ -1,11 +0,0 @@
|
|||||||
Delete a Branch
|
|
||||||
===============
|
|
||||||
|
|
||||||
When a commit has been accepted and merged into the main ZFS repository,
|
|
||||||
the developer's topic branch should be deleted. This is also appropriate
|
|
||||||
if the developer abandons the change, and could be appropriate if they
|
|
||||||
change the direction of the change.
|
|
||||||
|
|
||||||
To delete a topic branch, navigate to the base directory of your local
|
|
||||||
Git repository and use the ``git branch -d (branch-name)`` command. The
|
|
||||||
name of the branch should be the same as the branch that was created.
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
Generate a PR
|
|
||||||
=============
|
|
||||||
@@ -1,52 +0,0 @@
|
|||||||
.. raw:: html
|
|
||||||
|
|
||||||
<!--- When this page is updated, please also check the 'Get-the-Source-Code' page -->
|
|
||||||
|
|
||||||
Get the Source Code
|
|
||||||
===================
|
|
||||||
|
|
||||||
This document goes over how a developer can get the ZFS source code for
|
|
||||||
the purpose of making changes to it. For other purposes, please see the
|
|
||||||
`Get the Source
|
|
||||||
Code <https://github.com/zfsonlinux/zfs/wiki/Get-the-Source-Code>`__
|
|
||||||
page.
|
|
||||||
|
|
||||||
The Git *master* branch contains the latest version of the software,
|
|
||||||
including changes that weren't included in the released tarball. This is
|
|
||||||
the preferred source code location and procedure for ZFS development. If
|
|
||||||
you would like to do development work for the `ZFS on Linux
|
|
||||||
Project <https://github.com/zfsonlinux>`__, you can fork the Github
|
|
||||||
repository and prepare the source by using the following process.
|
|
||||||
|
|
||||||
1. Go to the `ZFS on Linux Project <https://github.com/zfsonlinux>`__
|
|
||||||
and fork both the ZFS and SPL repositories. This will create two new
|
|
||||||
repositories (your *forked* repositories) under your account.
|
|
||||||
Detailed instructions can be found at
|
|
||||||
`https://help.github.com/articles/fork-a-repo/ <https://help.github.com/articles/fork-a-repo/>`__.
|
|
||||||
2. Clone both of these repositories onto your development system. This
|
|
||||||
will create your *local* repositories. As an example, if your Github
|
|
||||||
account is *newzfsdeveloper*, the commands to clone the repositories
|
|
||||||
would be:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ mkdir zfs-on-linux
|
|
||||||
$ cd zfs-on-linux
|
|
||||||
$ git clone https://github.com/newzfsdeveloper/spl.git
|
|
||||||
$ git clone https://github.com/newzfsdeveloper/zfs.git
|
|
||||||
|
|
||||||
3. Enter the following commands to make the necessary linkage to the
|
|
||||||
*upstream master* repositories and prepare the source to be compiled:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ cd spl
|
|
||||||
$ git remote add upstream https://github.com/zfsonlinux/spl.git
|
|
||||||
$ ./autogen.sh
|
|
||||||
$ cd ../zfs
|
|
||||||
$ git remote add upstream https://github.com/zfsonlinux/zfs.git
|
|
||||||
$ ./autogen.sh
|
|
||||||
cd ..
|
|
||||||
|
|
||||||
The ``./autogen.sh`` script generates the build files. If the build
|
|
||||||
system is updated by any developer, these scripts need to be run again.
|
|
||||||
@@ -1,50 +0,0 @@
|
|||||||
Install Git
|
|
||||||
===========
|
|
||||||
|
|
||||||
To work with the ZFS software on Github, it's necessary to install the
|
|
||||||
Git software on your computer and set it up. This page covers that
|
|
||||||
process for some common Linux operating systems. Other Linux operating
|
|
||||||
systems should be similar.
|
|
||||||
|
|
||||||
Install the Software Package
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
The first step is to actually install the Git software package. This
|
|
||||||
package can be found in the repositories used by most Linux
|
|
||||||
distributions. If your distribution isn't listed here, or you'd like to
|
|
||||||
install from source, please have a look in the `official Git
|
|
||||||
documentation <https://git-scm.com/download/linux>`__.
|
|
||||||
|
|
||||||
Red Hat and CentOS
|
|
||||||
~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
# yum install git
|
|
||||||
|
|
||||||
Fedora
|
|
||||||
~~~~~~
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ sudo dnf install git
|
|
||||||
|
|
||||||
Debian and Ubuntu
|
|
||||||
~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ sudo apt install git
|
|
||||||
|
|
||||||
Configuring Git
|
|
||||||
---------------
|
|
||||||
|
|
||||||
Your user name and email address must be set within Git before you can
|
|
||||||
make commits to the ZFS project. In addition, your preferred text editor
|
|
||||||
should be set to whatever you would like to use.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ git config --global user.name "John Doe"
|
|
||||||
$ git config --global user.email johndoe@example.com
|
|
||||||
$ git config --global core.editor emacs
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
Adding Large Features
|
|
||||||
=====================
|
|
||||||
@@ -1,9 +0,0 @@
|
|||||||
Merge a PR
|
|
||||||
==========
|
|
||||||
|
|
||||||
Once all the feedback has been addressed, the PR will be merged into the
|
|
||||||
*master* branch by a member with write permission (most members don't
|
|
||||||
have this permission).
|
|
||||||
|
|
||||||
After the PR has been merged, it is eligible to be added to the
|
|
||||||
*release* branch.
|
|
||||||
@@ -1,28 +0,0 @@
|
|||||||
Rebase the Update
|
|
||||||
=================
|
|
||||||
|
|
||||||
Updates to the ZFS on Linux project should always be based on the
|
|
||||||
current *master* branch. This makes them easier to merge into the
|
|
||||||
repository.
|
|
||||||
|
|
||||||
There are two steps in the rebase process. The first step is to update
|
|
||||||
the *local master* branch from the *upstream master* repository. This
|
|
||||||
can be done by entering the following commands:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ git fetch upstream master
|
|
||||||
$ git checkout master
|
|
||||||
$ git merge upstream/master
|
|
||||||
|
|
||||||
The second step is to perform the actual rebase of the updates. This is
|
|
||||||
done by entering the command ``git rebase upstream/master``. If there
|
|
||||||
are any conflicts between the updates in your *local* branch and the
|
|
||||||
updates in the *upstream master* branch, you will be informed of them,
|
|
||||||
and allowed to correct them (see the
|
|
||||||
`Conflicts <https://github.com/zfsonlinux/zfs/wiki/Workflow-Conflicts>`__
|
|
||||||
page).
|
|
||||||
|
|
||||||
This would also be a good time to
|
|
||||||
`squash <https://github.com/zfsonlinux/zfs/wiki/Workflow-Squash>`__ your
|
|
||||||
commits.
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
Squash the Commits
|
|
||||||
==================
|
|
||||||
@@ -1,106 +0,0 @@
|
|||||||
Testing Changes to ZFS
|
|
||||||
======================
|
|
||||||
|
|
||||||
The code in the ZFS on Linux project is quite complex. A minor error in
|
|
||||||
a change could easily introduce new bugs into the software, causing
|
|
||||||
unforeseeable problems. In an attempt to avoid this, the ZTS (ZFS Test
|
|
||||||
Suite) was developed. This test suite is run against multiple
|
|
||||||
architectures and distributions by the Github system when a PR (Pull
|
|
||||||
Request) is submitted.
|
|
||||||
|
|
||||||
A subset of the full test suite can be run by the developer to perform a
|
|
||||||
preliminary verification of the changes in their *local* repository.
|
|
||||||
|
|
||||||
Style Testing
|
|
||||||
-------------
|
|
||||||
|
|
||||||
The first part of the testing is to verify that the software meets the
|
|
||||||
project's style guidelines. To verify that the code meets those
|
|
||||||
guidelines, run ``make checkstyle`` from the *local* repository.
|
|
||||||
|
|
||||||
Basic Functionality Testing
|
|
||||||
---------------------------
|
|
||||||
|
|
||||||
The second part of the testing is to verify basic functionality. This is
|
|
||||||
to ensure that the changes made don't break previous functionality.
|
|
||||||
|
|
||||||
There are a few helper scripts provided in the top-level scripts
|
|
||||||
directory designed to aid developers working with in-tree builds.
|
|
||||||
|
|
||||||
- **zfs-helper.sh:** Certain functionality (i.e. /dev/zvol/) depends on
|
|
||||||
the ZFS provided udev helper scripts being installed on the system.
|
|
||||||
This script can be used to create symlinks on the system from the
|
|
||||||
installation location to the in-tree helper. These links must be in
|
|
||||||
place to successfully run the ZFS Test Suite. The ``-i`` and ``-r``
|
|
||||||
options can be used to install and remove the symlinks.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ sudo ./scripts/zfs-helpers.sh -i
|
|
||||||
|
|
||||||
- **zfs.sh:** The freshly built kernel modules from the *local*
|
|
||||||
repository can be loaded using ``zfs.sh``. This script will load
|
|
||||||
those modules, **even if there are ZFS modules loaded** from another
|
|
||||||
location, which could cause long-term problems if any of the
|
|
||||||
non-testing file-systems on the system use ZFS.
|
|
||||||
|
|
||||||
This script can latter be used to unload the kernel modules with the
|
|
||||||
``-u`` option.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ sudo ./scripts/zfs.sh
|
|
||||||
|
|
||||||
- **zfs-tests.sh:** A wrapper which can be used to launch the ZFS Test
|
|
||||||
Suite. Three loopback devices are created on top of sparse files
|
|
||||||
located in ``/var/tmp/`` and used for the regression test. Detailed
|
|
||||||
directions for the running the ZTS can be found in the `ZTS
|
|
||||||
Readme <https://github.com/zfsonlinux/zfs/tree/master/tests>`__ file.
|
|
||||||
|
|
||||||
**WARNING**: This script should **only** be run on a development system.
|
|
||||||
It makes configuration changes to the system to run the tests, and it
|
|
||||||
*tries* to remove those changes after completion, but the change removal
|
|
||||||
could fail, and dynamic canges of this nature are usually undesirable on
|
|
||||||
a production system. For more information on the changes made, please
|
|
||||||
see the `ZTS
|
|
||||||
Readme <https://github.com/zfsonlinux/zfs/tree/master/tests>`__ file.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ sudo ./scripts/zfs-tests.sh -vx
|
|
||||||
|
|
||||||
**tip:** The **delegate** tests will be skipped unless group read
|
|
||||||
permission is set on the zfs directory and its parents.
|
|
||||||
|
|
||||||
- **zloop.sh:** A wrapper to run ztest repeatedly with randomized
|
|
||||||
arguments. The ztest command is a user space stress test designed to
|
|
||||||
detect correctness issues by concurrently running a random set of
|
|
||||||
test cases. If a crash is encountered, the ztest logs, any associated
|
|
||||||
vdev files, and core file (if one exists) are collected and moved to
|
|
||||||
the output directory for analysis.
|
|
||||||
|
|
||||||
If there are any failures in this test, please see the `zloop
|
|
||||||
debugging <https://github.com/zfsonlinux/zfs/wiki/Workflow-Zloop-Debugging>`__
|
|
||||||
page.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
$ sudo ./scripts/zloop.sh
|
|
||||||
|
|
||||||
Change Testing
|
|
||||||
--------------
|
|
||||||
|
|
||||||
Finally, it's necessary to verify that the changes made actually do what
|
|
||||||
they were intended to do. The extent of the testing would depend on the
|
|
||||||
complexity of the changes.
|
|
||||||
|
|
||||||
After the changes are tested, if the testing can be automated for
|
|
||||||
addition to ZTS, a `new
|
|
||||||
test <https://github.com/zfsonlinux/zfs/wiki/Workflow-Create-Test>`__
|
|
||||||
should be created. This test should be part of the PR that resolves the
|
|
||||||
issue or adds the feature. If the festure is split into multiple PRs,
|
|
||||||
some testing should be included in the first, with additions to the test
|
|
||||||
as required.
|
|
||||||
|
|
||||||
It should be noted that if the change adds too many lines of code that
|
|
||||||
don't get tested by ZTS, the change will not pass testing.
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
Update a PR
|
|
||||||
===========
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
Debugging *Zloop* Failures
|
|
||||||
==========================
|
|
||||||
Reference in New Issue
Block a user