github
- Introduction
- Opening a GitHub Account and & Setting Up Git
- Repositories
- Teams
- Making a Repository Public
All code generated at SPIRAL should be at a quality level that allows for worldwide dissemination. As a member of SPIRAL, you will not be writing code for yourself; you will be working as part of a team. Consequently, it is expected that you follow the coding practices and standards of the group. You must learn quickly from others and teach others if you have something useful and interesting to contribute. All project codes must be maintained in a version controlled repository. Our aim is to collectively grow our project specific code collections and generic tool libraries, for the purpose of producing reproducible scientific results.
If another reasonably knowledgeable and capable person cannot (1) use your code and replicate your results, (2) make modifications to your code to allow for its application to alternative problems and datasets, your code is useless. Always strive to learn how to write better code and how to improve our collective product. All codes will be disseminated to the public over the internet with appropriate credit to all contributors. These can (1) improve your impact on science and society, (2) showcase your work and capabilities to potential future employers.
-
Open a GitHub account at
https://github.comusing your ECE.NEU.EDU email (at any time, you can associate more email addresses with your account, however having the ECE email as primary makes it easier for other SPIRAL members to invite you to join repositories – use your ece email address). -
Get invited to the
neu-spiralorganization. You need an invitation to join; ask your advisor if you have not already received one. Doing so will give you access to SPIRAL resources, including this wiki. -
Read the GitHub documentation.
-
You have a couple of different choices for GIT software on your computer.
a. GIT GUI. (Also has the GIT Bash option) Note that when merging different versions, unresolved conflicts will cause extra text to be inserted in the code file, and this breaks the code. Do not leave any conflicts unresolved when committing.
b. GIT Extensions. This option is preferred by some CSL users.
c. Command line (GIT Bash), more complete and more advanced, but may require GIT proficiency. This option is preferred by some CSL users.
You can use any GIT software you want as long as you make sure everything is working correctly.
-
Remember to assign your full name (First Last) and ECE email address correctly in any GIT software you use. When you commit a code to a repository these credentials are used to show who committed the code.
Follow these instructions to create a new git repository. Make sure that you assign it to the neu-spiral organization and to set it to private. If you do not import it to neu-spiral, it may automatically become public.
Repositories from bitbucket, gitlab, or elsewhere, can be seamlessly transferred to github. Instructions on how to import a repository from, e.g., bitbucket, are here. Make sure that you import the project to neu-spiral, as opposed to your personal account, and that you make the repository private. Once a repository has been imported, it is very easy to change any local copies (e.g., on your laptop or on discovery) to make them point to GitHub rather than, e.g., bitbucket. Instructions on how to make local repo copy point to github rather than bitbucket are here.
Once you have created a repository you may want to invite team members to collaborate with you, or invite external collaborators. Finally, once a project is good to be shared with the outside world, you may want to make it public.
The neu-spiral organization has a hierarchical structure, and all its members are organized in teams. Everyone belongs to the spiral team. You should also belong to your lab/group team. If you are participating in a project, you may also belong to the team that is responsible for maintaining this project. You may want to create a new team; instructions on how to create a team can be found here.
Once you create a repository, it is by default only viewable and editable by you. You may want to make it available to one or more teams. Instructions on how to give access to a team to your repository can be found here.
The recommended behavior for how to share SPIRAL projects with teams is as follows:
- If your repository belongs to a project, give write permissions to the entire team of that project.
- In addition, give read permissions to any SPIRAL groups may in any way related or affiliated with the project.
- In addition, give appropriate (read or write) permissions to any external collaborators.
Example: Suppose that you created new repository named ASSIST, containing the code for the NSF-funded project ASSIST. This project includes SPIRAL members from the CSL, ML, and DNAL labs, and a few external collaborators. The repository for should then be shared with write permissions with the entire ASSIST team. It should also be shared with read permissions withe CSL, ML, and DNAL teams. Finally, external collaborators should be invited as individual collaborators.
Individual collaborators (either internal or external) can also be added to a project. If you intend to add a lot of internal collaborators, you might as well create a new team. Instructions on how to add individual collaborators (either internal or external) can be found here.
Once you have published a paper, you may want to make the code you used for this paper public. Instructions on how to make a repository public can be found here. Before doing so, make sure that it is released under the right software license, and that your code is well-documented; in particular, your repository should contain a README.md file, written in markdown language.
