Maintained by: David J. Birnbaum (djbpitt@gmail.com)
Last modified:
2022-01-19T01:59:02+0000
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:
New repositorybutton 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.
Settingstab (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).
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.
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.
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 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).
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
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
is self-explanatory—poke around there yourself. Only the project owner
has access to the Settings tab.
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!