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.
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 “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 GitHub username to email@example.com and firstname.lastname@example.org or email@example.com.
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