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