Work with a partner on this assignment. (Groups of three are also OK.) Do all the installations and account signups individually on your own computers, but share a single git repository for your project. Put both/all of your names in the comments at the top of each source file.
To learn about:
Here's the quick summary of your tasks. Much more detailed instructions are in the numbered sections below.
The rest of this document contains lots and lots of details. Go slowly, write down your questions as you go, and pay attention to error messages and other information that appears on your screens. Also, talk to your partner about each step: Did you get what happened there? Should we try something different? Should we reread the instructions? What does that sentence mean? Maybe we should bug Jeff or post on Slack about this one...
If you get stuck or just want a little elaboration on a concept, don't hesitate to ask for help, in person or on Slack.
For the rest of this document, and sometimes in other exercises, I will refer to the partner whose repo you're using for this project as Alice, and each other partner as Bob. This makes writing instructions a lot easier than refering to "the partner whose repo you're using for this project" and "the partner whose repo you're not using for this project". Alice and Bob have been used in computer-related exposition for a long time because they're handy to have around.
Have fun!
You can create an account at https://github.com. Once you have a GitHub account, post your github user name on the appropriate thread on our class Slack channel.
I'll send you a link once you have let me know your github user name. Follow that link to accept your git repository for doing homework this term.
A repository is essentially a folder in which you can store whatever files and subfolders you want. What makes a repository more than a folder, however, is that the version control system (git, in this case) keeps track of all the changes that get made to the files in the repository. This saving of history makes it possible for you to retrieve old work, track down the time when a bug was introduced (and who introduced it), collaborate on a project with a team of programmers, easily back up your work, etc. Version control systems are a bit of a hassle to learn for the first time, but they're indispensable programming tools and unquestionably worth the effort.
You can get git here. It's possible that you already have git on your computer (e.g. it's available by default on most Macs).
Once you install git, you'll be able to use it from the command line. For many people, that's sufficient. However, there are some benefits to using a GUI git client, too. Since we'll be using GitHub to host our git repositories, you might find GitHub Desktop a good choice.
For the rest of this document, whenever there's need to show a git operation, I will show you the git command-line version of that operation. If you're using GitHub Desktop or any other git client, you'll need to figure out the equivalent operations in your client.
Install Microsoft's Linux Subsystem for Windows to get access to a wide range of Unix/POSIX/GNU tools. These are the tools that you'll see me using all the time in a Mac terminal, because macOS is based on a Unix core. Similarly, Linux is a variant of Unix, and thus has all the usual Unix tools. Windows has its own command-line interface (PowerShell) that's plenty powerful, so you can definitely work to become an expert on that interface and not worry about having Unix on Windows. That said, the documentation and open source software available for Unix-like systems is a huge benefit to day-to-day programmers, and I personally never work long with a Windows machine without first making sure I have a Unix command line to work with. Since I won't be demonstrating Windows-specific tools at all this term, you might find it handy to have the tools that I do demonstrate.
That link you got on the "You are ready to go!" page in Step 2 above? You need it now. Right now, your repository is stored only on the GitHub server. To add files to it, you'll need to clone a copy of the repository onto your working computer. You will then add files to your local copy of the repository and push your changes back up to GitHub.
You'll do your cloning via the following operation (or its GUI equivalent):
where the "..." is the remainder of the link you got from the "You are ready to go!" page. You should now have a folder called "assignments-yourgithubname", which contains only a subfolder called ".git". You can move this folder wherever it's convenient for you. (Curious about the contents of the .git folder? Go ahead and poke around to see what's there. It gets more interesting, of course, after you add some files.)
IMPORTANT FOR WINDOWS USERS: When you do this, you will need to be careful about where you put your files. If you put your repository inside the Linux file tree (by, say, doing "cd" at the bash prompt to get to your Linux home directory and then doing "git clone ..." to put your git repository there), you'll run into file permissions trouble when you create IntelliJ projects during the second half of this term. There's a simple solution. You can use bash to access files in the normal Windows file system (say, on your C drive) by doing this:
If you want me to connect you to somebody, personal-message me on Slack right away.
It doesn't matter which partner's repository is the one you use for this assignment, but you need to pick one. Then, the owner of the chosen repository (Alice, that is) will need to add Bob(s) as collaborator(s) on Alice's repository. Try to figure this out on github.com. Ask questions if you run into problems.
Once all partners are collaborators on the chosen repo, everyone should "git clone" it to their working machines.
Bob, at the command line on your computer, cd to your clone of Alice's repository, and do
Does the hello.py file appear in your copy of the repo? It should. If it doesn't, try to figure out what went wrong, then ask for help if you're still stuck.
Bob: Change something in hello.py. Then do the git status/add/status/commit/push sequence from section 7 above to get your changes included in the master copy on github.com.
Alice: do a "git pull" and see if you ended up with Bob's version of the code.
While we work on a project, it's common for the project directory to accumulate files that aren't really part of the project. For example, if you write program.py and module.py and program.py includes an "import module" statement, you may discover a module.pyc in your working directory. This isn't source code, and it doesn't matter if you deleted (it'll just get recreated next time you import module). So you don't want that litter included in your repository.
There are lots of other examples of files that shouldn't be saved in a repo. Like the .DS_Store files the macOS Finder generates whenever you look at a folder in a window or the .class files you get when you compile a .java file. Accidentally adding these files to your repository is all too easy. And since these files typically change every time you run the Python program or recompile the Java program or look at the folder in a window, all those changes get added to the repository every time you commit, which makes every clone of your repo take up a lot of unnecessary disk space. It's a mess, and we hate messes.
To prevent you from accidentally adding these extraneous files to your repository, you can tell git to ignore them completely via a .gitignore file. Like so:
IMPORTANT ODDITY: by default, macOS, Windows, and Unix command shells (including bash) don't display files whose names start with a period. So if you open your repo's top-level folder in a macOS Finder window, you probably won't see your .gitignore file. Similarly, a simple:
command at a Unix command line won't show you .gitignore. But this command does:
(the "-a" stands for "all").
All done.