From 0a3a3281a110e434339e8c070546a9dfa676b7ff Mon Sep 17 00:00:00 2001 From: George Melikov Date: Sat, 16 May 2020 18:32:51 +0300 Subject: [PATCH] delete Workflow-* pages, until this section will be ready Signed-off-by: George Melikov --- docs/Workflow-Accept-PR.rst | 11 --- docs/Workflow-Close-PR.rst | 2 - docs/Workflow-Commit-Often.rst | 24 ------ docs/Workflow-Commit.rst | 76 ----------------- docs/Workflow-Conflicts.rst | 2 - docs/Workflow-Create-Branch.rst | 32 ------- docs/Workflow-Create-Github-Account.rst | 18 ---- docs/Workflow-Create-Test.rst | 2 - docs/Workflow-Delete-Branch.rst | 11 --- docs/Workflow-Generate-PR.rst | 2 - docs/Workflow-Get-Source.rst | 52 ------------ docs/Workflow-Install-Git.rst | 50 ----------- docs/Workflow-Large-Features.rst | 2 - docs/Workflow-Merge-PR.rst | 9 -- docs/Workflow-Rebase.rst | 28 ------- docs/Workflow-Squash.rst | 2 - docs/Workflow-Test.rst | 106 ------------------------ docs/Workflow-Update-PR.rst | 2 - docs/Workflow-Zloop-Debugging.rst | 2 - 19 files changed, 433 deletions(-) delete mode 100644 docs/Workflow-Accept-PR.rst delete mode 100644 docs/Workflow-Close-PR.rst delete mode 100644 docs/Workflow-Commit-Often.rst delete mode 100644 docs/Workflow-Commit.rst delete mode 100644 docs/Workflow-Conflicts.rst delete mode 100644 docs/Workflow-Create-Branch.rst delete mode 100644 docs/Workflow-Create-Github-Account.rst delete mode 100644 docs/Workflow-Create-Test.rst delete mode 100644 docs/Workflow-Delete-Branch.rst delete mode 100644 docs/Workflow-Generate-PR.rst delete mode 100644 docs/Workflow-Get-Source.rst delete mode 100644 docs/Workflow-Install-Git.rst delete mode 100644 docs/Workflow-Large-Features.rst delete mode 100644 docs/Workflow-Merge-PR.rst delete mode 100644 docs/Workflow-Rebase.rst delete mode 100644 docs/Workflow-Squash.rst delete mode 100644 docs/Workflow-Test.rst delete mode 100644 docs/Workflow-Update-PR.rst delete mode 100644 docs/Workflow-Zloop-Debugging.rst diff --git a/docs/Workflow-Accept-PR.rst b/docs/Workflow-Accept-PR.rst deleted file mode 100644 index 50c62dd..0000000 --- a/docs/Workflow-Accept-PR.rst +++ /dev/null @@ -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. diff --git a/docs/Workflow-Close-PR.rst b/docs/Workflow-Close-PR.rst deleted file mode 100644 index 02c36d2..0000000 --- a/docs/Workflow-Close-PR.rst +++ /dev/null @@ -1,2 +0,0 @@ -Close a PR -========== diff --git a/docs/Workflow-Commit-Often.rst b/docs/Workflow-Commit-Often.rst deleted file mode 100644 index 7661073..0000000 --- a/docs/Workflow-Commit-Often.rst +++ /dev/null @@ -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 `__ -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 `__ -commits from time to time, even before you're ready to `create a -PR `__. diff --git a/docs/Workflow-Commit.rst b/docs/Workflow-Commit.rst deleted file mode 100644 index 14b9d20..0000000 --- a/docs/Workflow-Commit.rst +++ /dev/null @@ -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 `__ 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 `__. - -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 `` - -- 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 `__ - page. - -For more information about writing commit messages, please visit `How to -Write a Git Commit -Message `__. - -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. diff --git a/docs/Workflow-Conflicts.rst b/docs/Workflow-Conflicts.rst deleted file mode 100644 index aa2e624..0000000 --- a/docs/Workflow-Conflicts.rst +++ /dev/null @@ -1,2 +0,0 @@ -Fix Conflicts -============= diff --git a/docs/Workflow-Create-Branch.rst b/docs/Workflow-Create-Branch.rst deleted file mode 100644 index 8e6a37a..0000000 --- a/docs/Workflow-Create-Branch.rst +++ /dev/null @@ -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. diff --git a/docs/Workflow-Create-Github-Account.rst b/docs/Workflow-Create-Github-Account.rst deleted file mode 100644 index f55e1f9..0000000 --- a/docs/Workflow-Create-Github-Account.rst +++ /dev/null @@ -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 `__. - -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/ `__ - -In addition, the following articles might be useful: - -- `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/adding-a-fallback-authentication-method-with-recover-accounts-elsewhere/ `__ diff --git a/docs/Workflow-Create-Test.rst b/docs/Workflow-Create-Test.rst deleted file mode 100644 index 2cdc94b..0000000 --- a/docs/Workflow-Create-Test.rst +++ /dev/null @@ -1,2 +0,0 @@ -Create a New Test -================= diff --git a/docs/Workflow-Delete-Branch.rst b/docs/Workflow-Delete-Branch.rst deleted file mode 100644 index 12046bb..0000000 --- a/docs/Workflow-Delete-Branch.rst +++ /dev/null @@ -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. diff --git a/docs/Workflow-Generate-PR.rst b/docs/Workflow-Generate-PR.rst deleted file mode 100644 index 36751d7..0000000 --- a/docs/Workflow-Generate-PR.rst +++ /dev/null @@ -1,2 +0,0 @@ -Generate a PR -============= diff --git a/docs/Workflow-Get-Source.rst b/docs/Workflow-Get-Source.rst deleted file mode 100644 index 1b5746c..0000000 --- a/docs/Workflow-Get-Source.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. raw:: html - - - -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 `__ -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 `__, you can fork the Github -repository and prepare the source by using the following process. - -1. Go to the `ZFS on Linux Project `__ - 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/ `__. -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. diff --git a/docs/Workflow-Install-Git.rst b/docs/Workflow-Install-Git.rst deleted file mode 100644 index 3bdaceb..0000000 --- a/docs/Workflow-Install-Git.rst +++ /dev/null @@ -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 `__. - -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 diff --git a/docs/Workflow-Large-Features.rst b/docs/Workflow-Large-Features.rst deleted file mode 100644 index 0f5a0d3..0000000 --- a/docs/Workflow-Large-Features.rst +++ /dev/null @@ -1,2 +0,0 @@ -Adding Large Features -===================== diff --git a/docs/Workflow-Merge-PR.rst b/docs/Workflow-Merge-PR.rst deleted file mode 100644 index c757290..0000000 --- a/docs/Workflow-Merge-PR.rst +++ /dev/null @@ -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. diff --git a/docs/Workflow-Rebase.rst b/docs/Workflow-Rebase.rst deleted file mode 100644 index 9e5ed5d..0000000 --- a/docs/Workflow-Rebase.rst +++ /dev/null @@ -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 `__ -page). - -This would also be a good time to -`squash `__ your -commits. diff --git a/docs/Workflow-Squash.rst b/docs/Workflow-Squash.rst deleted file mode 100644 index efa08d1..0000000 --- a/docs/Workflow-Squash.rst +++ /dev/null @@ -1,2 +0,0 @@ -Squash the Commits -================== diff --git a/docs/Workflow-Test.rst b/docs/Workflow-Test.rst deleted file mode 100644 index 8b64adc..0000000 --- a/docs/Workflow-Test.rst +++ /dev/null @@ -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 `__ 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 `__ 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 `__ -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 `__ -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. diff --git a/docs/Workflow-Update-PR.rst b/docs/Workflow-Update-PR.rst deleted file mode 100644 index 8d02c30..0000000 --- a/docs/Workflow-Update-PR.rst +++ /dev/null @@ -1,2 +0,0 @@ -Update a PR -=========== diff --git a/docs/Workflow-Zloop-Debugging.rst b/docs/Workflow-Zloop-Debugging.rst deleted file mode 100644 index 1e5d344..0000000 --- a/docs/Workflow-Zloop-Debugging.rst +++ /dev/null @@ -1,2 +0,0 @@ -Debugging *Zloop* Failures -==========================