![[Creative Commons BY-NC-SA 3.0 Unported License]](https://www.obdurodon.org/images/cc/88x31.png "Creative Commons BY-NC-SA 3.0 Unported License")
Last modified:
2020-01-19T21:05:19+0000
Maintained by: David J. Birnbaum (djbpitt@gmail.com)
Last modified:
2020-01-19T21:05:19+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 clear,
organized, and accessible. To start, go to https://github.com, where you already have your account, and click the green
New repository
button on the right. 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. Next, add your team
members as collaborators. Go to the Settings
tab (somewhere in the middle or
right side of the screen). You’ll be able to find everyone’s GitHub userid through the
introductory GitHub issue in the class repo. 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). Please add the instructors as collaborators, too, so that we can
assist and follow your work more easily. Our GitHub userids are:
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, and instead you’ll want
to follow the workflow for Git outlined in the Guide to Git Shell: Git and
GitHub at command line tutorial that you read earlier.
Your GitHub Issues board is the place to discuss problems, ideas, and solutions with your team members, peers, and instructors. A lot of collaboration and discussion should happen here, as it cannot all happen face-to-face. 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 Projects
tab 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 Documenting your projects on
GitHub.
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 Create a 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 should create cards as they see 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!