What is this document
This document will guide you through administration of a Spark! owned Github repository, adding and managing collaborators and basic branch use.
Spark! utilizes Github.com to store and manage all code produced from our various projects. It is treated as the single source of truth for code from projects and is used both during active development and for archival purposes.
To add users to a repository utilize the
COLLABORATORS file located in the root of the repository. Put a single Github username per line and commit to
master. In the case that either branch is protected you can commit to
dev. A Github Action will run automatically and send invites to the new users and remove users who are no longer on the list.
This part will go over in more detail the process and intricacies of adding and managing users.
Types of Repositories
Repositories can be of two types, private or public. Private repositories can only be viewed by those who have been explicitly added whereas public repositories can be viewed by anyone (including non-BU affiliated individuals). In both cases, users must be added as collaborators in order to contribute code to the repository.
Look for the label next to the name of the repository on Github to identify if it is public or private.
Adding or removing a user to a repository
To add a user you need to add their Github username to the
COLLABORATORS file and commit it to the correct branch(typically
dev). In this case we will edit the file directly on Github so you do not have to download anything to your computer.
The first step is selecting the
dev branch from the list of branches on Github.
dev if it does not exist
dev branch does not exist you will need to create it by typing it in the box as shown below and choosing “Create branch: dev from ‘main’”:
Verify current branch
Once you have created or selected the
dev branch you should verify that the you are indeed on the
dev branch by looking at the branch indicator on the left corner:
Now that you are on the
dev branch, locate the
COLLABORATORS file in the root of the repository and select it
Next you need to enter edit mode in order to add Github usernames, this is located on the right hand side of the screen:
Add Github usernames
Now you are editing the file and can add or remove usernames from the list. There should only be one Github username to per line. Do NOT use email addresses, this must be their github account name.
Now that the username(s) have been added/removed we need to commit the changes to the
dev branch. Scroll down and you will see a small form that you can fill out describing the changes. You only need to fill in the first text field unless further explanation is required – good documentation is always appreciated! Verify that “Commit directly to
dev branch” is selected and click “Commit Changes” button.
You have now added/removed users and just need to wait for the automatic process to execute. New users will receive an email invite that will be valid for 7-days. They can click this invitation to become a collaborator on the project and be able to push code to the repository.
Why not commit directly to main?
It might seem odd that we have made the change on
dev instead of
master. We have chosen
master are typically protected branches that do not allow anyone other than Spark! staff to make changes. This includes making edits to files such as
COLLABORATORS or pushing changes from their local machines. For this reason,
dev is used throughout the semester and is where students and PMs can make changes to files.