Version Control and Static Site Bootstrap
Overview
We'll kick off day 2 with a review of Assignment 1 (Elements of a News App), and then begin ramping up on the technical side with version control. If time allows, we'll also wade into the AWS cloud platform and begin setting up our project websites.
Elements of a News App
Let's review thoughts on features of ICIJ Implant Files database and The Force Report.
- What features are common?
- What features are in one but not the other?
- What user behaviors are these apps trying to enable?
- What would you add/change to improve the app or its trustworthiness from a user perspective?
Version control overview
"What is 'version control', and why should you care? Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later. For the examples in this book, you will use software source code as the files being version controlled, though in reality you can do this with nearly any type of file on a computer." ~ Pro Git
Using version control along with a code-sharing platform such as Github has numerous benefits for software and journalism. Among other things, it:
- Increases transparency (share your code with the world!)
- Invites contributions/feedback (pull requests, bug reports)
- Facilitates collaboration (branches and forks; code reviews and commenting)
- Enables automation (CI/CD, automated testing)
- Helps avoid disaster and reduces fear of change
Git/Github support sophisticated collaboration models, in particular the use of a primary repo with branches and the fork-and-pull strategy. These are not mutually exclusive, of course. We'll mostly use the fork-and-pull model for group work, but keep branches in mind as a valuable tool for experimentation.
Basic git workflow with Github Desktop
Pre-flight check
- Configure email on Github and in desktop client
- Configure default editor for desktop client
Basic git workflow
In the Github Desktop client:
- Click
File -> New Repository
- Create a repo called
Comm177T-2019
. This will create a repository that exists only on your machine. The client will give you the option to publish the repository to Github, but hold off on that for now.
Go to the command line and create a test file in the new repository:
cd /path/to/Comm177T-2019
echo "hello world" > testfile.txt
Now switch back to the Github client. You should notice a few things:
- The
Changes
tab lists the file name. - The right panel shows the one line of text ("hello world") highlighted in green, which indicates an addition.
This new file has not yet been "committed" to the repository. Think of it as an unsaved draft of work. If you were
to delete or change the file at this point, the original version could not be recovered.
Let's save the new file by going to the lower left panel of the client and clicking Commit to master
. This version of the file is now saved as part of your repository history. The client should now show 0 changes. If you toggle over to the History
tab, you should see an entry for Create testfile.txt
.
Let's add another line to our file. You can do this on the command line, as below, or by simply opening/editing the file in a text editor.
echo "Coding is somewhat fun." >> testfile.txt
This change should now appear in the Changes
of the Github client, with the newly added line highlighted in green. Note that the original line is not highlighted. Git is smart enough to figure out both what has and has not changed in the file.
Go ahead and commit this change as well.
Now let's try modifying the file to see what happens. On the second line, change "somewhat" to "jolly good" (this is, after all, closer to the truth).
Once again, checkout the Github client. This time, the client displays the original line in red and the new line in green. It also highlights the precise nature of the change: "somewhat") is shaded in a slightly darker red, and "jolly good" in darker green.
Let's commit this change as well, this time using a custom commit message: "Bumping up the excitement level".
At this point, you have a series of changes, all of which can individually be viewed (and even recovered), as seen in the History
tab of the client.
Now let's try publishing the repository to Github:
- Click the
Publish repository
button - In the modal window, leave the defaults and click
Publish Repository
Congratulations, you've now saved your work to a private Github repository! There are many more features to git and Github, but these basic steps are all we need for the moment.
AWS and the cloud
AWS is a cloud services provider with a mind-boggling array of offerings. Some of the best-known services include:
- Databases (RDS)
- Virtual machines (EC2)
- "Serverless" functions (Lambda)
- Static file storage (S3)
- Domain registration and networking (Route 53)
- Content delivery (CloudFront)
- Machine learning services
- ...and much, much more
AWS isn't the only game in town, but it's widely used and well documented. The S3 service also has a handy feature that makes it frighteningly easy to set up a static website.
The downside is that these services cost money, and the bills can add up if you're not mindful of usage. The good news is that the types of services we plan to use this quarter should cost pennies to a few dollars per month.
Bootstrapping our static website
Pre-flight check
Sign up for an AWS account.
Bootstrap your static site
Follow the steps in Create a Static Website to get the basics going.
If you finish that, get started on the Adding a Custom Domain and HTTPS part of Assignment 2 (see below).
Assignment 2
- Complete the Create a Static Website tutorial
- Complete Adding a Custom Domain and HTTPS tutorial
- Mac users:
- Install xcode from the command line:
xcode-select --install
- Install Homebrew
- Install xcode from the command line:
Upload a link via Canvas to your custom, HTTPS-enabled domain.
Recommended
If you're new to web development or need to refresh your knowledge of the picture: