Difference between revisions of "Open Source Comes to Campus/Resources"

From OpenHatch wiki
Jump to navigation Jump to search
imported>Shauna
Line 95: Line 95:
 
==Github Demo==
 
==Github Demo==
   
  +
The purpose of this demo is to get students more experience, hands-on, in a social environment, submitting pull requests to a project on Github. The content of the pull requests is not the point; instead, the idea is to focus on the social/personal concept that this is how projects often want changes submitted, and the technical side of getting practice with the tools. Students have already been through a basic tutorial on git; the idea is to cement this knowledge.
--Paul--
 
  +
  +
Typically, this takes the following form.
  +
  +
Before the session, an instructor creates a sample repository where it is safe to merge pull requests from students. This could be a personal project of theirs, a fork of someone else's project through which they create a sandbox to accept students' work where it is okay to eventually erase those changes, or an automatically-cleared repository (such as one automirrored from elsewhere, where remote changes clobber changes made in Github).
  +
  +
The instructor begins by explaining the project in question, and showing how to find the project's Github page.
  +
  +
They then use the Github website to point to a particular file that can accept simple, text-based edits, typically a file like README. They then navigate to a terminal and demonstrate how to create a pull request by demonstrating all the following steps:
  +
  +
* They "forking" the project into their personal Github account. (In most cases, instructors are demonstrating a personal project; in this case, it would be wise for the instructor to create a dummy Github account to be the person submitting the pull request. This also avoids some trouble where Github accounts that are part of "organizations" see a slightly different fork UI than accounts that aren't.)
  +
** They explain the key concept about forking: This copies all the history of the project into a space they are permitted to modify.
  +
* They "clone" the repository onto their own computers.
  +
* They make a change on their own computer, and run 'git add' on the change. Then they use 'git commit -m' to commit the change. The change is usually as simple as adding their name to a README file.
  +
* Then they 'git push' the change, which updates their master branch on Github. They should stop to explain this.
  +
* Then they visit their fork on the Github website and notice that their fork has their personal work on it.
  +
* Then they click around in the Github UI to submit a pull request.
  +
* Then they visit the upstream project, and show what the pull request looks like. They typically do not click "Merge" because it might create conflicts for student submissions.
  +
* Then they tell students to submit changes, encouraging them to raise their hand if they need any help.
  +
* The instructor sticks around at the front of the room, showing the upstream project's "List of pull requests" page, which typically automatically refreshes as students' work rolls in. Typically, seeing the student submissions makes for a lot of fun in the classroom. We often have to ask, "Hey, who is susanna112" (for example) and see a student raise their hand.
  +
  +
NOTE: We would do well to have a cheat sheet for students for the commands they use. Typically, students are supposed to follow along with the instructor by typing in analogous commands, with TAs roaming to help students as they run into issues. (For example, one student once ran into an issue where the Git version we recommend on Mac OS X would segfault in libcurl if using the HTTPS access method. Switching to SSH-based worked around the issue, but then she was behind.) We haved typically worked around this by having someone type the corresponding commands into IRC.
  +
  +
Also NOTE: It is important that the instructor suggest students use the HTTP(S) access method for Github; otherwise, students who do not have SSH keys set up will spend time on that, which is beside the point.
  +
  +
Some students may have trouble following along, and it is essential that TAs work to identify students who are not progressing well by walking around and looking at laptop screens to find students who seem stuck.
   
 
==Ethics and History of Free Software==
 
==Ethics and History of Free Software==

Revision as of 02:33, 4 June 2013

What to expect as a staffer

Laptop Setup

See laptop setup page.

Open Source Communication Tools

The slides I use for this talk can be found here. These are modified from a version graciously provided by Jessica McKellar. There are substantial notes in the ODP file which can be viewed by going to the "Notes" tab.

Version Control Demo

Go to the Wikipedia page for the host institution, e.g. http://en.wikipedia.org/wiki/Wellesley_College and http://en.wikipedia.org/w/index.php?title=Wellesley_College&action=history. The presenter of this talk will explore the page more thoroughly later.

I also suggest, while you are out of the ODP presentation, showing the German law Git repository as an example of version control for things other than code.

Diff and Patch Demo

This demo uses the files in this repository.

I have a To Do List! But maybe it needs editing. First, I'll make a copy to edit:

cp ToDoList new_ToDoList

Then I'll open it up and make changes to it. (Side note: make sure to explain which editor you're using and give options for those following along - emacs, vim, nano, or a GUI.)

How do I view the differences between the two?

diff -u ToDoList new_ToDoList

That's just printed to the command line, though. How do I store it in a file?

diff -u ToDoList new_ToDoList > changes.diff

I open up the file and see it contains the same stuff as was printed out before. Okay, now how do I apply these changes to the original list?

patch -p0 ToDoList < changes.diff

Note that the argument given to the patch is the file I want to modify, not the file that already has the changes.

People often ask - what does the argument "-u" given to diff mean, or the argument -p0 given to "patch"?

Well, -u tells diff to output in unified diff format. Two other formats are Edit script (specified with -e) and Context format (specified with -c).

-p[x] is an argument which allows the user to specify how much of the given file's path needs to be matched. -p0 gives the entire file name unmodified. The documentation has a bit more info.

Issue Tracker Demo

Pick a few random issue trackers, ideally ones which use different platforms, such as:

Information to look for:

  • status
  • priority
  • owner/assigned
  • component/product
  • summary/descriptor
  • tags like "bite size"

IRC Demo

Log into IRC and join the #openhatch channel.

Forgot to install? Go here.

Show:

  • how your name is highlighted if someone uses it
  • how to do /me
  • how to send messages to individual users
  • different servers vs different channels (#openhatch on other servers might be empty)
  • how to make a new channel, if asked

Introduction to the Command Line

--link to website?--

Introduction to Version Control

--Marina--

Github Demo

The purpose of this demo is to get students more experience, hands-on, in a social environment, submitting pull requests to a project on Github. The content of the pull requests is not the point; instead, the idea is to focus on the social/personal concept that this is how projects often want changes submitted, and the technical side of getting practice with the tools. Students have already been through a basic tutorial on git; the idea is to cement this knowledge.

Typically, this takes the following form.

Before the session, an instructor creates a sample repository where it is safe to merge pull requests from students. This could be a personal project of theirs, a fork of someone else's project through which they create a sandbox to accept students' work where it is okay to eventually erase those changes, or an automatically-cleared repository (such as one automirrored from elsewhere, where remote changes clobber changes made in Github).

The instructor begins by explaining the project in question, and showing how to find the project's Github page.

They then use the Github website to point to a particular file that can accept simple, text-based edits, typically a file like README. They then navigate to a terminal and demonstrate how to create a pull request by demonstrating all the following steps:

  • They "forking" the project into their personal Github account. (In most cases, instructors are demonstrating a personal project; in this case, it would be wise for the instructor to create a dummy Github account to be the person submitting the pull request. This also avoids some trouble where Github accounts that are part of "organizations" see a slightly different fork UI than accounts that aren't.)
    • They explain the key concept about forking: This copies all the history of the project into a space they are permitted to modify.
  • They "clone" the repository onto their own computers.
  • They make a change on their own computer, and run 'git add' on the change. Then they use 'git commit -m' to commit the change. The change is usually as simple as adding their name to a README file.
  • Then they 'git push' the change, which updates their master branch on Github. They should stop to explain this.
  • Then they visit their fork on the Github website and notice that their fork has their personal work on it.
  • Then they click around in the Github UI to submit a pull request.
  • Then they visit the upstream project, and show what the pull request looks like. They typically do not click "Merge" because it might create conflicts for student submissions.
  • Then they tell students to submit changes, encouraging them to raise their hand if they need any help.
  • The instructor sticks around at the front of the room, showing the upstream project's "List of pull requests" page, which typically automatically refreshes as students' work rolls in. Typically, seeing the student submissions makes for a lot of fun in the classroom. We often have to ask, "Hey, who is susanna112" (for example) and see a student raise their hand.

NOTE: We would do well to have a cheat sheet for students for the commands they use. Typically, students are supposed to follow along with the instructor by typing in analogous commands, with TAs roaming to help students as they run into issues. (For example, one student once ran into an issue where the Git version we recommend on Mac OS X would segfault in libcurl if using the HTTPS access method. Switching to SSH-based worked around the issue, but then she was behind.) We haved typically worked around this by having someone type the corresponding commands into IRC.

Also NOTE: It is important that the instructor suggest students use the HTTP(S) access method for Github; otherwise, students who do not have SSH keys set up will spend time on that, which is beside the point.

Some students may have trouble following along, and it is essential that TAs work to identify students who are not progressing well by walking around and looking at laptop screens to find students who seem stuck.

Ethics and History of Free Software

Typically this takes 20-30 minutes and takes place right before the Career panel.

The inspiration for the career panel comes partly from a past event, namely the first one (at Penn). After the main lecturer (Asheesh) gave a history tour in the lecture, students did Q&A with him and one other staffer. The main lecturer and the other staffer had similar but different opinions, which helped.

To deliver an equivalent lecture to what was given at at UMD or Wellesley College, follow the link to the full Ethics history talk.

Staying Involved

  • Join our general mailing list.
  • Join the alumni mailing list.
  • Hang out with us on IRC.
  • Training missions?
  • Bug list?
  • Meetups?
  • Programs like GSoC and GNOME outreach.