Skip to content

Instantly share code, notes, and snippets.

@lspector
Forked from thelmuth/GitHub-help.md
Created September 2, 2012 08:27
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save lspector/3595867 to your computer and use it in GitHub Desktop.
Save lspector/3595867 to your computer and use it in GitHub Desktop.
Help file for contributors to any CI Lab project on GitHub.

General Info

  • The master branch is the stable main branch. No one should ever need to edit the master branch, and even if they do, they should definitely never push it to the Github repository. All changes to master will come as merges from other branches, which Lee will be responsible for merging with master.

  • Branches are easy and cheap to create, and should be used extensively. If you ever want to "try something out", make sure you branch from master (or some other branch) first. If you want to add a feature to a project permanently, create a branch for it while you test it, and once the bugs are ironed out, then it can be merged to master (by Lee or whoever is managing the project). If you find a bug in master, create a branch to fix it. If you want to add some code for an experiment for a paper, create a branch for it. I cannot emphasize enough: things will be easier for all of us if we always create branches for any changes to master that we need.

  • Whenever Lee updates master by merging in a branch, everyone else will need to download that change and merge it manually into all branches that may eventually contribute to master. For example, if you have branches new_feature, bug_fix, and crazy_thing_that_will_never_be_added_to_the_project, you should definitely merge a new master branch into new_feature and bug_fix, since these will likely end up in the project someday. It's probably fine not to merge it into the third branch, since it will likely never leave your repository, but unless it breaks things, might still be a good idea.

How-To

Create a New Feature for a Project

Do this if you want to create a new feature for a CI Lab project.

  1. Create a new branch from master to implement and test the feature.

     $ git checkout master
     $ git branch new_feature
     $ git checkout new_feature
    
  2. Make your changes to the code.

  3. Commit those changes in one or more commits.

     $ git add [filename(s)] OR $ git add .
     $ git commit
    
  4. Push your branch to Github.

     $ git push origin new_feature
    
  5. Tell Lee about the new branch, either by email, or by a pull request.

Merge in Changes from master

Every time that Lee makes changes to master, we will all need to merge them into any open branches that we have in our local repositories.

  1. Lee tells us that master has changed.

  2. Fetch the changes to master from Github.

     $ git fetch origin
    
  3. Merge the changes into your master branch; this should not have merge conflicts.

     $ git checkout master
     $ git merge origin/master
    
  4. For any local branch my_branch that may eventually end up in the project:

  5. Merge the changes into my_branch; this may have merge conflicts.

     $ git checkout my_branch
     $ git merge origin/master
    
  6. If there are merge conflicts, resolve them and commit.

     $ (edit conflicting files)
     $ git add [filename(s)]
     $ git commit
    

Merge Changes Into master (Lee only)

For Lee to integrate code into master, whether from one of his branches or one of ours, he will need to merge that branch into master. He should only do this for code that he wants to be included in the main branch of the project, which is the body of code that everyone will have in common, and will be used by people outside our lab.

  1. Let's call the branch to be merged feature_branch.

  2. If feature_branch is Lee's creation, skip the next step.

  3. Fetch the branch from the Github repository.

     $ git fetch origin
    
  4. Create local branch temp to inspect and test changes.

     $ git branch temp origin/feature_branch
     $ git checkout temp
     $ (test and look at code. to look at difference from master: $git diff master)
    
  5. Make any necessary changes to the code and update the version number.

     $ (make changes)
     $ (update version number in project.clj to "A.B.C")
     $ git add [filename(s)] OR $git add . OR $git add -u  (the last one also removes deleted files from the repository)
     $ git commit
    
  6. Checkout master and merge in the new branch, and then delete temp. This should not have conflicts; if it does, the contributor did not merge in previous changes to master, and they should do so before doing this.

     $ git checkout master
     $ git merge temp
     $ git branch -d temp
    
  7. Tag this commit with the new version number.

     $ git tag -a vA.B.C -m 'Version message here'
    
  8. Push the new master branch to Github, as well as your tags.

     $ git push origin master
     $ git push origin --tags
    
  9. Lee now tells the lab to fetch this master branch to merge it with their branches.

  10. Merge master with all your branches, including working. See "Merge in Changes from master" section above.

  11. feature_branch can now be deleted; to delete the branch on the Github repository:

    $ git push origin :feature_branch
    
  12. Checkout whatever branch you're working on.

    $ git checkout working
    
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment