ddc56b0106
The open-zfs.org host, Dreamhost, returns a page for https://open-zfs.org (note, httpS://) which causes HTTPS Everywhere with the 'Encrypt All Eligible Sites' option enabled to redirect http://open-zfs.org to https://open-zfs.org, and therefore fail to redirect to openzfs.org. Ideally a redirect would be implemented at Dreamhost for httpS://open-zfs.org too, but presumably the links in the docs should really be updated anyway.
211 lines
6.5 KiB
ReStructuredText
211 lines
6.5 KiB
ReStructuredText
Git and GitHub for beginners (ZoL edition)
|
|
==========================================
|
|
|
|
This is a very basic rundown of how to use Git and GitHub to make
|
|
changes.
|
|
|
|
Recommended reading: `ZFS on Linux
|
|
CONTRIBUTING.md <https://github.com/zfsonlinux/zfs/blob/master/.github/CONTRIBUTING.md>`__
|
|
|
|
First time setup
|
|
----------------
|
|
|
|
If you've never used Git before, you'll need a little setup to start
|
|
things off.
|
|
|
|
::
|
|
|
|
git config --global user.name "My Name"
|
|
git config --global user.email myemail@noreply.non
|
|
|
|
Cloning the initial repository
|
|
------------------------------
|
|
|
|
The easiest way to get started is to click the fork icon at the top of
|
|
the main repository page. From there you need to download a copy of the
|
|
forked repository to your computer:
|
|
|
|
::
|
|
|
|
git clone https://github.com/<your-account-name>/zfs.git
|
|
|
|
This sets the "origin" repository to your fork. This will come in handy
|
|
when creating pull requests. To make pulling from the "upstream"
|
|
repository as changes are made, it is very useful to establish the
|
|
upstream repository as another remote (man git-remote):
|
|
|
|
::
|
|
|
|
cd zfs
|
|
git remote add upstream https://github.com/zfsonlinux/zfs.git
|
|
|
|
Preparing and making changes
|
|
----------------------------
|
|
|
|
In order to make changes it is recommended to make a branch, this lets
|
|
you work on several unrelated changes at once. It is also not
|
|
recommended to make changes to the master branch unless you own the
|
|
repository.
|
|
|
|
::
|
|
|
|
git checkout -b my-new-branch
|
|
|
|
From here you can make your changes and move on to the next step.
|
|
|
|
Recommended reading: `C Style and Coding Standards for
|
|
SunOS <https://www.cis.upenn.edu/~lee/06cse480/data/cstyle.ms.pdf>`__,
|
|
`ZFS on Linux Developer
|
|
Resources <https://github.com/zfsonlinux/zfs/wiki/Developer-Resources>`__,
|
|
`OpenZFS Developer
|
|
Resources <https://openzfs.org/wiki/Developer_resources>`__
|
|
|
|
Testing your patches before pushing
|
|
-----------------------------------
|
|
|
|
Before committing and pushing, you may want to test your patches. There
|
|
are several tests you can run against your branch such as style
|
|
checking, and functional tests. All pull requests go through these tests
|
|
before being pushed to the main repository, however testing locally
|
|
takes the load off the build/test servers. This step is optional but
|
|
highly recommended, however the test suite should be run on a virtual
|
|
machine or a host that currently does not use ZFS. You may need to
|
|
install ``shellcheck`` and ``flake8`` to run the ``checkstyle``
|
|
correctly.
|
|
|
|
::
|
|
|
|
sh autogen.sh
|
|
./configure
|
|
make checkstyle
|
|
|
|
Recommended reading: `Building
|
|
ZFS <https://github.com/zfsonlinux/zfs/wiki/Building-ZFS>`__, `ZFS Test
|
|
Suite
|
|
README <https://github.com/zfsonlinux/zfs/blob/master/tests/README.md>`__
|
|
|
|
Committing your changes to be pushed
|
|
------------------------------------
|
|
|
|
When you are done making changes to your branch there are a few more
|
|
steps before you can make a pull request.
|
|
|
|
::
|
|
|
|
git commit --all --signoff
|
|
|
|
This command opens an editor and adds all unstaged files from your
|
|
branch. Here you need to describe your change and add a few things:
|
|
|
|
::
|
|
|
|
|
|
# Please enter the commit message for your changes. Lines starting
|
|
# with '#' will be ignored, and an empty message aborts the commit.
|
|
# On branch my-new-branch
|
|
# Changes to be committed:
|
|
# (use "git reset HEAD <file>..." to unstage)
|
|
#
|
|
# modified: hello.c
|
|
#
|
|
|
|
The first thing we need to add is the commit message. This is what is
|
|
displayed on the git log, and should be a short description of the
|
|
change. By style guidelines, this has to be less than 72 characters in
|
|
length.
|
|
|
|
Underneath the commit message you can add a more descriptive text to
|
|
your commit. The lines in this section have to be less than 72
|
|
characters.
|
|
|
|
When you are done, the commit should look like this:
|
|
|
|
::
|
|
|
|
Add hello command
|
|
|
|
This is a test commit with a descriptive commit message.
|
|
This message can be more than one line as shown here.
|
|
|
|
Signed-off-by: My Name <myemail@noreply.non>
|
|
Closes #9998
|
|
Issue #9999
|
|
# Please enter the commit message for your changes. Lines starting
|
|
# with '#' will be ignored, and an empty message aborts the commit.
|
|
# On branch my-new-branch
|
|
# Changes to be committed:
|
|
# (use "git reset HEAD <file>..." to unstage)
|
|
#
|
|
# modified: hello.c
|
|
#
|
|
|
|
You can also reference issues and pull requests if you are filing a pull
|
|
request for an existing issue as shown above. Save and exit the editor
|
|
when you are done.
|
|
|
|
Pushing and creating the pull request
|
|
-------------------------------------
|
|
|
|
Home stretch. You've made your change and made the commit. Now it's time
|
|
to push it.
|
|
|
|
::
|
|
|
|
git push --set-upstream origin my-new-branch
|
|
|
|
This should ask you for your github credentials and upload your changes
|
|
to your repository.
|
|
|
|
The last step is to either go to your repository or the upstream
|
|
repository on GitHub and you should see a button for making a new pull
|
|
request for your recently committed branch.
|
|
|
|
Correcting issues with your pull request
|
|
----------------------------------------
|
|
|
|
Sometimes things don't always go as planned and you may need to update
|
|
your pull request with a correction to either your commit message, or
|
|
your changes. This can be accomplished by re-pushing your branch. If you
|
|
need to make code changes or ``git add`` a file, you can do those now,
|
|
along with the following:
|
|
|
|
::
|
|
|
|
git commit --amend
|
|
git push --force
|
|
|
|
This will return you to the commit editor screen, and push your changes
|
|
over top of the old ones. Do note that this will restart the process of
|
|
any build/test servers currently running and excessively pushing can
|
|
cause delays in processing of all pull requests.
|
|
|
|
Maintaining your repository
|
|
---------------------------
|
|
|
|
When you wish to make changes in the future you will want to have an
|
|
up-to-date copy of the upstream repository to make your changes on. Here
|
|
is how you keep updated:
|
|
|
|
::
|
|
|
|
git checkout master
|
|
git pull upstream master
|
|
git push origin master
|
|
|
|
This will make sure you are on the master branch of the repository, grab
|
|
the changes from upstream, then push them back to your repository.
|
|
|
|
Final words
|
|
-----------
|
|
|
|
This is a very basic introduction to Git and GitHub, but should get you
|
|
on your way to contributing to many open source projects. Not all
|
|
projects have style requirements and some may have different processes
|
|
to getting changes committed so please refer to their documentation to
|
|
see if you need to do anything different. One topic we have not touched
|
|
on is the ``git rebase`` command which is a little more advanced for
|
|
this wiki article.
|
|
|
|
Additional resources: `Github Help <https://help.github.com/>`__,
|
|
`Atlassian Git Tutorials <https://www.atlassian.com/git/tutorials>`__
|