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.
Introduction
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.
Quick Summary
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 main
or 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.
In depth
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.
Select dev
branch
The first step is selecting the dev
branch from the list of branches on Github.
Create dev
if it does not exist
If the 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:
Locate file
Now that you are on the dev
branch, locate the COLLABORATORS
file in the root of the repository and select it
Edit COLLABORATORS
file
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.
Commit changes
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.
Complete
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 main
or master
. We have chosen dev
because main
and 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.