Collaboration via GitHub

Creating a Shared Repository | Fork and Pull

There are two methods of creating collaborative projects in GitHub. The simplest method is the Shared Repository, where one user creates an AudiAnnotate project and additional users are manually invited to join that project by the initial user. The second, more complex method is to use GitHub's "fork" and "pull" features. This method involves one user creating a repository and additional collaborators making a copy of that repository using GitHub’s fork (i.e., copy) feature, making changes, and making pull requests which can then be merged into the original repository after being reviewed and approved by the repository owner.

Creating a Shared Project

To create a shared repository (i.e., project), first create a project in AudiAnnotate. Once created, you will be able to give collaborators access to the generated repository through GitHub. You can invite collaborators by their GitHub username or by their email address. If they do not already have a GitHub account, the invitation will prompt them to create an account.

  1. Navigate to GitHub

  2. Open the drop down menu at the top right corner

    3. Open the drop down menu at the top right corner

  3. Select "Your repositories"

    4. Select "Your repositories"

  4. Select the repository to which you would like to invite others

    5. Select the repository to which you would like to invite others

  5. Enter the repository's settings

    6. Enter the repository's settings

  6. Select "Collaborators"

    7. Select "Collaborators"

  7. Select "Add people"

    8. Here, you can add collaborators by email or existing username. Note that email invites expire after 7 days. If you add them by email and they do not have an account, the invite will prompt them to create one. Once collaborators have access to the repository, they will be able to add annotations to the project through the AudiAnnotate application.

    Select "Add people"

This workflow was created with Tango

Fork and Pull

After the original owner of the repository has created a project, added audiovisual material(s), and attached annotations, they can provide collaborators with a link to the repository in GitHub. With that link, collaborators will be able to "fork" (copy) the repository into their own GitHub account. They can make changes to their copy of the repository before submitting a "pull" request to the original owner. The owner will be notified of the request and have the option to either adopt the changes or reject them.

Sharing the Repository Link

  1. Navigate to GitHub.

  2. Open the drop down menu at the top right corner.
    3. Open the drop down menu at the top right corner

  3. Select "Your repositories".
    4. Select "Your repositories"

  4. Select the repository to which you would like to invite others.
    5. Select the repository to which you would like to invite others

  5. Copy the link to your project's repository from your browser's address bar. (The link should follow this formula: github.com/YourUsername/YourProjectName.) Send this link to any collaborators so that they can "fork" the repository into their own GitHub account.

Forking a Repository

  1. Open the repository link supplied by its original owner.

  2. Select the fork button.
    3. Screen Shot 2022-07-05 at 3 28 24 PM

  3. On the page that opens, you will choose the account to fork the repository to. You'll also have the option to rename the repository and to add a description. Once you've done so, select "Create fork".
    4. Screen Shot 2022-07-05 at 3 32 50 PM

  4. Back on the repository page, select the gear icon to make a few crucial edits.
    5. Screen Shot 2022-07-05 at 3 34 07 PM

    • First, change the repository's URL so that it includes your username rather than the original owner's.
      • Screen Shot 2022-07-05 at 3 35 38 PM

    • Next, your forked repository needs to be manually associated with AudiAnnotate. You'll do this by adding the AudiAnnotate "topic" to the repository.
      • Screen Shot 2022-07-05 at 3 35 54 PM

    • Save your changes.
  5. Because your project was forked, AudiAnnotate did not automatically generate a webpage for it. To force this creation, edit the README file on the repository page. Select the pencil icon on the README file to make edits.
    6. Screen Shot 2022-07-05 at 3 37 57 PM

  6. Add any text to the README file. We suggest text that shares the origins of the repository, e.g.: “Forked from [username of original user]/[repository name].” Commit your changes.
    7. Screen Shot 2022-07-05 at 3 40 51 PM

Editing a Forked Repository

  1. Navigate to your projects page in AudiAnnotate. You should see a project tile for your forked repository there—look for the "Forked from..." text on the tile.
    2. Screen Shot 2022-07-05 at 3 42 57 PM

  2. Click the edit button and proceed to make changes as desired.

  3. Once your changes have been made, you must submit a pull request wihtin GitHub. Navigate to the GitHub repository page and open the drop down under "Contribute". From there, select "Open pull request".
    4. Screen Shot 2022-07-05 at 3 47 36 PM

  4. On the next page, you can compare the differences between the original and your forked repositories if desired. Once you are ready to notify the original owner of your proposed changes, select "Create pull request".
    5. Screen Shot 2022-07-05 at 3 51 37 PM

  5. On this page, you can add a note about what you changed (e.g., “imported additional annotations”) and then select “Create pull request”. At this point, GitHub will send a request to the owner of the original project to review your proposed changes.
    6. Screen Shot 2022-07-05 at 3 52 14 PM

Responding to a Pull Request

Once a collaborator has created a pull request requesting a change in a repository that you own, you will have to review and decide whether to accept their changes. GitHub will send an email notification when a pull request has been created. This email will provide a link to the pull request made by the collaborator.

  1. Navigate to the pull request link via your GitHub notification email.

  2. Open the "Commits" tab.
    3. Screen Shot 2022-07-07 at 5 08 15 PM

  3. Click individual commits to review changes at a more detailed level. Additions will be highlighted in green and preceded by a plus sign (+); deletions will be red and preceded by a minus sign (-).
    4. Screen Shot 2022-07-07 at 5 08 58 PM

  4. To accept the changes, return to the "Conversation" tab and select “Merge pull request”.
    5. Screen Shot 2022-07-07 at 5 09 23 PM

  5. If you are unsure of changes or have questions for the collaborator, you can continue a discussion by commenting on the thread.