Rich Rath edited this page Oct 2, 2017 · 25 revisions

GIT and the DIGITAL A&H Initiatve

Welcome to the University of Hawaiʿi Digital Arts and Humanities Inititiative (DAHI) user guide. If you have tripped across this other than by joining, you can find out about the inititiative here. We are open to anyone with an interest. You do not need to be at UH, though most of us are. You can be associated with any department (or none), not just A&H. We have besides A&H, people from the UH administration, the UH Press, the local community, other UH campuses Computer Science, Library and information science, communications, social sciences, and more.

Most of our planning and development takes place here on github, which can appear intimidating and wonky at first. We use a specific part of it, the issues section, to do most of our planning though, and that does not involve any coding or tech skills at all. Everything you need to get up and running on github issues is on this page.

DAHI is an open source, open access operation. We believe as part of our founding that open access is something that makes sense when we are a public university. That includes the output of our projects. The source code for any software or applications we develop is also open source. That way Github's millions of participants, many of them expert coders, can offer their input and expertise. In return, we share the source code for any project we work with. But you do not need to be a coder at all to participate, and in fact we need you!

There are three ways to participate in the development of the initiative and its projects. One is to be a "lurker" which anyone can do by going to https://github.com/digiah/ and looking around. All of our public projects will be there. The place where most of our development process takes place is in the "2do" repository's "Issues" page. A repository is a place for a specific project. 2do is our general purpose project. It links to the other projects as well. Code generally goes in the main part of the repo (see below for that, it is optional) but any digtal material can be stored there. GitHub is designed for open source collaboration on digital materials. Mostly though, we work on our issues, as befits arts and humanities! You can read all about what we are doing and when we hope to do it in the 2do/issues page.

The second level is to sign up for a free github account. Once you have a github account you can not only read issues but add and respond to them, but only the public ones.

What we hope you will do is the third level: send an email to rrath at hawaii dot schmedu (minus the schm) asking for an invitation to the digiah group. We will send it and you will then need to respond. That makes you a full blown member of the github digiah group (you are already a full blown member of the initiative!) with the ability to add code to the repositories and see any private digiah (i.e. DAHI) repositories.

Issues

The main thing most A&H people will want first is the "issues" section of the 2Do repository or another repo they are working on. Issues are for discussion and tracking of projects. Once you are in a particular repository, say 2Do, the issues tab is on the row of tabs on the right hand side of the page (where the wiki tab also resides). Since you are in the 2Do repository wiki right now, you should see the row of tabs on the right of this page. Issues is the second from the top. Issues are searchable. They are also writable, and you can start a new one if you don't see what you are looking for. If you go to the root GitHub page after signing in, you can see all your issues together rather than by repo. Another way to stay on top of all the issues is to check your github mail up at the top right corner.

The @USERNAME function is helpful. Use @ and someone's GitHub username to draw their attention to a comment. To refer to another issue in the same repository, just put # followed by the issue number (no space).

We would really like help from the whole team on issues. If you find a bug or think of an enhancement (or even an entirely new project), create an issue. Many of the issues already there are A&H rather than technical issues, such as how to write collaboratively. Have a look at the 2Do Milestones to get an idea of what we hope to accomplish when. To find out where we need you most, look at the issues that are labeled "help wanted," "discuss," "question," and if you are adventurous, "bug." Or take the long view and read through our "Blue Sky" ideas. Browse the other projects in the Digiah repository by reading their README files and looking at their issues. See if anything catches your interest. You could write directions or descriptions, code, do graphics, or figure out your own unique way to contribute. What will you contribute? Where?

Although having a bunch of unrelated issues open can look confusing at first, there are ways to manage efficiently. Search/filter for the issue you are looking for rather than browsing for it. Use a search term for a specific project, or use the drop-down tag and milestone filters. If you are looking for something that needs to be done, just search for open issues.

We need help here on the wiki too. You can edit the wiki if you are a Digiah group member (see above) and it would be great if you would write what you think will be most useful to new people. If you are shy about that (don't be!) or don't want to be a member of the digiah group then put it as a comment to issue #126 and we can sort it out together. All you need is a github account for that.

###EMail Notifications and other settings. Click on the settings for your account (the gear logo at the top right of this page, next to your username) and choose "notification center" to adjust the email settings if you do not want to be notified of updates. While you are there, take a look through the other settings. They are all pretty self-explanatory.

###Markdown Git uses a simple wiki formatting language called markdown. If you click on the edit button for the wiki you can see what it looks like. Any time you are working on text on github (such as in issues, or on the wiki) you can format text using markdown. Click on the question mark while in edit mode for a list of the formatting tags.

Gists

Gists are little repos that are used to jot down ideas, store code, or whatever. Here is how to create one. You can get to your gists by clicking on "gists" at the top of many pages. They can be public or secret. If you are not logged in they are anonymous. Secret gists aren't private. If you send the URL of a secret gist to a friend, they'll be able to see it. However, if someone you don't know discovers the URL, they'll also be able to see your gist. Here is a secret gist that you can read. If you read this would you please make a comment on it or edit it so that I know it works? Gist supports mapping GeoJSON files. These maps are also displayed in embedded gists, so you can easily share and embed maps.

Working with Git for development

There are some reasons not to use git for humanities work, and there are other options we are exploring (#3, #5, #6, #7, #8, and #9 for now), but the "issues" and the "wiki" functions are helpful. If you decide to learn the inner workings of git, then continue on, but generally there is no need to -- until you need to.

Getting the basic idea of software development can be done numerous ways. One is the vernerable Hello World exercise done git-style. Git is a program that you install to work with repositories on Github collaboratively. You get (clone) git repositories like this one to work with on your own computer, work on them, commit the changes on your local copy, and push them back to be merged into the codebase online that everyone in Digiah has access to. All changes are kept track of online and can be reverted. It is set up to keep track of multiple versions with multiple people working on them.

I found the Git Workflow visualization helpful. The Git Cheat Sheet is a handy way to remember the basics. It is part of the Git Training Kit. There are also open-access git classes.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.