Initial commit for GitHub reference documentation for forking/branching/pullrequest

docs/source/developers/git/index.rst

@@ -1,14 +0,0 @@
-Git
-===
-
-xCAT uses git for source code version control.  There are many resources and documentation available to help you learn git.  A great place to start would be: http://git-scm.com/doc
-
-* https://training.github.com/kit/downloads/github-git-cheat-sheet.pdf
-
-
-
-
-.. toctree::
-   :maxdepth: 2
-
-

docs/source/developers/github/change_code.rst

@@ -0,0 +1,40 @@
+Changing Code
+=============
+
+Checkout Branch
+---------------
+
+Checkout and switch to the branch using ``git checkout -b`` ::
+
+        $ git checkout -b mybranch origin/mybranch
+        Branch mybranch set up to track remote branch mybranch from origin.
+        Switched to a new branch 'mybranch'
+
+
+Changing the code
+-----------------
+
+Now you are ready to make changes related to your function in this branch 
+
+Multiple Remote Branches
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+It may take days before your pull request is properly reviewed and you want to keep changes out of that branch so in the event that you are asked to fix something, you can push directly to the branch with the active pull request.  
+
+Creating additional branches will allow you to work on on different tasks/enhancements at the same time.  You can easily manage your working changes between branches with ``git stash.``.
+
+
+Commiting code and pushing to remote branch
+-------------------------------------------
+
+Once your code is ready....
+
+#. Commit the code to your local branch: ::
+
+        $ git add <files> 
+        $ git commit | git commit -m "<comments>"
+
+#. Push the changes to your remote branch: ::
+
+        $ git push origin <branch name>
+

docs/source/developers/github/create_branches.rst

@@ -0,0 +1,78 @@
+Creating Branches
+=================
+
+**Note:** To more easily keep the forked repository and upstream repositories in sync, we recommended that you keep your master branch free from changes and create branches to contain the changes in function you are working on.
+
+Local Branches
+--------------
+
+Git branches are very light weight and easy to create.  Simply use the ``git branch <branch_name>`` command. 
+
+Since we are using pull requests to merge changes back to the upstream project, you will need to have your changes committed to a branch on GitHub (calling this a "remote branch") so that GitHub can detect differences and pull requests can be created.
+
+Remote Branches
+---------------
+
+Reference articles: 
+* http://www.gitguys.com/topics/adding-and-removing-remote-branches/
+
+
+From GitHub
+^^^^^^^^^^^
+
+* Under your repository, click on the **Branch** dropdown and type in a name for the new branch, then hit enter.
+
+  In the example below, creating a new branch off 'master' called ``DOC_MERGE``
+
+
+.. image:: github-create_branch.png
+
+
+* Since we created the branch from the UI, a refresh needs to be done in order to see the new branch.  Refresh by fetching from the origin repository: ::
+
+        $ git fetch origin
+        Enter passphrase for key '/home/vhu/.ssh/github/id_rsa': 
+        From github.com:whowutwut/xcat-doc
+         * [new branch]      DOC_MERGE  -> origin/DOC_MERGE
+
+* Show the remote branches: ``git branch -r`` ::
+
+        $ git branch -r
+          origin/HEAD -> origin/master
+          origin/large_cluster
+          origin/master
+          origin/DOC_MERGE  <=== NEW BRANCH
+          origin/sync
+          upstream/master
+
+
+From Command Line (CLI)
+^^^^^^^^^^^^^^^^^^^^^^^
+
+* Create a branch: ::
+
+      $ git branch
+      * master
+
+      $ git branch skeleton 
+
+      $ git branch 
+      * master
+        skeleton
+
+* Push the newly created branch to origin (on GitHub): ::
+
+      $ git push origin skeleton 
+      Enter passphrase for key '/home/vhu/.ssh/github/id_rsa': 
+      Total 0 (delta 0), reused 0 (delta 0)
+      To git@github.com:whowutwut/xcat-doc.git
+       * [new branch]      skeleton -> skeleton
+
+  Verify that the branch is there by looking at the remote branches: :: 
+
+      $ git branch -r
+        origin/HEAD -> origin/master
+        origin/master
+        origin/skeleton   <=== HERE IT IS 
+        upstream/master
+

docs/source/developers/github/delete_branches.rst

@@ -0,0 +1,35 @@
+Deleting Branches
+=================
+
+From Command Line
+-----------------
+
+Switch off the branch that you want to delete. Most of the time, switching to master will allow you to delete a working branch: ::
+
+        $ git checkout master
+        $ git branch -D mybranch
+
+Delete the remote branch off GitHub: ::
+
+        $ git push origin --delete mybranch
+        Enter passphrase for key '/home/vhu/.ssh/github/id_rsa': 
+        To git@github.com:whowutwut/xcat-doc.git
+         - [deleted]         mybranch
+
+Verify branch is gone: ::
+
+        $ git branch -r
+          origin/HEAD -> origin/master
+          origin/large_cluster
+          origin/master
+          origin/sync
+          upstream/master
+
+
+
+Sync up GitHub and Local Machine
+--------------------------------
+
+There are times when you delete the branch off your local machine or from GitHub and it's become out of sync, you sync up the list, run the following: ::
+
+        git remote prune origin 

docs/source/developers/github/forks.rst

@@ -0,0 +1,52 @@
+Fork a repository
+=================
+
+Forking a repository is taking a copy of a GitHub repository and associating it to your own account space so you can make changes to the code base.  Since you own this copy, you will have fetch/push access to the repository.
+
+We will first create a fork on the xcat2/xcat-core project so that we can work on functions without affecting the mainline (or *upstream*) code.  Additionally, by creating a fork, you are able to generate *pull request* so that the changes can be easily seen and reviewed by other community members. 
+
+* In GitHub UI, find a project that you want to fork and click on the "Fork" icon.  
+
+  .. image:: github-fork.png
+
+  **Note:** The target is your own account space
+
+* After the fork is created, there is a copy of the repository under your own account
+
+  ``<userid>/xcat-core`` <-- forked copy
+
+  ``xcat2/xcat-core``     <-- upstream 
+
+
+Clone the forked repository
+===========================
+
+* On your development machine, clone the forked repository from **your** account: 
+
+  **Note:** Ensure the clone is from *<userid>/xcat-core* and **not** *xcat2/xcat-core* ::
+
+      $ git clone git@github.com:<userid>/xcat-core.git
+
+  This now becomes the origin remote repository: ::
+
+      $ git remote -v 
+      origin  git@github.com:<userid>/xcat-core.git (fetch)
+      origin  git@github.com:<userid>/xcat-core.git (push)
+
+
+Configure an ``upstream`` repository
+====================================
+
+* In order to get updates from the upstream project: ``xcat2/xcat-core``, you will need to add another remote repository to fetch from. ::
+
+      $ git remote add upstream git@github.com:xcat2/xcat-core.git
+
+  View the configured reposotories: ::
+
+      $ git remote -v 
+      origin  git@github.com:<userid>/xcat-core.git (fetch)
+      origin  git@github.com:<userid>/xcat-core.git (push)
+      upstream        git@github.com:xcat2/xcat-core.git (fetch)
+      upstream        git@github.com:xcat2/xcat-core.git (push)
+
+

docs/source/developers/github/index.rst

@@ -0,0 +1,30 @@
+
+GitHub
+======
+
+Developers are encouraged to fork the `xcat2 <https://github.com/xcat2>`_ repositories, make changes, and submit pull requests.  This mechanism allows for better collaboration and gives the community a chance to review and provide feedback before the code is pulled into the product. 
+
+GitHub provides execllent documentation on `Collaborating <https://help.github.com/categories/collaborating/>`_ and the following is only provided as a quick reference. 
+
+Getting Started
+---------------
+
+.. toctree::
+   :maxdepth: 2
+
+   forks.rst 
+
+
+Changing Code and Pull Requests
+-------------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   syncing_forks.rst 
+   create_branches.rst 
+   change_code.rst 
+   pull_request.rst
+   delete_branches.rst
+
+

docs/source/developers/github/pull_request.rst

@@ -0,0 +1,33 @@
+Pull Requests
+=============
+
+Creating Pull Requests
+----------------------
+
+Once your changes are ready to be submitted to the xcat team, the easiest way to generate a pull request is from the GitHub UI. 
+
+#. Under your project, click on the "branches" link
+
+   .. image:: github-pullrequest_branch.png
+
+#. Find the branch that contains your changes and click on the "New pull request" button
+
+   .. image:: github-create_pullrequest.png
+
+#. Submit the pull request!
+
+
+Reviewing Pull Requests as a Maintainer
+---------------------------------------
+
+When you are looking over a pull request, you can merge the changes into your own temporary branch to give the code or changes a try before merging into the parent project. 
+
+#. From the merge request, click on the ``command line instructions`` link: 
+
+   .. image:: github-merge_command_line.png
+
+#. Then under **Step 1:**, there are instruction for creating a temp branch and pulling the changes from the pull request: 
+
+   .. image:: github-merge_step1.png 
+
+

docs/source/developers/github/syncing_forks.rst

@@ -0,0 +1,52 @@
+Syncing a Fork
+==============
+
+**Note:** *The examples below all reference the master branch*
+
+References: https://help.github.com/articles/syncing-a-fork/
+
+From time to time, your master branch will start to fall behind the upstream/master because changes are being pulled into the `xcat2/xcat-core`` project from other developers. 
+
+.. image:: github-behind_master.png
+
+Use the following steps to sync up your forked copy: 
+
+Fetching commits from upstream to your local
+--------------------------------------------
+
+#. Fetch the upstream changes for the master branch.  (changed are stored in a local branch: ``upstream/master``) ::
+
+      $ git fetch upstream
+      Enter passphrase for key '/home/vhu/.ssh/github/id_rsa': 
+      From github.com:xcat2/xcat-core
+       * [new branch]      master     -> upstream/master
+
+ 
+#. Switch to your master branch and merge from upstream/master: ::
+
+      $ git checkout master
+      Switched to branch 'master'
+      
+      $ git merge upstream/master
+      Updating a24d02f..f531ff8
+      Fast-forward
+      ...
+     
+Pushing the merged changes from your local to your remote fork
+--------------------------------------------------------------
+
+The following is needed to push the changes that you merged from upstream into your local clone on your development machine to the remote GitHub repository.
+
+#. Sync the changes in your master branch to GitHub: ::
+
+      $ git push origin master
+
+
+Your fork master branch should now be even with ``xcat2/xcat-core``
+
+.. image:: github-even_with_master.png 
+
+
+
+
+

docs/source/developers/index.rst

@@ -7,8 +7,8 @@ This page is for developers interested in working with xCAT.
 .. toctree::
    :maxdepth: 2
 
+   license/index.rst
+   github/index.rst
    developer_guide.rst
    programming_tips.rst
    debug_xcat.rst
-   license/index.rst
-   git/index.rst