Open main menu

CDOT Wiki β

DPS909 & OSD600 Winter 2017

Resources for DPS909 & OSD600

Week 1

  • Course introduction
  • Some questions:
    • What was the first video game you ever played?
    • What are your main technical strengths, which technologies do you know well and enjoy?
    • Which (new) technologies are you excited to learn and try?
    • When you hear "open source," what comes to mind?
    • Do you have any hesitation, fears, or anxieties about working in open source projects?
  • How to have Success in this course:
    • Willingness to be lost and not panic
    • Willingness to put yourself out there, jump in
    • Curiosity
    • Being driven, persistence
    • Willingness to ask for help
    • Willingness to give others help
    • Independent learning
    • Doing more than the bare minimum

Week 2

Week 3

Week 4

  • Working with git Branches
  • Lightweight, movable, reference (or pointer) to a commit
  • Series of commits: a branch is the furthest tip of a line of commits
  • It is always safe to branch, it won't change the code in any way
  • Relationship of git commit with branches
    • commit SHA: e0ee2b5acd01acbe5b0bc1ee24b73e5d53a1fd70 or shortened to e0ee2b5
    • HEAD: the most recent commit (NOTE: you can also do HEAD~2 to mean 2 commits older than HEAD or HEAD~5 to mean 5 commits older than HEAD),
    • branch: an easy to remember name we give to the current commit, e.g., master
    • master branch vs. "Topic Branches": all work happens on a new branch
  • creating, switching between, updating
    • git branch <branch name>: -d (maybe delete), -D (force delete), -m (rename), -a (list all)
    • git checkout <branch name | commit SHA>, discussion of "detached HEAD"
    • git checkout -b <branch name> [<base commit> | HEAD](create if doesn't exist, checkout new branch)
    • git checkout -B <branch name> [<base commit> | HEAD] (create or reset, checkout new branch)
  • local vs. remote, tracking branches
    • Branches are always local to your current repo
    • git branch -a will show all of your branches, and any/all remote branches (i.e., branches in remote repos your repo knows about via git fetch)
    • Example: git checkout -b bug123 friend-repo/bug123 will create a branch bug123 locally that is pointing at the same commit as the remote repo friend-repo's bug123 branch.
    • Any branch you check out that is based on a remote branch will be tracked by git, and any commits they have ahead of you, or you have ahead of them, will get reported
  • common workflow
    • git checkout master - switch to master branch
    • git pull upstream master - pull in any new commits from the upstream/master branch
    • git checkout -b issue-1234 - create a topic branch for your work, named with bug #
    • git add files - edit files, add to staging area
    • git commit -m "Fix #1234: ..." - commit changes, referencing bug # in commit message
    • git push origin issue-1234 - push your topic branch (and all commits) to your origin repo
    • create pull request
  • merging
    • A merge in git is a way of combining branches into a single branch/history
    • We always fix bugs and add features on new branches, but then we need to merge them back into the main master branch
    • Merging doesn't change any of the branches it combines, it simply connects them.
    • git merge <branch name> merges <branch name> into the currently checked out branch
    • Different merge algorithms
      • fast-forward merge - given identical histories, move the branch ahead in the history to the new tip
      • 3-way merge - divergent histories, use common ancestor commit (commit 1), and two branch tops (2, 3)
    • recall that git pull does a git fetch and git merge in one step
  • rebasing
    • Replay a series of commits on a different branch vs. the current one, rewriting its history
    • Often done with squashing (combining multiple commits into a single commit) on topic branches before merging with master to simplify the history
    • Because it rewrites history, you shouldn't do it on branches shared with other developers
    • git rebase <new-base>
    • After a rebase, it's easy to do fast-forward merges
    • git rebase -i starts an interactive rebase, and lets you specify what to do with each commit. git rebase --abort let's you stop it mid-way through.
    • If you need to squash the last few commits, you can use git rebase -i HEAD~2 for example.
  • conflicts while merging, rebasing
    • Git compares files at the line level: if two commits both change the same line(s), there will be a conflict
    • Git can't automatically resolve two competing changes to the same line(s), since it isn't clear which one is right--you have to do it manually
    • Using git status to discover which files have conflicts
    • Examining, understanding, and working with conflict markers ">>>>" and "<<<<"
    • git add and git commit
    • Here's a video demo of resolving merge conflicts manually
    • Various visual tools exist for doing this, too:
  • gh-pages

Week 5

  • Strategies for Understanding Code
    • RTFM (Read the F.....antastic Manual!): README.md, Contributing.md, website?, wiki? Read it. Twice. Mostly you want to start building up a list of keywords, common themes, and useful tips you can use later when you start trying things.
    • Bottom-Up: look at the code, directory structure, scan for file/dir names that related to your task. Don't get bogged down, just go for a walk in the code and take note of what you see.
    • Top-Down: try to find a UI string (e.g., menu name, button label) that you can search for within the code
    • Sideways Excavation: look at a similar code path or feature for clues about where you should work (e.g., want to add a new menu option to 'File', look at one of the existing ones)
    • Time Machine: use project history (commits, log messages, blame, issues) for info about how code was introduced and evolved
    • Clean Room: read the test/ code. What do the original devs think the code should do? How do they use it, when do they use, in what order to they call things, which code is related, etc.
    • Family Tree: find code in other projects/repos that uses the same code you're interested in. How does Project X use this API in their code? Use other people's code to build an understanding of what you should do (e.g., read extension code from https://brackets-registry.aboutweb.com/ to understand Brackets APIs)
    • Ask a Local: don't be afraid to ask for clarification from more experienced devs. Often they can narrow your search to a particular area of the code. Use mailing lists, ask in bugs/issues, discuss on chat systems, talk to people IRL!
    • Just Try Stuff: often the best thing to do is simply to try things. Create a new branch experiments and start adding logging, debug statements, delete things and see what happens, add things and see what happens, change things and see what happens! If you can break it, you can probably make it do something useful.
  • Tools for Understanding Code:
    • git grep
    • git blame
    • Search within commit messages: git log --grep "some string"
    • Search within the commit content for addition/removal of a string: git log -S "some string"
    • Search all branches: git log -S 'populate_database' --all
    • Search in date range: git log -p --since=2012-01-01 --until=2015-02-01
    • Log Formatting examples
      • git log --graph --pretty=oneline --decorate
      • git log --pretty=format:"%h %ad | %s%d [%an]" --graph --date=short
      • git log --graph --pretty=format:'%Cred%h%Creset %an: %s - %Creset %C(yellow)%d%Creset %Cgreen(%cr)%Creset' --abbrev-commit --date=relative
    • Searching on GitHub: Repositories, Code, Commits, Issues, Wikis

Week 6

  • Combining Open Source Projects
    • We'll work together to fix this bug: https://github.com/mozilla/thimble.mozilla.org/issues/1696
    • We'll try to add a sprite editor to Thimble for people to use for game programming, animations
    • We'll do it as an Extension to Brackets
    • Along the way we'll learn about working with code you don't know, integrating different projects, writing extensions, working with advanced web technologies and techniques, and we'll have some fun!

Week 7

Week 8

  • Code Review
    • A change to the project is done by a contributor and a reviewer (and maybe more than one of each).
    • No one is on their own doing work. No one is solely to blame for what happens next, good or bad.
    • Automated vs. Manual code review
      • Linters (eslint, standard, csslint, etc)
      • Build systems, task runners (grunt, gulp, etc)
      • Travis CI
    • Code review as scaling factor: enabling contributions
    • Code review has nothing to do with how good you are at programming, isn't a value statement about you.
  • Questions
    • Do you need review on a one line change? A one word change? Why?
    • What are the types of changes/results that you need to review? What is the process like?
    • How does code review differ from pair programming, or working directly with a partner in the class/office?
  • 0.2 Release (Due Tues Mar 7)
    • What worked?
    • What didn't?
    • What do you need to do differently for 0.3, 0.4?
    • What did you learn doing this release?
    • What still confuses you, or are you finding hard?

Weeks 9, 10, 11, 12

  • More on Code Review
    • How to create a good PR?
    • https://github.com/mozilla/thimble.mozilla.org/pull/1559 is a **great** example of a good PR.
    • This isn't a "beginner" problem, everyone struggles with it (cf. https://groups.google.com/forum/#!topic/mozilla.dev.platform/3ig8TZ-0rN8)
    • Tips:
      • Name your branches with issue numbers, or describe your fix (e.g., issue-123, fix-sidebar-styling)
      • If you are fixing an issue, mention the issue number in your PR subject or commit message: Fix #123: Fixing styling on sidebar to not overlap title). GitHub will automatically close issues that are mentioned like this when the PR is merged.
      • Don't just use the issue number. Make sure you also include text to describe your fix.
      • Commit messages don't have to be 1-line long! You can write a long description of what you did, changes that are coming as a result, advice for devs following your patch, etc.
      • If your code has some visible impact on the app, create screenshots or a screencast animated gif and include it in the PR.
      • Discuss what your change does, what it's fixing, and how you solved it.
      • Tell the reviewer how to test your change, what to pay special attention to when reviewing, and give any other guidance.