Help file for contributors to any CI Lab project on GitHub.

GitHub-help.md

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, where remotename is the name of the remote (such as thelmuth or etosch).

    $ git fetch remotename
   

4. If git complains that the thing that you're trying to fetch is not a git repository then you may have to create a remote for the repository. If the user who created it has a git name of sally, for example, and if it is a repository for the Clojush project, then you should issue the command git remote add sally https://github.com/sally/Clojush.git. Then you should be able to successfully do git fetch sally.

5. Checkout master and merge in the new branch. 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 remotename/feature_branch
   

6. 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
   

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. Create jar and copy to Clojars.

    $ lein clean
    $ lein jar
    $ lein pom
    $ lein deploy clojars
   

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

11. Checkout whatever branch you're working on.

    $ git checkout working
    

12. Lee now tells the lab to fetch this master branch to merge it with their branches.

Would it make sense to move this to the Github wiki for Clojush so it's with the code?