README.org

This is an assignment for Digital History, a digital humanities course taught in the History Department at the University of Toronto. If you’re a teacher, feel free to fork and repurpose for your own courses. If you’re a student, keep reading!

Git and Github Assignment: Goal

In this assignment, you will:

• create a small file with some information about yourself
• add (“commit”) that file and a separate image file to a git repository
• optionally (if you are considering attempting an “A” in the class) write short responses to some questions in a text file and commit that file as well
• send (“push”) your changes to the github code-sharing website

The information you send will generate a “trading card” about you that will be saved to a publicly-visible website. Take this opportunity to think about the ethics of data collection, and implications for historical work that operates in communities like this one.

This is also your opportunity to set up a development environment on your laptop. While we have done our level best to simplify the process, this can still be a somewhat daunting task, so do not leave your setup to the last minute. Expect the unexpected!

Quickstart

There are more details below, but for the impatient: to work on this assignment, you will need to do the following

• install the VSCode texteditor and preferably add the recommended course extensions
• install node, if you can. Without node, you can’t run the tests, so you won’t know if you’ve done the assignment properly.
• sign up for the Slack team and install the Slack client on your computer and/or phone, so you can ask and answer questions

Expectations

This assignment is graded pass/fail. You will only get credit if your repository passes all relevant tests. To pass the assignment, you must:

• set up your work environment (see previous section!)
• Accept the assignment invitation that was circulated on Quercus (you may already have done this!). This will create a repository for you, which you must then clone locally on your laptop
• enable automated testing by installing all npm packages
• add to the repository a text file containing structured information about you
• add to the repository a profile picture of yourself
• commit both these changes
• students attempting an A only: answer reflection questions

Details

Setup

Setting up your work environment could take some time. It’s best to do this well in advance of the assignment deadline.

• install git
• download the Visual Studio Code (VSCode) editor and install the course extensions package as described on the Setup page and preferably add the recommended course extensions
• configure git with your git and github information as described here and here
• allow Github to create a copy of this repository for you by following the link on Quercus/the website. Clone locally via the “Clone or Download” method described here, and do your work within VSCode (you can also clone directly from VSCode, which may feel easier; see these instructions.
• download and install node.js and npm as described in the course setup instructions
  • install the node dependencies for your project with npm install as described on this page. On windows you may run into some issues. See the Node website before coming to me for help, but I will assist where I can.
  • run tests by executing npm test in your working directory
  • you should now see a new directory TestResults, inside of which you will find a file testresults.html. Open this file in a modern browser (Chrome or Firefox) to see your test results (most of the tests should fail at this point, so don’t worry!).

Add files and commit changes

Add a picture of yourself to the repository

• the picture should be named yourgithubid.jpg (substitute your real !) and should be placed in the images directory
• commit this new file to the repository. You can use the command line, the git tools inside VSCode, or the GitKraken interface, as you prefer.

Create and update your JSON file

In the directory students, you should see a file named “template.json”. Copy the contents of this file to a new file, which should be named yourgithubid.json (substitute your actual Github user id for “yourgithubid”!). This file is written in the JSON (“JavaScript Object Notation”) framework, which we will learn more about later in the course. Your file will contain exactly one “JSON object”, delimited by the { and } at the beginning and end of the file. Each line of the file is called a “property” and takes the form of a “key/value pair:”

"key": "value",

Think of the “key” as the name of this small element, and the value as its content. You should not change the keys, but you must change almost all of the values.

This file needs to meet the stringent criteria of the JSON specification, so be very careful editing it:

• the resultant file must be valid JSON, which means that key names must be enclosed in double quotes, and values must either be enclosed in double quotes as well, or use the special Javascript values “true” or “false” in the case of the privateXXX properties. Please do not enclose true and false in quotes, or they will not work as expected. Avoid using " and ' except as enclosing markers around your keys and values, as they can easily lead to syntax errors.
• the fields “firstName”, “lastName”, “email”, “github”, and “photo” must all be filled out (no exceptions).
• firstName and lastName should be the same as the names I will find in my official class roster from U of T
• use the nickName field if either of these is true for you:
  • you prefer to be called by a name that is not the name I’ll find in my roster
  • you do not wish to share your full name publicly on the class roster website.
• the “privateXXX” fields control what information will be displayed on the public website. Any such field set to “true” will mark some information as private, as follows:
  • privatePicture will hide your picture on the website (default: false)
  • privateEmail will hide your email (default: true)
  • privateGithub will hide your github id (default: true)
  • if you set privateName to true, your first and last name will be hidden. Your nickName will still be displayed, so be sure to use a nickName value that you are willing to make public.

  This is a low-traffic website which will only be available during this semester, but if you do not want to share information with your classmates, or have serious concerns about information becoming public, you should be sure to fill these fields out

• the superPowers field is not mandatory, but it will help me to remember who you are, so… please do fill it out! Use it to tell the class something interesting and/or memorable about yourself. Note that this field cannot be made private.

When you are done, commit your changes as above.

Answer Reflection Questions (“A” Bundle only)

This section is only required for students who are attempting to achieve an “A” grade. If that is not your goal, you do not need to worry about this part, or about tailing tests from this section.

In the folder “Reflection”, you will find a file named reflection-template.md. Copy the file contents to a new file named yourgithubid.md (again, use your real Github id instead of githubid!). This file contains two subheadings, each of which is a question. Answer each of these questions in a response of approximately 150 words. Your responses should be thoughtful and perceptive, and written at a level that would normally result in a grade of B or higher.

Run tests

At any point in the process, you can re-run your tests by executing npm test from a terminal in the working directory. Visit the file TestResults/results.html in a browser to see your updated results. To have the tests run continuously whenever you modify a file, run npm run watch instead (you will still have to refresh the web page to see the new results!).

You can do all of this within VSCode itself, either by running npm: run tests from the Command Palette or by running tests directly in the Mocha Sidebar.

Building the Website

You may want to see what your profile will look like on the website when it goes live. You can get a preview this with the following command:

npm run collectjson

(again you can do this directly from the terminal, or within VSCode with npm: run scripts from the Command Palette)

Now open the file index.html in your browser. You should see your card along with the dummy cards already provided.

Handing in

As mentioned above: when you are finished – when your code passes all the tests – submit your code by pushing your changes to origin in VSCode (or with git push origin master in the terminal). At that point, the “continuous integration server” will re-run the tests and confirm that your code is valid; if the tests pass, a script will trigger and upload your work to the website.

‘

For the curious: How this works

This is a very simple example of using structured data to create a visual interface that, as it were, represents that data to the visitor. In this case, the “representation” takes the form of a playing card.

Each of you creates a small json file with uniform structure. Because the structure is predictable, I can build other structures on top of the data you provide. In this case, I use some primitive techniques for harvesting that data; and then I have some further code (also very simple) for looping across the data structure, creating an HTML structure for each person in the class. That HTML is then “injected” into the web page, where you can see the cards.

For privacy reasons, you don’t have access to each other’s information. However, if you want to, you can still see how this process works.

index.html: The main web page

You haven’t learned about HTML yet, but the structure of this page is quite simple:

• the <header> element contains some metadata and some very simple styling instructions in the form of CSS directives
• the <body> is also simple, and has two main parts:
  • a <nav> element for the blue headline
  • a <div> element with an id attribute of cardcontainer to hold the cards

If you look closely at the code, you’ll see that the card container div is empty! So where do the cards actually come from? That’s where the <script> tags comes in. First, we load the list of all student information (see below) by executing the trivial script in utils/allstudents.js. Then, in the final script tag I “loop over” that list – for each student, this script creates a bunch of HTMl and adds it to the cardcontainer div.

utils/collectjson.js: Gather student data

This script reads all the json files and uses them to write a new file, allstudents.js. It might be a little hard to follow, but I’ve added extensive comments which might help you a little bit.

utils/allstudents.js: student data storage

This is where the full list of students is stored.

Testing this out yourself

To run this yourself, you will need to install node.js and NPM. Follow those instructions, then run npm run collectjson from a terminal(or VSCode; see above fore details) having first navigated to the root directory of the repository. When you reload index.html you should see a set of cards that also includes your own information.