Using GitHub with the Worklist Project

Table of Contents

I. Worklist-Github Flow
II. Setting Up Your Sandbox Environment
III. Development & Deployment

### I. Worklist-Github flow ###

First time Bidders for the Worklist project will be asked to authorize the "worklist" application to use your Github account. This is required so that we can use the API to make fork, pull and merge requests on your behalf.

Prior to your first accepted bid on a Github Worklist project you will not have a fork of the repository. On bid acceptance, we will create a fork of Worklist's master repository in your Github account. At this point you have a new git repository that has one branch, the master branch. It is a copy of the Worklist master repository at that point in time.

For any accepted bid on a Worklist Github project (whether it's the first or the 1000th), we will create a branch in your forked repository named as the job number for which your bid was accepted. It is branched from the Worklist's master repository for that project and therefore is an up to date version of the code for that project.

This branch is where you will push all modifications.

### II. Setting Up Your Sandbox Environment

A sandbox will need to be created in our development environment. This facilitates testing for the Developers as well as the Designers and allows access to the dev_worklist database. The following steps assume that you already have an account on dev.worklist.net. Developers who do not have an account should contact one of our operations staff (either @lieutdan13 or @murillodigital) to have an account created. Note that steps 1 through 3 below will only need to be completed for your first job.

1. You will first need to clone the repository from your github account to your dev account. SSH into dev.worklist.net, cd to your public_html directory and run the following:

   $ git clone https://github.com/YOURGITHUBNAME/worklist
   

   This creates a sandbox for you.

2. Run the setup script in your worklist directory:

   $ cd worklist
   $ ./setup.sh
   

3. Get the current version to merge changes into your sandbox. This step should be performed during the course of your work to ensure that your files are up to date and to avoid conflicts.

   $ git pull upstream master
   

### III. Development & Deployment

8. Perform the work necessary to complete your job. Once you are satisfied that the code is working, set the job to QA Ready in Worklist for Designer approval. When the Designer gives the green light, stage and commit your changes in preparation for a Pull Request (PR) and code review.

9. Switch to the branch created for your job:

   $ git branch jobnumber
   

10. Check out the branch:

    $ git checkout jobnumber
    

11. Add your changed files to the branch:

    $ git add <filename>
    

    for each file you have updated

12. Verify that your changes are cached:

    $ git diff --cached
    

    to see a list of every staged diff

13. Commit your changes to your branch:

    # please avoid job numbers alone, use a quick but descriptive message instead
    $ git commit -m "description goes here"
    

14. For first commit, you will get a "Please tell me who you are." message. Run the following:

    $ git config --global user.email "you@example.com"
    

    $ git config --global user.name "Your Name"
    

15. Push the changes to your branch:

    $ git push 
    

16. In Worklist, set the job to Code Review. This will automatically create a Pull Request.

17. Once the Code Review is approved and your changes have been merged into the highfidelity/worklist master repository, set your job to Merged in Worklist.

---