====== Github ======
=====Introduction=====
 
Our account on GitHub is here: https://github.com/elrepo

Please sign up for an account at github.

We have set up 3 "repositories" under the elrepo organization - packages, templates, and kernel. Hopefully these are self explanatory.

The templates repo is for the templates we maintain.
The packages repo is for packages in elrepo, elrepo-testing and elrepo-extras, etc.
The kernel repo is for the kernel-ml and kernel-lt packages.

The structure for packages is: elrepo/packages/foo-kmod/{el7,el8,el9}/

The contents of elrepo/packages/foo-kmod/{el7,el8,el9}/ would typically include the SPEC file, kmodtool, GPL-v2.txt, Makefile, foo.c, and patches etc as required. Basically anything that elrepo contributes to the package that we might want to track changes for.

The contents of elrepo/kernel would include the SPEC file and the CONFIG file.

If you simply use a source.tar.bz2 untouched then it's __not__ necessary to commit that to the repository.

=====Setting up elrepo GitHub=====

First register for an account on GitHub. Then:

1. Install the following git-related packages:
git
gitk
gitweb
git-gui
perl-Git
git-email

only git and dependencies are really needed.

There is a help page here: http://help.github.com/linux-set-up-git/

2. You will need a public ssh key - many people will already have one of these.  The directions on http://help.github.com/linux-set-up-git/ are a bit ambiguous, and if not read and interpreted carefully might lead one to delete the existing ~/.ssh directory and public/private key pairs.  That is not necessary nor desirable.

3. Add your SSH public key to GitHub. On the GitHub site, Click Account Settings -> Click SSH Public Key-> Click New GPG key as described in the helpfile (#4): http://help.github.com/linux-set-up-git/

4. Set your username and email.
<code>
 $ git config --global user.name "Firstname Lastname" 
 $ git config --global user.email "your_email@youremail.com" 
</code>

See changes in ~/.gitconfig:
<code>
$ cat .gitconfig
[user]
        name = Bob Smith
        email = bsmith@example.com

[core]
        editor = vim 
</code>
The last section may be added as desired,  Substitute your favorite editor if it is different.

5. Fork your repo.

There are two repositories, //packages// and //templates//. Normally only //packages// is required for outside contributors.

Go to the ELRepo //packages// repository on the github web site ( https://github.com/elrepo/packages )

Click the "Fork" button (near the upper, right-hand side corner)
Click the "Fork to <username>" button

When finished, you will be in <username>/packages (forked from elrepo/packages)

6. Now set up your local copy of the repositories for the first time:

<code>$ mkdir -p ~/github

$ cd ~/github/
$ git clone git@github.com:<username>/packages.git
</code>
If your username is bob, it will be:

<code>$ git clone git@github.com:bob/packages.git
</code>
You now have an up to date copy of the //packages// repository.

When a repo is cloned, it has a default remote called //origin// that points to **your** fork on GitHub, **not** the original repo it was forked from. To keep track of the original repo, you need to add another remote named //upstream//:

<code>
$ cd packages
$ git remote add upstream git://github.com/elrepo/packages.git
$ git fetch upstream
</code>

=====Workflow=====

This section will describe the typical workflow one might employ for a typical git session with example commands to help you along the way.

The remote GitHub server is the master server and we all keep local client copies of the repository.

A general workflow would involve :

(1) pull the latest updates in from the master GitHub repo (upstream), \\
(2) update your fork by merging from upstream, \\
(3) make some additions, edits, changes and maybe test your edits by doing some test compiles etc,  \\
(4) add any new files to your fork,  \\
(5) commit any changes and  \\
(6) push the changes to your fork on the GitHub. \\
(7) send a pull request on the github web site. \\

So lets see how that might look in practice:

Suppose we want to edit the README file in the packages repo:
<code>
$ cd ~/github/packages   
$ git fetch upstream  <-- (1) 
$ git merge upstream/master  <-- (2)
</code>
make some edits to README <-- (3)
<code>
$ git add README  <-- (4)
$ git commit -s -m 'README: fixed a typo'  <-- (5)
$ git status   <-- not required but a good practice
$ git push   <-- (6)
</code>
Go to the GitHub web site and click the "Pull Request" button (look for something in green). <-- (7)

Suppose you edit a few files, you can commit all changes in one go with 'commit -a'.

Another useful command is 'git diff master origin/master' to see the diffs between your local branch (master) and the remote branch (origin/master).

Suppose we want to import a new kmod package for el8 into the repository:
<code>
$ cd ~/github/packages 
$ git fetch upstream 
$ git merge upstream/master 
$ mkdir -p hellop-kmod/el8 
</code>
copy files into ~/github/packages/hellop-kmod/el8
edit files as necessary
<code>
$ git add hellop-kmod/el8/* 
$ git commit -s -m 'hellop-kmod: initial commit of hellop-kmod package v0.5-1' 
$ git push 
</code>
We used a wildcard to add all files 'git add hellop-kmod/el8/*' but we could just as easily added them individually with 'git add hellop-kmod/hellop.spec' etc.


A simple 'git commit' may suffice as an editor will pop up allowing you to enter the commit text.

General git help/manual is here: http://www.kernel.org/pub/software/scm/git/docs/