Resources

Accounts

Creating an account in GitHub is pretty simple

1. If you already have a GitHub account, go directly to step 4. Otherwise, go to http://github.com
2. Complete the form with a username, email address, and password.
   • Remember that your username will be your screen name and the way we’ll find you (and you’ll find others) in github.
   • Remember, too, that the email you enter is the location to which all notifications will be sent moving forward.
   • Yes, your account will be free.
3. Click the big green button to “Sign up for GitHub.”
4. Send us (dbloom@vertnet.org and/or larussell@vertnet.org) your username so we can find you in GitHub.
5. Congratulations, you’re in! (don’t forget step #4)

Navigation: Finding your Organization and Repository(ies) in GitHub

Once you’ve sent us your username and we’ve added you as an owner of your institution’s organization within GitHub, you can begin to look around and get things set up.

Below, we’ve described the most important pages and features relevant to VertNet Issue Tracking. GitHub, especially at first, appears overwhelming in it’s scope, navigation, and features, but before you throw your hands in the air and go take a walk outside, we want to assure you of a few things.

1. GitHub was made for developers - but don’t let that scare you. Folks use GitHub for all kinds of things, including wedding planning, day care scheduling, and a whole host of things you’d find hilarious and inspiring.
2. There are tons of features and options in GitHub, most of which we won’t ever use. The few features we will use have been described below to make this process as easy as possible for you and so you can see what will pop up on your screen.
3. In many cases, you won’t even need to log in to GitHub to track issues. GitHub is set up so that all notifications are sent to your email service. You can reply to issues directly from your email account without having to log in to GitHub. So, for you or other members of your teams who don’t want to fuss around with GitHub much, it is possible that the only time they will have to login, is when the create their username and password. After that, the majority of the work can be done via email and in your own collection database. Only administrative functions will have to be performed while logged in to GitHub.

Go ahead, start looking around. Be brave.

1. Go to https://github.com/ and log in.
2. To get to your organization, you can click the drop down menu on the left side of your home screen - A below - or click on your username in the upper right of the screen - B below.

   GitHub Home Page, after user login.

   
   
3. If you click A you’ll see a drop down menu of all of the organizations you own or of which you are a member, as well as some management options. Just click the organization in the menu you want to visit, and you’ll be taken your organization's activity summary page.

   Sample organization activity page (Option A).

   
   
4. If you click B, you’ll be taken to your personal activity summary page. All of your organizations, etc., are displayed in the lower left, directly under your avatar and name. Click on the one you want to visit (although, you’ll probably only have one organization to choose from). From there, you will be taken to your organization's main page.

   Sample personal activity summary page (Option B).

Regardless of whether you clicked A or B above, you have arrived at one of your organization's pages. Welcome. On both pages (below) you’ll see several items that will help you to navigate and maintain your repositories. We’ve highlighted a few of the important links you’ll want to know about. Feel free to click around for a minute and to get lost. If you do get lost, you can always click your username in the upper right to return to your personal activity summary page or the GitHub icon in the upper left to return to your organization's activity summary.

Important links on the organization activity page.

Important links on the organization activity page.

Repository Pages

A repository is the place to keep all of the issues, discussions, files, and other items related to a particular part of your project. For you, and for VertNet, each repository associated with your organization is related directly to each of the data sets you have published to your IPT, hosted either by VertNet or your institution. We’ve already set up all of the relevant repositories for you - each one has a name that corresponds directly to the name of the IPT resource you’ve published. For example, the MVZ has eight repositories because there are 8 individual data sets each named for the data set published via IPT (e.g., mvz-bird, mvz-herp, mvz-egg). By comparison, UTEP will have only one repository (utep-vertebrates) because they have elected publish a single data set via IPT.

To visit a repository (sample below), simply click on the name of a repository (see above). Your repository pages will remain pretty simple, and mostly unchanged, because we do not expect these pages to be used for code - just for issue tracking. There are, however, a few things on each repository page that you should know about.

• README.md is a simple file into which you can place a description of the repository. We’ve already added a simple description for you, but if you want to edit it or add a description of the collection, please feel free.
• Reports contain the monthly statistics that detail the use of the content within each dataset in the VertNet portal. We've put together a Usage Reporting Guide to help define the contents of the reports.
• Watch Settings allow you make certain you receive notifications when activity occurs within the repository, such as posted issues, responses, and monthly reports . If you are an Owner of a repository, you should, by default, receive notifications of these events, but it doesn’t always work. So, to assure yourself, or others on specific teams, it is a good idea to make certain that this setting is set to “Watch.” When set to “Watch” the settings window will read “Unwatch” (see image below). This is correct, if not a little counter-intuitive. To stop receiving notifications, just change the setting to “Unwatch” (or, do not watch), and the settings window will read “Watch.”
• Settings is where owners can perform some maintenance functions, most of which you will never use. Not to be confused with your Account Settings, repository settings control only a given repository. This is also the page on which you can change the name of or delete the repository. Please don’t do either of these things. If you are having issues with a repository, please let us know first. We are likely to be able to solve the majority of your problems. If you change the repository name, we cannot guarantee that issues will be tracked correctly. If you delete the repository, everything, including the issue tracking, is lost for good.
• Issues is the primary reason for this exercise. When you click this link, you’ll be able to view and manage the issues submitted to this repository, including viewing individual issues, creating labels, and generating new issues.

Important links on sample repository page.

Issue Pages

NOTE: If you are navigating from your organization’s activity page, and you click on the Issues link, you’ll arrive on an issue page that includes a list of all issues submitted to your organization. This page can be handy, but If you want to see the issues for a specific repository, you’ll need to navigate BACK to the activity page and click on a specific repository first.

Sample issue summary page.

Once you’ve arrived at a repository issues page, you will see a list of the issues submitted to that repository (there may not be any issues in your repositories yet, but we’ll make sure you get some soon).

When you click on an issue, you’ll be taken to that issue’s page. On this page, you’ll see the original issue/message as it was posted and any responses. Beneath the issue, or perhaps the most recent comment, you’ll find a text box into which you can add to the discussion.

When a team member (perhaps you or another individual responsible for that repository) decides that the issue has been addressed or that the discussion has come to a conclusion, he or she can click the green “Close” button at the bottom of the page to close the issue. Closing an issue is not required, but it’s a great way to let everyone participating in the discussion, or who might have subscribed to the repository, that an issue has been resolved.

At the top of each issue page is the issue’s unique URL. Because all of your repositories are public, you can provide it anyone, via web page, email, or document, and they will be able to visit the page and contribute (viewing is easy, but contribution to the discussion will require a GitHub username).

Within each issue page, you’ll have the opportunity to assign one or more labels to the issue, as well as assign the issue to one or more individuals to address. If you’re feeling wonky, you can even assign this issue to specific milestones, but you are very unlikely to use any milestones for this use of GitHub.

Sample issue page.

Organizations

Now that you’ve had a chance to look around, you’re probably ready to set up your organization and to add others at your institution to your organization. To begin, we need to set up your Organization Profile.

1. Click the Account Settings icon in the upper right corner of your browser window (it’s that wrench and screwdriver). This will take you to your settings page.
2. On you setting pages, look on the left side of your window. There will be a list of all of your accounts and organizations. Click on the organization you want to set up.
3. A drop down menu of options should appear with several options (e.g., Organization Profile, Billing, Payment History). On the right side of the window you should see your Profile Information. When we set up your organization, we filled in some of this information, but now that you’re the owner please update or verify the following:
   • Name: Your organization name will probably look something like “mvz-vertnet”. For now, just leave it as it is - just make sure your institution code is correct in the name.
   • Email (Publicly visible!): Please change this to your email address, or to one directed to your institution. This allows folks to contact you from GitHub if there are questions of problems (this type of communication is very rare).
   • URL: Feel free to add a URL for your institution or collection.
   • Location: If you wish, you may add an address or other locality information about your collection or institution. We recommend “City, State, Country” or similar, if you are not within the United States.
   • Billing Email (Private): Please change this to your email address or another one directed to your institution. This account for your organization is free, so there is no need to worry about charges, but GitHub requests an email here just in case you decide to upgrade.
   • Gravatar Email (Private): An email address here is not required, but if you want to set up a Gravatar account so that your avatar (which can be in image of your institution’s logo) is pulled in automatically, you’ll need to use the email address you used to set up Gravatar.

Sample organization profile.

Once you’ve made these changes, your Organization Profile is complete.

NOTE: This is also the location where you can rename and delete your organization. Please don’t do either of these things. If you are having issues with your organization, please let us know first. We are likely to be able to solve the majority of your problems. If you change the organization name, we cannot guarantee that issues will be tracked correctly. If you delete the organization, everything, including the repositories and issues, will be lost for good.

Notifications

IMPORTANT: Just because you are registered as an owner of one or more organizations does not mean that you will receive notifications of activity automatically. To receive notifications you must first create one team AND add yourself to the team. Once you have done this you will receive notifications regarding any activity within the repository or repositories connected to that team.

For example, we’ve already created a team called “VertNet” to your organization. This team includes a few key members of the VertNet team who will monitor the issues submitted to each repository to make certain that any issues that are related to our responsibilities to your data and the portal will be addressed promptly. [NOTE: please do not delete or modify this team. Changes to this team could result in missed notifications on our side.] Feel free to take a look at the VertNet team and how it was set up as you move forward.

You can learn how to add teams in “Creating Teams and Adding Team Members of Collaborators” below. Just remember to add yourself and all other owners to each team you create so you can keep track of all activity within the organization.

Also be sure to check your Watch Settings in each repository. The Watch settings allow you make certain you receive notifications when activity occurs within the repository, such as posted issues, responses, and monthly reports . If you are an Owner of a repository, you should, by default, receive notifications of these events, but it doesn’t always work. So, to assure yourself, or others on specific teams, it is a good idea to make certain that this setting is set to “Watch.” When set to “Watch” the settings window will read “Unwatch” (see the first image in the Repository Pages section). This is correct, if not a little counter-intuitive. To stop receiving notifications, just change the setting to “Unwatch” (or, do not watch), and the settings window will read “Watch.”

Owners

Who Should Be An Owner

It may not always be clear who within your institution or collection should be an owner or a member (or collaborator) of your GitHub organization. To help you make your decisions, the following are our recommendations to get you started. Of course, your institutional needs may vary or change over time, so you can take some comfort in knowing that an assignment as an owner or member is not permanent. These relationships can be changed at any time.

Owners should be individuals who:

• need to, or should, receive notifications of activity within all repositories (if you have more than one);
• should have the ability to add/remove owners and members from your organization or teams;
• and, who should have administrative access to all areas of the GitHub organization.

Some examples of the type of individuals we might recommend as owners include curators and collections managers with oversight over multiple collections and/or taxa, IT managers who maintain institutional technology and provide database and collection support, and administrators or other individuals with oversight and decision-making authority over multiple collections.

Members (or collaborators) should be individuals who:

• have a taxonomic or collections-based focus and should receive notifications of activity within specific repositories, but not all of them (if you have more than one);
• do not, should not, need the ability to add/remove owners and members from your organization or teams;
• and, do not need to have administrative access to all areas of the GitHub organization.

Some examples of the type of individuals we might recommend as team members include curators and collections managers with oversight over a single collections or taxon, IT personnel who work with collections staff and databases who should be notified of issues related to specific collections or taxa, and administrators or other individuals who should receive notifications of issues for specific collections or data sets.

Remember, an individual who is a team member can always subscribe to other repositories on their own if they wish to receive notifications regarding other repositories or issues.

To Add An Owner

(If you’re already on the Organization Profile page, you can start with step #3)

NOTE: To add an individual as an owner to your organization, he or she must first have a registered username with GitHub. Please ask each individual to create a GitHub account following the instructions at the beginning of this guide. They should share their username with you, since you’re the owner. If you have any issues, we’re available to help.

1. Click the Account Settings icon in the upper right corner of your browser window (it’s that wrench and screwdriver). This will take you to your settings page.
2. On you setting pages, look on the left side of your window. There will be a list of all of your accounts and organizations. Click on the organization to which you want to add an owner.
3. Click Owners in the list of options under your organization name. One the right side of the window you should see a list of the members of the organization’s Owners Team. This is the group of people with full administrative access to your account - including several members of the VertNet team. Please leave us on the team just in case we need to help you with questions or problems. You should also see your username, on the list.
4. Click the Owners Team link just above the list of owners toward the top of the page.


Sample owners page.



5. Now you should see the list of owners, now with the option to “remove” existing owners. At the bottom of list there is an empty text field with an Add button. Simply type the GitHub username of the person you want to add as an owner, and once select, click add.


Add/Remove owner interface.



6. You should now see the new owner listed in the list above.

You may add as many individuals as owners as you wish, but we recommend that you limit this type of access to those individuals who really should have full administrative access to your organization.

Teams

Creating Teams and Adding Team Members or Collaborators

(If you’re already on the Organization Profile page, you can start with step #3)

NOTE: To add an individual as a collaborator to your organization, he or she must have a registered username with GitHub.

1. Click the Account Settings icon in the upper right corner of your browser window (it’s that wrench and screwdriver). This will take you to your settings page.
2. On your setting pages, look on the left side of your window. There will be a list of all of your accounts and organizations. Click on the organization to which you want to add an owner.
3. Click Members in the list of options under your organization name. On the right side of the window you should see a list of all of your organization’s members - including owners. At first, your list of members will be identical to your list of owners. You should also see buttons to allow you re remove individuals from the organization.
4. Click the Team Management link just above the list of members toward the top of the page.


Sample members page.



5. Now you should see a list of all the teams associated with your organization. At first, you’ll have only one team (Owners) lists.

Sample team management page.

Remember that herp collections manager we mentioned above who needs to get notifications from the herp repository, but not from birds or mammals? To add her to the organization as a member, we first need to create a team for the herp repository.

Create a New Team and Add Collaborators

1. Click the New Team button.
2. Now you should see a window with several options to help you to create your team.
   • Name: Give your new team a name (e.g., Herp Team or Aves or Barbara’s Army).
   • Permissions: You can choose the level of permissions to grant this team, but we strongly recommend that you grant “Push, Pull, & Administrative” permissions. This will make many communications and actions much easier in the future.
   • Members: Just like we added new Owners, simply type the GitHub username for each collaborator you want to add to your team (e.g., our herp collection manager). You can add as many collaborators as you want, you just have to do it one at a time. Click Add to add each member to the list.
   • Repositories: To make your issue tracking work, you’ve got to connect your team with at least one repository.

     • NOTE: for this process, you’ll need to know the exact names of the repository(ies) affiliated with your organization, but once you start typing the name of a repository in, GitHub will autocomplete the name or provide a drop down list of repositories that match. Select the repository you want to add, and click Add to add it to the list.

     • Remember, you don’t need to add individuals who are already owners to a given team because they should receive all notifications related to the entire organization, but we recommend that you add everyone to a team whom you believe should be listed as such (including owners). This way, when a team member or subscriber wants to see who is on this team - or if you want to assign responsibility to a specific individual for a specific issue - everyone on the team is listed.

   • When you’ve added all of your team members and associated repositories, click Save Team. You can add or remove team members and repositories at any time.
   

   Sample team creation/add member interface.

   
   
   • You should see confirmation of your creation at the top of the screen - GitHub puts a message highlighted in blue, when your team has been saved.
   • To verify your team is on the list, or to create another team, click the Teams link on the right side of the window. You can add or remove team members and repositories at any time.

Now you should be ready to start receiving and processing issues. Congratulations!

GitHub Help

GitHub Help ( https://help.github.com) is pretty darned good, so don’t be afraid to use their services, too.