Difference between revisions of "DPS909 & OSD600 Winter 2017"

From CDOT Wiki
Jump to: navigation, search
 
(27 intermediate revisions by the same user not shown)
Line 60: Line 60:
  
 
* [[DPS909 & OSD600 Winter 2017 - Lab 3 | Lab 3]]
 
* [[DPS909 & OSD600 Winter 2017 - Lab 3 | Lab 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 <code>git commit</code> with branches
 +
** commit SHA: <code>e0ee2b5acd01acbe5b0bc1ee24b73e5d53a1fd70</code> or shortened to <code>e0ee2b5</code>
 +
** <code>HEAD</code>: the most recent commit (NOTE: you can also do <code>HEAD~2</code> to mean 2 commits older than <code>HEAD</code> or <code>HEAD~5</code> to mean 5 commits older than <code>HEAD</code>),
 +
** branch: an easy to remember name we give to the current commit, e.g., <code>master</code>
 +
** <code>master</code> branch vs. "Topic Branches": '''all work happens on a new branch'''
 +
* creating, switching between, updating
 +
** <code>git branch <branch name></code>: <code>-d</code> (maybe delete), <code>-D</code> (force delete), <code>-m</code> (rename), <code>-a</code> (list all)
 +
** <code>git checkout <branch name | commit SHA></code>, discussion of "detached HEAD"
 +
** <code>git checkout -b <branch name> [<base commit> | HEAD]</code>(create if doesn't exist, checkout new branch)
 +
** <code>git checkout -B <branch name> [<base commit> | HEAD]</code> (create or reset, checkout new branch)
 +
* local vs. remote, tracking branches
 +
** Branches are '''always local''' to your current repo
 +
** <code>git branch -a</code> will show all of your branches, and any/all '''remote branches''' (i.e., branches in remote repos your repo knows about via <code>git fetch</code>)
 +
** Example: <code>git checkout -b bug123 friend-repo/bug123</code> 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
 +
** <code>git checkout master</code> - switch to master branch
 +
** <code>git pull upstream master</code> - pull in any new commits from the upstream/master branch
 +
** <code>git checkout -b issue-1234</code> - create a topic branch for your work, named with bug #
 +
** <code>git add files</code> - edit files, add to staging area
 +
** <code>git commit -m "Fix #1234: ..."</code> - commit changes, referencing bug # in commit message
 +
** <code>git push origin issue-1234</code> - 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.
 +
** <code>git merge <branch name></code> merges <code><branch name></code> '''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 <code>git pull</code> does a <code>git fetch</code> and <code>git merge</code> 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 <code>master</code> to simplify the history
 +
** Because it rewrites history, you shouldn't do it on branches shared with other developers
 +
** <code>git rebase <new-base></code>
 +
** After a rebase, it's easy to do '''fast-forward''' merges
 +
** <code>git rebase -i</code> starts an interactive rebase, and lets you specify what to do with each commit.  <code>git rebase --abort</code> let's you stop it mid-way through.
 +
** If you need to squash the last few commits, you can use <code>git rebase -i HEAD~2</code> 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 <code>git status</code> to discover which files have conflicts
 +
** Examining, understanding, and working with conflict markers ">>>>" and "<<<<"
 +
** <code>git add</code> and <code>git commit</code>
 +
** Here's a [https://www.youtube.com/watch?v=4dJcsF6hgS4&index=5&list=PLDshL1Z581YYxLsjYwM25HkIYrymXb7H_ video demo] of resolving merge conflicts manually
 +
** Various visual tools exist for doing this, too:
 +
*** [http://meldmerge.org/ Meld]
 +
*** [http://naleid.com/blog/2013/10/29/how-to-use-p4merge-as-a-3-way-merge-tool-with-git-and-tower-dot-app p4merge]
 +
*** [https://developer.atlassian.com/blog/2015/12/tips-tools-to-solve-git-conflicts/ others discussed here]
 +
* gh-pages
 +
** Great for hosting static web content associated with a project
 +
** https://pages.github.com/
 +
** Once enabled for a project, you can use a special <code>gh-pages</code> branch
 +
** Pushing commits to this branch will cause web content to get hosted at http://username.github.io/repository
 +
** Here's an example: https://flukeout.github.io/thimble-gallery/index.html which is the '''gh-pages''' branch (default branch) here https://github.com/flukeout/thimble-gallery
 +
 +
* [[DPS909 & OSD600 Winter 2017 - Lab 4 | Lab 4]]
 +
 +
==Week 5==
 +
 +
* Strategies for Understanding Code
 +
** '''RTFM''' (Read the F.....antastic Manual!): <code>README.md</code>, <code>Contributing.md</code>, 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 <code>test/</code> 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 <code>experiments</code> 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:
 +
** <code>git grep</code>
 +
** <code>git blame</code>
 +
** Search within commit messages: <code>git log --grep "some string"</code>
 +
** Search within the commit content for addition/removal of a string: <code>git log -S "some string"</code>
 +
** Search all branches: <code>git log -S 'populate_database' --all</code>
 +
** Search in date range: <code>git log -p --since=2012-01-01 --until=2015-02-01</code>
 +
** Log Formatting examples
 +
*** <code>git log --graph --pretty=oneline --decorate</code>
 +
*** <code>git log --pretty=format:"%h %ad | %s%d [%an]" --graph --date=short</code>
 +
*** <code>git log --graph --pretty=format:'%Cred%h%Creset %an: %s - %Creset %C(yellow)%d%Creset %Cgreen(%cr)%Creset' --abbrev-commit --date=relative</code>
 +
** Searching on GitHub: Repositories, Code, Commits, Issues, Wikis
 +
*** Find all uses of <code>fadeIn()</code>https://github.com/search?utf8=%E2%9C%93&q=fadeIn%28%29&type=Repositories&ref=searchresults
 +
*** Within repo vs. all of GitHub (e.g., how a function is used, finding similar bugs based on error messages, who is using a piece of code, etc)
 +
*** Searching within repo only works in original repo vs. forks (e.g., https://github.com/adobe/brackets not https://github.com/mozilla/brackets)
 +
*** Commits, Code (and Languages), Issues
 +
 +
* Some examples of bugs we could try to solve using the above techniques:
 +
** https://github.com/mozilla/thimble.mozilla.org/issues/889
 +
** https://github.com/mozilla/thimble.mozilla.org/issues/1306
 +
** https://github.com/mozilla/thimble.mozilla.org/issues/1120
 +
** https://github.com/mozilla/thimble.mozilla.org/issues/958
 +
 +
* [[DPS909 & OSD600 Winter 2017 Release 0.1 | 0.1 Release (Due Fri Feb 10)]]
 +
 +
==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!
 +
 +
* [[DPS909 & OSD600 Winter 2017 - Lab 5 | Lab 5]]
 +
 +
==Week 7==
 +
 +
* Continuing with https://github.com/mozilla/thimble.mozilla.org/issues/1696
 +
** https://github.com/juliandescottes/piskel
 +
** https://github.com/juliandescottes/piskel-embed
 +
* Issues:
 +
** How to combine this into an extension?
 +
** How to trigger things to load when you open a file?
 +
** How to deal with save, open events with Bracket's filesystem?
 +
 +
* [[DPS909 & OSD600 Winter 2017 - Lab 6 | Lab 6]]
 +
 +
==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?
 +
 +
* GitHub Code Reviews
 +
** [https://help.github.com/articles/requesting-a-pull-request-review/ Asking for a review on a PR]
 +
** [https://help.github.com/articles/about-pull-request-reviews/ PR Reviews]
 +
 +
* Let's do some reviews
 +
** https://github.com/mozilla/thimble.mozilla.org/pulls
 +
** https://github.com/mozilla/brackets/pulls
 +
 +
* [[DPS909 & OSD600 Winter 2017 Release 0.2 | 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., <code>issue-123, fix-sidebar-styling</code>)
 +
*** If you are fixing an issue, mention the issue number in your PR subject or commit message: <code>Fix #123: Fixing styling on sidebar to not overlap title</code>).  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.
 +
 +
* Learning JavaScript In Depth
 +
** Look at code in Thimble (browser and node) and Brackets
 +
** Understand node.js programming
 +
** Complex ideas in JS:
 +
*** Object Literals and JSON
 +
*** Constructor Functions and <code>new</code>
 +
*** Prototypical Inheritance
 +
*** The many meanings of <code>this</code>
 +
*** [http://bonsaiden.github.io/JavaScript-Garden/#function Anonymous Functions (lambdas)]
 +
*** [http://underscorejs.org/docs/underscore.html Self-executing anonymous functions]
 +
*** [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array Functional programming with Arrays], [https://github.com/adobe/brackets/blob/6affa7907fdc820f7b9083bc0ff7c9fb87fb3e57/src/language/HTMLInstrumentation.js#L93-L123 example]
 +
*** [https://github.com/adobe/brackets/blob/ae17456a596965a1247b79ddb82c6e1518bc6e5e/src/utils/UrlParams.js Constructor functions and the prototype], [https://github.com/mozillafordevelopment/webmaker-app/blob/bfa6377bf49d14c16868dd3a4ae7b8f9fbcfcaea/lib/model.js another example]
 +
*** [https://github.com/adobe/brackets/blob/791bcc436155cbd8e8e73429af4ca3fde0881703/src/utils/Compatibility.js Extending native prototypes]
 +
*** [https://github.com/filerjs/filer/blob/develop/src/errors.js Dynamic property access]
 +
 +
* [[DPS909 & OSD600 Winter 2017 - Lab 7 | Lab 7]]
 +
* [[DPS909 & OSD600 Winter 2017 - Lab 8 | Lab 8]]
 +
* [[DPS909 & OSD600 Winter 2017 - Lab 9 | Lab 9]]
 +
 +
 +
* [[DPS909 & OSD600 Winter 2017 Release 0.3 | 0.3 Release]]
 +
* [[DPS909 & OSD600 Winter 2017 Release 0.4 | 0.4 Release]]
  
  

Latest revision as of 11:27, 30 March 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.



Retrieved from "https://wiki.cdot.senecapolytechnic.ca/w/index.php?title=DPS909_%26_OSD600_Winter_2017&oldid=124909"