→ Digital humanities

Maintained by: David J. Birnbaum (djbpitt@gmail.com) [Creative Commons BY-NC-SA 3.0 Unported License] Last modified: 2022-01-19T01:59:02+0000

GitHub for project management

Creating a repository

You’re the project owner now, so it’s your job to make sure you set your team up with a great collaborative foundation. This means making your project team’s GitHub repo clear, organized, and accessible. To do that:

  1. Go to https://github.com, where you already have your account, and click the green New repository button on the right side of the left sidebar. Follow the directions, and be sure to initialize your repo with a README.md file. Include a descriptive, but short, title (remember not to use any spaces in your repo name). Your README.md description can be brief for now; you’ll expand it and add links as your project grows.
  2. Ask your team members for their GitHub userids and add them as collaborators. Go to the Settings tab (somewhere in the middle or right side of the screen). When you add collaborators to a project, they’ll receive an email about your invitation (if they can’t find it, have them check Spam before resending).
  3. Add the instructors as collaborators, too, so that we can assist and follow your work more easily. Our GitHub userids are:

GitHub interface tabs

Once you’ve set up your repo on GitHub, let’s talk a little bit about the different tabs GitHub uses to keep you organized.

Code

The first tab, called Code, is where the files for your project live. This page allows you to see your repo, and to view files and their version histories. It also allows you to edit online, but editing on line is poor practice (= not permitted in this course), and we’ll show you how to work in a more robust way. You’ll be using Git regularly in your projects, and although it can be disorienting at first, you’ll become adept at the most important operations quickly.

Issues

Your GitHub Issues board is the place to discuss problems, ideas, and solutions with your team members, peers, and instructors. If you have a question, you can link your code to your post, tag team members, and flag your post so others see it.

Pull requests

Pull requests are fixes proposed by either team members or outsiders. For our class purposes, pull requests aren’t particularly useful, as your teammates and instructors (who are likely to assist you with code writing) have collaborator status, and collaborators can push to the repo directly, and don’t need to issue pull requests in order to make contributions. However, pull requests are an important part of collaborative coding and project building. You may have noticed that your new project is completely public-facing. Most digital humanists do their work in the public eye, as it creates a positive collaborative environment. When you get a pull request, it means that someone has seen potential in what you’re creating, and they have a genuine interest in improving it with you. A pull request says, I’ve figured this problem out, please feel free to pull my code into yours! You decide whether you use it (and also which branch you use it on).

Wiki

We’re going to skip over the Actions and Projects tabs for a moment (see below) and discuss the Wiki tab. This feature was added recently, and it may be useful for documenting your project if the documentation becomes too complicated to fit into a single README.md file. The Wiki is a convenient way to create a step-by-step guide or brief web page without initializing a whole GitHub Pages site (GitHub pages is an optional resource that is used not as much for project management as for publication). If you think you’d like to use the Wiki, feel free to play around, and tell the rest of us, so that we can learn from your experience. You can read more about the GitHub Wiki and its relationship to README.md pages at About Wikis.

Insights

Insights is a metrics tab that helps you track contributions to the project, and that your instructors we may use during evaluation. The Insights will help us see who pushes work, when they push it, and how much they’re pushing. You’ll want to aim for regular, sustained, incremental development, rather than sporadic large pushes. Not everyone will contribute the same amount every week; for example, it may be that during initial markup you push very little, but your teammates are pushing almost daily, while during site development you push often and they push little. Your contributions to the repo should be reflected in your Projects tab (see below) and Issue assignments. At the beginning there won’t be much data in the Insights, section, so don’t worry about checking it too much.

Settings

Settings is self-explanatory—poke around there yourself. Only the project owner has access to the Settings tab.

Projects

Finally, the Projects tab is a way to manage tasks and assignments. This board will help you get things done on schedule. Click the New project button and follow the directions. Choose the Basic kanban template once you’ve added your title and description, and then you’re ready to start. The first card issued to you is a mini-tutorial with different assignment tasks you can check off. Before you start, move your card to the In Progress tab, and away you go! After you’ve had a chance to poke around, start by creating an initial To do card. This card should say something like Create project team. After you confirm that all team members have accepted your invitation, you can move this card to the Done column.

As you begin to plan work (some of your first steps are going to be source identification, document analysis, and brainstorming), use these cards to track those tasks. Both project owners and team members can create cards as the needs arise. You can integrate the Issues tab with the Project board by using the three-dot menu at the top right of each card. An Issue will let you assign members, labels, and other useful stuff.

To make to-do lists, follow the GitHub-flavored Markdown syntax for task lists. Markdown and team member tagging (uses @) will come in handy here—so remember to use them!