Notes for DCI 190: Shenandoah, a studio course on online literary magazine design.
GitHub, based on the open source tool git, most often functions as a version control system. (There are several other similar tools based on git, such as GitLab and Bitbucket.) I tend to prefer GitHub, though the others are also very good systems and you may very well encounter those in whatever workplace you enter. Version control will be discussed later in the course. Initially, we’re going to focus on using GitHub as a collaboration tool, as a way of facilitating communication among the class, as a project management tool, and as a mechanism for tracking things to do in the publishing on a literary magazine.
If you do not yet have a GitHub account, then signup for one. You can get a free account at github.com.
Don’t freak out by the Built for developers. You don’t have to be a developer to make really good use of GitHub.
In several ways, GitHub is a type of social network. I don’t really use it in that manner, but some people do. And your GitHub profile is public and serves as a good way of showcasing your technical work. Indeed, I’m a bit impressed when I see people place their GitHub address on their CV. You can see mine. Impressed? Uh, well, no? That’s okay. Let’s move on.
Once you have a GitHub account, send me your GitHub username. (Some of you have done that already.) So, what am I going to do with your username? This is where things start to get interesting.
The concept of a repository is central to understanding how GitHub works. Think of GitHub as being organized into repositories of code. Some of you may even be wondering, what really is code? In the simplest sense, code is just a set of files. Code could just be one file but it’s usually many files organized in a single top-level directory and, often, with subdirectories. It’s that top-level directory and all its files and subdirectories that make up a git repository.
Yet, in GitHub a repository also can have no code associated with it. Whoa. It’s not a very common case, but for the purposes of this class we’re going to use a repository on GitHub that has no code. So, for now, just don’t worry about any code. Instead, let’s focus on the other tools that come with a GitHub repository, namely Issues and Projects.
In this class, we will be working with the Shenandoah repository on GitHub, which you can find at https://github.com/wludh/Shenandoah. This is a private repository. So, you’re not going to have access until I add your GitHub username to this repository.
There are three things I want to point out about the Shenandoah repository page: wludh, Issues, Projects.
All GitHub repository pages have a similar structure with a number of tabs along the top. But let’s first talk about that wludh up above those tabs. As students at W&L, you probably have guessed that wlu refers to Washington and Lee University. You might or might not have guessed that the dh refers to digital humanities. So, wludh is simply the organizational home on GitHub for DH projects at W&L. And the Shenandoah project is grouped under that organizational account. Enough about DH for now, but if you’re excited about that then you can browse our dedicated digital humanities at W&L site.
Issues
The way in which GitHub handles issues is one of my favorite features of this tool. What are issues? Ah, don’t get confused because this class is about publishing a literary magazine. In the context of GitHub, an issue is not an issue of the magazine. An issue is an idea, or a thought, or feedback, or a task to do. In the GitHub help, issues are explained under Managing your work on GitHub. That’s a really good section to read thoroughly.
Issues allow for threaded discussions so that you can follow the flow of a conversation. You also can add labels, tags, and milestones to issues. These attributes aid in organizing issues.
We’re going to use the GitHub issue tracking extensively in this course. Actually, issues will be one of the primary ways in which we communicate in this course.
Spend time getting familiar with the variety of ways in which issues can be used in GitHub. Many other tools have similar capabilities. Issue tracking is an essential component of project management. A well-structured set of issues enhances productivity for everyone. But it takes an organized mindset to use labels (i.e., categories) and tags in an effective way. Tools can only aid you so much.
Knowing how to conceptualize a structured approach to issue tracking via the logical use of labels is a skill that makes you a valuable part of any team.
I’ll be talking more in-depth about issues, but it all becomes clearer as you actually start using the issue tracking within GitHub. I’ve created some issues that will help you get started. There are three that I want to call to your attention.
- Q&A. This is a general issue where you can post questions throughout the term related to any aspect of the course, whether assignments or technical questions. I’ll also post my answers to those questions in this thread.
- Suggestions for enhancements/fixes. This week you should be looking through the online issues of Shenandoah and identifying enhancements and fixes for the site. We’re going to talk about those in class on Friday morning.
- Weekly reflection. A separate issue exists for each week of the course. (The dates are the Fridays on which the class meets.) Prior to class, post an individual reflection of what you learned this week. You’ll be doing these reflections for every week of the course. Essentially, this is a way to get you to think about your own thinking. It’s a good habit to get into for anything that you do. As for grading: the only way to get this wrong is not to do it. Your reflections will likely improve week-by-week.
I’ll talk about the Projects part of GitHub in another posting. Projects are directly connected to Issues. For now, focus on getting comfortable with issues.
To do:
- Signup for a free GitHub account
- Send me your GitHub username
- Look through Shenandoah and make suggestions in the issue tracker for enhancements and fixes.
- Write a weekly reflection in the issue tracker for this week.
- Let me know if you encounter any difficulties.