Open Source Comes to Campus/Resources

From OpenHatch wiki
< Open Source Comes to Campus
Revision as of 16:51, 18 June 2013 by imported>Paulproteus (→‎Version Control Demo)

Command line basics

(This is based on what the command line tutorial in the Boston Python Workshop.)

Many of the tools of open source development are primarily used via the command line. Let's get some practice with navigating the computer from the command line.

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

Start by saying:

  • In open source software, people use version control to keep track of files as they change. To give you a sense of what this is for, how many of you have worked on group programming projects? (A few hands raise up.) One common way to do that is to email around copies of a file you're working on. When every person working on a project uses version control, they have their own copy of the project and they can make whatever changes they want, and they can synchronize with the main version....
  • To talk about version control, I want to show you how version control works for purely text documents. So let's look at the Wikipedia page for Wellesley College.
  • (Navigate web browser to http://en.wikipedia.org/wiki/Wellesley_College )
  • So one of the great things about Wikipedia is that the system keeps every track of every version of every article. The wiki system is a version control system, too. If you click on the "Edit" tab, you can see the built in way to edit every article. Let's take a look at the history tab here. (click history tab)
  • (find yourself at http://en.wikipedia.org/w/index.php?title=Wellesley_College&action=history ; zoom in so it's large enough for people to see; make it really enormous)
  • So here, you can see a little heading for every version of the page, including (mouse over the date) the time and date of that version, who made the ...

most recent version

with a web interface tracking versions of a document.


used in open source that helps track versions of files

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 (as needed)

Need to extract relevant tutorial bits from: https://openhatch.org/wiki/Boston_Python_Workshop_7/Friday

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

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 "fork" 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 can be as simple as adding their name to a README file. It can also be silly.
  • Then they 'git push' the change, which updates their master branch on Github.
  • 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.

Roadmap

Release goal: Ready for teachers, Wed June 19

In time for http://opensourcebridge.org/sessions/1066 , in order of highest priority to lowest priority:

  • Shauna: Write a section on event logistics
  • Asheesh: Take intro to command line tutorial from BPW and make it part of this page
  • Asheesh: Write up intro to version control tutorial, based on the current outline of using Wikipedia as a demo, but with more writing clearly about what to say and how to introduce the git version control demo
  • Asheesh, probably: Prepare a solid plan for a nice looking version of this page (aka a "frame" to help people navigate the materials)
  • Maybe not doable by Jun 19, but nice: (Asheesh or Shauna) Improve the Github demo by adding screenshots and stating more clearly what to say out loud
  • Maybe not doable by Jun 19, but nice: Revisit the intro to FLOSS
Retrieved from "https://wiki.openhatch.org/wiki/Open_Source_Comes_to_Campus/Resources?oldid=12061"