Guide to GitHub for PPG

Why GitHub?

GitHub provides tools to allow us to have open, collaborative discussions of taxonomic proposals, and to maintain a record of those discussions publicly available in perpetuity.

Setup

In order to participate in PPG discussion you will need to obtain a GitHub account (the free account is fine). Anyone can browse the discussions, but only GitHub account-holders can contribute to them.

Background information

About repos

A repository (or “repo” for short) is a project—a collection of files in a single folder (that may contain subfolders) that is tracked by a piece of version-control software called “git”. Git can be thought of as a fancy “undo” tool—it keeps track of all previous versions of your documents so you can always go back to earlier versions if you want to. GitHub is a web service to host repos in the cloud (online) so that anybody can access them. For our purposes, one need not know anything about git—just think of GitHub as a website that can host our classification and our discussions.

About issues

Issues are the tool that GitHub uses to track “to-do” items related to the project. A repo will have a list of issues (like a to-do list), each of which can be open or closed. Open issues still need to be completed. Closed issues have been resolved. Issues can be commented on in a discussion, and the discussion will remain online in perpetuity, even after the issue is closed.

About markdown

When you create a new issue or add a comment on an existing issue, you can only use plain text (no bold, italics, etc). In order to add formatting, you need to use a syntax called markdown. In markdown, you indicate how the text should be formatted with special characters, such as asterisks around words to be shown in italics. That is why any dialog box to enter text in GitHub has two tabs, “Write” and “Preview”. You enter the text in the “Write” tab and click on “Preview” to see how the formatted text will appear. For more on writing with markdown, see this help doc.

Tip: No markdown needed

If you don’t want to bother with markdown formatting, you don’t need to use it! Feel free just to write with plain text.

The PPG repo

We will use a GitHub repo to maintain the PPG classification (in the form of a CSV file) and to organize and maintain a record of all community discussions using issues1. It is located at https://github.com/pteridogroup/ppg.

Note

In order to be able to complete each of the steps yourself, you will need a GitHub account (see Setup).

There are three basic things to learn: creating a new issue, searching for an issue, and commenting on an issue.

Creating a new issue

Warning

Before submitting a new issue, please search the existing issues to see if one already exists.

  1. Click on “Issues” in the top navigation bar of the repo homepage (Figure 1).

Figure 1: Repo homepage

  1. Click on the green “New issue” button (Figure 2)

Figure 2: Issues page

  1. Click on the “Get started” button next to “Taxonomic proposal” (Figure 3)

Figure 3: Issues templates page

  1. Fill out the form provided (Figure 4). It includes fields to ensure that proposals to update PPG are sufficiently informative for productive discussion. When you are done filling out the form, hit the “Submit new issue” button. You’re done!
Tip: Include the taxon name in the issue title

It will make it easier to find issues if you include the name of the taxon in the title (e.g., “Add Gastoniella”)

Tip: Add a PDF

If you want, you can upload a PDF (or other file) by dragging it into the text box. It will automatically upload to GitHub and a link will be added. Click “Preview” to see how the link will look.

Figure 4: Issue form

Searching for an issue

  1. Click on “Issues” in the top navigation bar (Figure 1), which will take you to the “Issues” page (Figure 2). You will see issues in chronological order.

  2. Use the search bar (Figure 5) to find an issue you are interested in. Note that the search only includes open issues by default; pressing on the button listing the number of closed issues will bring them up instead.

Figure 5: Issue search bar

Commenting on an issue

Anyone with a GitHub account can comment on an issue.

  1. First, find an issue you are interested in (it could be one you created). See “Searching for an issue” for how to do that.

  2. Once you find an issue you are interested in, click it. You should see the page for the issue, with a dialog box at the bottom (Figure 6).

Figure 6: Commenting on an issue

  1. Fill out the dialog box with your comment and press the green “Comment” button. Keep in mind that we will maintain this discussion thread in perpetuity, and want it to be maximally useful for all users. Of course, civility is essential, and please make the extra effort to ensure that each comment has the maximal amount of information—refrain from contributing to long threads of simple agreements, or unfocused discussions.
Tip: Don’t press “Close issue” (usually)

You may notice there is also a “Close issue” button. This will only be available to the person who created the issue and to the maintainers of the repo. Generally you should not press the “Close issue” button—the maintainers of the repo will take care of that, after voting is complete.

General discussions

So far this guide has focused on using issues as a forum for discussing taxonomic proposals. If you have something else you want to talk about, for example, discussing how PPG is maintained, asking a question about using GitHub, etc., please use the Discussions feature, available at https://github.com/pteridogroup/ppg/discussions.

To start a discussion, click the green “New discussion” button, select a category, and fill out the text box.

The interface is very similar to issues, but general discussions don’t get marked as “open” or “closed”. We want to separate taxonomic proposals from general discussions to make it easy to track which proposals have been approved and implemented2.

Figure 7: The Discussions forum

Voting

GitHub is not used for voting. For more details on how voting is carried out, see the PPG Guidelines.

After voting, the results will be indicated on each proposal (issue) that was up for a vote, including the tally of votes for and against. The issue will not be closed at this point, however. Issues will only be closed once they have been implemented in the data.

Notifications

It is a good idea to subscribe to GitHub notifications so you don’t miss anything. We recommend receiving email notifications for all activity on the PPG repo. To do this, first log in to GitHub. Next, go to https://github.com/pteridogroup/ppg/ and click on the “Watch/Unwatch” button and select “All Activity” (Figure 8). Finally, to make sure that you receive notifications as emails, go to https://github.com/settings/notifications, and make sure “Email” is checked under “Subscriptions” (Figure 9).

Figure 8: The Watch/Unwatch button

Figure 9: Subscription options

Footnotes

  1. There was a demonstration repo originally set up for testing purposes at https://github.com/pteridogroup/ppg-demo. The demonstration repo is no longer active, but is still online for reference.↩︎

  2. If you notice a bug in the PPG database, filing an issue is appropriate way to let us know about it. Generally, issues are something that can be marked as completed and closed, whereas discussions are more open-ended↩︎