Collaboration via GitHub
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.
- Navigate to GitHub
- Open the drop down menu at the top right corner
- Select "Your repositories"
- Select the repository to which you would like to invite others
- Enter the repository's settings
- Select "Collaborators"
- Select "Add people"
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.
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
- Navigate to GitHub.
- Open the drop down menu at the top right corner.
- Select "Your repositories".
- Select the repository to which you would like to invite others.
- 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
- Open the repository link supplied by its original owner.
- Select the fork button.
- 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".
- Back on the repository page, select the gear icon to make a few crucial edits.
- First, change the repository's URL so that it includes your username rather than the original owner's.
- Next, your forked repository needs to be manually associated with AudiAnnotate. You'll do this by adding the AudiAnnotate "topic" to the repository.
- Save your changes.
Editing a Forked Repository
- 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.
- Click the edit button and proceed to make changes as desired.
- 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".
- 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".
- 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.
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.
- Navigate to the pull request link via your GitHub notification email.
- Open the "Commits" tab.
- 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 (-).
- To accept the changes, return to the "Conversation" tab and select “Merge pull request”.
- If you are unsure of changes or have questions for the collaborator, you can continue a discussion by commenting on the thread.