Stable link to this page: https://doi.org/10.7299/X75B02M5

Getting Started with Github for Arctos

Why Use GitHub for Arctos?

I’d also like to echo the value of the community from a development perspective. A broader perspective seems to make EVERYTHING better. I can often build stuff that just works out of the box because a bunch of people with very different perspectives looked at it before we started writing code. The key to an extremely robust locality model seems to have been getting parasitologists and ethnologists in the same conversation. Rapid digitization of a paleo collection drew heavily from stuff developed for a herbarium. Etc ad nauseum. I don’t think there’s any remote possibility that any “traditional” group of collections or developers could have built anything like Arctos; it’s a synthesis of the community. ~ Dusty McDonald, Arctos Programmer

The tool we use to accomplish what Dusty describes above is GitHub.

• GitHub serves as the primary means of communication between Arctos developers and users.

• GitHub is where Arctos users can contribute to the Arctos Handbook via the Arctos Documentation-wiki Repository.

• If you have an Arctos question or problem, post it on the Arctos Issues site. There you can also view and comment on issues.

How to Get Started in GitHub

• Set up a new (and free) account in GitHub. Go to http://github.com and fill out the form with a username, email address, and password. Your username will be your screen name. Your email address will be used to send notifications.

• Click the big green button to “Sign up for GitHub.”

• Edit your GitHub profile to include your name and Arctos Institution. This helps other Arctos users know who they are developing with when discussing Arctos Issues. To do this select “Profile” from the drop down in the top right corner of the GitHub page.

Then select the “Edit profile” button on the left side of your profile page.

You can add a photo to replace the GitHub generated avatar, but it isn’t completely necessary. The most helpful thing you can do here is to add your name and institution so that everyone working with you in Arctos will know who you are.

Be sure to save your edits! Now you are ready to get to know GitHub!

GitHub Membership Levels and Permissions

Anyone can view, post, or comment on an Arctos Issue. You do not need special permissions to do this. Without special permissions, however, you cannot label an issue, close an issue, assign an issue to another person, or assign a milestone to an issue.

Arctos Users Team

Any active Arctos user may request permission to become a member of the Arctos Users team.

• “Users” may create and/or edit Arctos Handbook pages and organize (assign labels and milestone or vote by reacting) Issues. To become a member of this team, send an email with your name, institution, Arctos username and GitHub username to arctos-working-group-officers@googlegroups.com.

• Look for an invitation in your email folder from GitHub for the Arctos Repositories, and use the invitation to sign in to GitHub. Make sure you sign in to Github prior to attempting access Arctos repositories.

• Arctos Users may request AWG Task Force Meetings to finalize Issues, or groups of related Issues. Start a Doodle poll and paste the link into the Issue(s) you wish to address.

• Users have access to the documentation code where they can create and edit pages for the Arctos Handbook Documentation and How-to Guides. See instructions on how to create and/or edit content in the documentation-wiki repository.

• Users cannot invite other members.

Arctos Owner Team

Arctos Owners have administrative permissions.

• Only people with administrative permissions can add new members. To do that, go to https://github.com/ArctosDB and click on “Invite someone” at the bottom of the People pane on the right of the window. Search by the person’s GitHub username and enter it where prompted. Select the person to add. He/she will need to accept the membership invitation in order to become a member. When you invite someone, the default role is ‘member’ versus ‘owner’ which has more administrative privileges.

VertNet, TDWG, and other GitHub Repositories

If you want to receive notifications (e.g., data issues) from VertNet, TDWG, or any other GitHub repository, your GitHub account needs to be added to them.

• VertNet For more information, read the VertNet Guide to Issue Tracking.

Managing GitHub Notifications

Once you have created your GitHub account and joined the Arctos repository, you will begin to get email from GitHub. Because our GitHub is very active, the amount of email can be overwhelming. So, how do you avoid 100 emails a day but still stay in touch?

You can manage email notifications in your GitHub settings, which you can access from your account profile or directly from the dropdown next to your GitHub avatar on any GitHub page when you are signed in.

To learn about GitHub Notifications and how to manage your GitHub experience in general, we suggest you read Managing your notifications

Watching vs Participating

So, the most confusing part is knowing when I am part of the conversation or just receiving comments from various issues that don’t involve me.

For each repository in GitHub you can select a participation setting. The setting you choose helps determine what kinds of notifications you receive. To see your watch settings for your GitHub repositories: in your GitHub profile select settings > Notifications and the linked text “things you are watching” at the top right of the page.

You will see a list of all of the GitHub repositories to which you have subscribed. For each one, you can choose the types of notifications you receive or not based upon the watch status you assign.

• Watching is the default. You will be notified of all conversations.

• Not Watching is not the best choice for the community, but a good choice for managing notifications when you don’t want to stumble upon issues that might interest you. You will only recieve notifications if you are participating (you started an issue or commented on one) or are mentioned (someone assigns an issue to you or uses your GitHub username in the text of an issue).

• Releases Only is effectively the same as Not Watching for Arctos Users.

• Ignoring is not recommended. You will never receive notifications.

TIP Web Notifications - Don’t get any email from GitHub

With a bit of discipline, you can avoid receiving any email from GitHub and still follow the conversation. In your GitHub profile, select settings > Notifications and change “watching” and “Participating” to “Web”.

THEN set a reminder in your personal calendar to review GitHub issues. To do this, select the little blue bell next to your avatar.

You will be rewarded with a list of unread notifications. You can peruse the list, read the issues that interest you and mark those that don’t as “read”. Depending upon the level you wish to participate, you might check once or twice a day or once a week, but less than that might mean missing out on contributing to an important conversation.

Using Arctos Issues

See How to Use Issues in Arctos

Devolping Arctos with GitHub

Developers who are interested in Arctos code can view it in the ArctosDB/arctos and ArctosDB/DDL repositories.

Editing the Arctos Handbook

See How to Contribute Content to the Arctos Handbook

More advanced users can check out How to get the most out of Arctos-Github

Edit this Documentation

If you see something that needs to be edited in this document, you can create an issue using the link under the search widget at the top left side of this page, or you can edit directly here.