Skip to content

Admin guide

Jump to bottom
Wenbin Yang edited this page Apr 11, 2019 · 1 revision

This admin guide is for admin users who have basic knowledge about GitHub and Perfect-Lab-System. For common users, please check this User-guide to start.

This guide will teach you how to build up a repository for your project and how to configure cloud storage (Nutstore) to make users take advantages of both Git and cloud storage. Finally, there are some design principles and ideas that are crucial for Perfect-Lab-System.

If you also have interests in organizing and managing things especially for projects, please join us to make this system better.

Content table

Advanced topics

Create a GitHub repository for a project

Please ask an admin user to assist you to create a new repository In the design of Perfect-Lab-System, there are two types of repository.

Code Repo

It is the most ordinary GitHub repository, which only works with code and the goal is to write a program.

  • Initiation: you can create a Code-Repo directly with create new repository. Be sure to initiate with proper README, LICENSE (recommend MIT) and gitignore (choose your language) files.
  • Clone the repo to disk via Atom or Git bash.
  • Add label on GitHub: Code-repo.

Project Repo

It is a specially designed GitHub repository, which allows all team members have an online platform to share knowledge, issues, and ideas about a concrete scientific project.

  • Initiation: please follow this guide to initiate a Project-Repo via importing.
  • Link-to-Code-Repos: normally, a Project-Repo includes one or more Code-Repo. Therefore, you can add the link to the Code-Repos in the README file.
  • Add label on GitHub: Project-repo.

Warning

  • Please do not edit the repository names since it might corrupt links related to those repositories.

Import the template repository

  1. Click import new repository to start
  2. Enter the address of this repository (https://github.com/young24/Perfect-Lab-System) as Your old repository’s clone URL
  3. In the owner list, choose YOUR-ORGANIZATION.
  4. Specify the new repository as private
  5. Give a new name for your new repository
  6. If your project contains files larger than 100 MB, choose Include large files
  7. Finished. You get the same repository with only the master branch but with a new name.

See the official guide to learn more details.

TODO: rewrite this part completely.

Configure your cloud storage (Google Drive) locally

If you are a first-time user, please ask admin users to help you. Otherwise, it may cause troubles not only for you but your teammates.

  • Install Google Drive File Stream. Download from here. Please follow the installation instructions.
  • If there exists a sync-folder for the Project-repo, just sign him/her in.
  • Otherwise create a new sync folder
  • Don't forget to set up selective folders to sync with Google Drive. Only sync the folders References and Results.

Notices and warnings for users

  1. The above steps only need to be done once. No further modification is required in the future. Please do not rename folders "Code/Data/References/Results/System" or any file at the same level.
  2. DO NOT ADD ANY FILES/FOLDERS AT THE ROOT OF YOUR SYNC FOLDER, put the temporary files to the "Working" folder, files to the References folder and the Results folder to auto-sync with Nutstore.
  3. Except the Data, Working folders, DO NOT PUT ANY LARGE FILES (> 100 MB) IN ANY FOLDER

Manage GitHub teams and members

An admin user can view the organization by clicking "view organization" on dashboard.

  • On "People" label, admin users can change other members' roles, such as convert an ex-lab-member into a collaborater.
  • On "Teams" label, admin users can create/edit/remove teams. Check out this guide to learn how to remove a member from a team.
  • For an outside collaborater (a person from other lab), you can add him/her individually to the project repo he/she is responsible for.

However, do not create too many teams for research purposes. You should add worm-team or fish-team to a project repo instead creating a new team, because we are going to increase the chance for lab members to communicate with each other, not the opposite.

When people leave the lab

  • On GitHub
    • Convert them into outside collaborater
    • Remove them from the Administration repository
  • On Nutstore,
    • Be sure to transfer the ownership of their sync-folders to other lab members
    • Remove them from the team.

Advanced topics

Design principles

  • Project-based
    • If it is a general project (e.g., this project), we can build a Project-repo for it.
    • If it is a specific project (e.g., write a manuscript or a program), we can build a Code-repo for it.
    • However, please do not create a repository for adding a feature. A branch is enough to do that. See Minimal Principle for more details.
  • Minimal principle
    • If a section is enough for doing something, do not create a file (e.g., if you have a new solution formula, just add it to worm-guide/fish-guide)
    • If a file is enough for a task/function (e.g., a guide for learning sth), do not create a branch
    • If a branch is enough for a task/function (LTS/OBSOLETE branch)
    • If one repository is enough for organizing all the code, do not create more (e.g., do not create repositories for each part of a setup. Put them together. See All in one for more details)
  • All in one
    • One project, one sync folder, one GitHub Project-repo
      • Put code/data/references/results in the Code/Data/References/Results folder; put the else in the Working folder
    • Link every related resource as links, badges, or QRcode
  • Automation
    • Automate the repetitive and tedious processes and link the same item correspondences in different places automatically.
    • Track all the changes (details) when doing (Git tools) and upload them to the remote origin voluntarily.
    • Be sure to separate each module to keep them organized

Storage model

Storage-model

This storage model is for Project-repo and its corresponding local sync folder. (For a Code-repo, Git takes control of everything, no cloud sync involved.)

Since a Project-repo is designed as an online platform, we just use it online, not local usage for this type of repository.

There are two subfolders on GitHub: (.github means these folders are only used on GitHub)

  • .github/Images: save images that are rendered in GitHub Wiki
  • .github/Files: save files that are linked in GitHub Wiki; for files that larger than 10 MB, please put the files in Nutstore, then paste the links on GitHub

We use sync folders to handle local files that will be shared within a team. The name of the local sync folder should be exactly the same as the corresponding GitHub Project-repo. (For a Code-repo, do not create its sync folder counterpart since Git should take care of everything.)

There are five subfolders inside the sync folder:

  • Code folder: You can git clone other Code-repos at here. Since there is no Git control over the sync folder, be sure to put code files in a Code-repo. (If there is no Code-repo, create one for your code. You can name it as xx-analysis or xx-acquisition.)

  • Data folder: Put all experiment data and intermediate data in the Data folder. You have the option to auto-sync the data with our storage server. Ask admin users for more info.

  • References folder: Put literature and files that are not composed by your team are in the References folder. All the files in this folder will be synced via Nutstore with your teammates.

  • Results folder: Put the final results for publications such as manuscripts and figures in the Results folder. Do not put large data files (>100MB) in this folder since all the files in this folder will be synced via Nutstore with your teammates.

  • Working folder: Files in the Working folder would not be uploaded or synced with any other devices/services. This is where you put anything unfinished, such as your programs to generate raw data. Please remember to put finished files into the above folders to keep track of them.

Finally, this sync folder will be linked to the corresponding GitHub Project-repo as a badge in README.

Warnings!

  1. DO NOT ADD ANY FILES/FOLDERS AT THE ROOT OF YOUR SYNC FOLDER, put the temporary files to the "Working" folder, files to the References folder and the Results folder to auto-sync with Nutstore.
  2. Except the Data, Working folders, DO NOT PUT ANY LARGE FILES (> 100 MB) IN ANY FOLDER
  3. Please do not edit/rename/move/remove the configuration files again.

Limitations

  • Git cannot version-control binary files (e.g., .fig)
  • Cannot read the MS Office files on GitHub
  • No easy to upload photos to GitHub from the mobile
  • Not good for LabView code due to the merging issue, check out this guide to find a workaround

Instant communication

Everyone wants to get responses as soon as possible. However, an instant communication might put extra stress to people you ask for.

GitHub itself provides a way to communicate instantly among a team. In teams, you can set up an instant online meeting with other teammates. There are some alternatives: Gitter (A web-based online chatting app), Slack App (blocked in China), and Wechat.

Personally, I (Wenbin Yang) do not recommend too much instant communication, because it will cause extra pressure to people.

Real-time discussions on the mobile

  • Gitter
    • Pros: use markdown to talk, and directly links to GitHub issues
    • Cons: cannot upload photos
  • Slack
    • Pros: have integrations with GitHub, a great platform with extensibility
    • Cons: blocked in China
  • Wechat
    • Pros: People in China use it a lot.
    • Cons: No good APIs available. Affect people's leisure time.

Make Git better

GitHub is born for source code; however, with proper configuration of gitignore, gitattributes files, and git LFS, people can handle other files type (e.g., Office files) as good as well.

Commonly used Git commands

  • git clone GITHUB_URL: clone down a remote GitHub repo to the local, replace GITHUB_URL with the repo url you want to clone
  • git pull: pull down updates on GitHub to the local
  • git add .: add every change (editing/deleting/addings) to Git
  • git commit -m "describe what you did": commit all the changes to the local branch
  • git push: push up local updates to GitHub
  • git branch BRANCH_NAME: create a new branch, replace BRANCH_NAME with your branch name
  • git checkout BRANCH_NAME: change the current branch to the branch BRANCH_NAME
  • git submodule add GITHUB_URL: add a repository as a submodule in another , replace GITHUB_URL with the repo url you want to clone

See more at the official Git docs.

Save GitHub credentials

Please see this guide to start.

Large files storage

GitHub will warn you when pushing files larger than 50 MB. You will not be allowed to push files larger than 100 MB. work with large files

There is a service called LFS which natively works with Git. There is an instruction on how to use the own server to store large files: Configuration of a server for git-lfs

Git ftp

This may fit our purpose better. Git-ftp step-by-step tutorial of installing the git-ftp all code format, e.g. c++, MATLAB, LabView

gitignore

Exclude large files such as video files, tiff images with git-ignore files. Check this link.

Using the following command to exclude files larger than 1 G find . -size +1G | cat >> .gitignore

gitattributes configuration

Check this link.

Git on MS Office files

This tutorial might be helpful to deal with the MS Office.

Git works fine with Pandoc. However, people cannot directly see the content of the MS Word from the Github website. So it's better to use markdown instead. Another alternative is to open the link to file with external applications.

Rights and responsibilies

As an admin user, you have to know your rights and responsibilies to help lab members and avoid irreversible mistakes.

Rights

  • Full access and control of all Wenlab GitHub repositories and teams
  • Admin control of Wenlab Nutstore member/storage management
  • Better chance to learn more knowledge about Git, GitHub, HTML, and more cutting-edge knowledge about the Web-based technologies and management

Responsibilies

  • Help other lab members implement Perfect-Lab-System for their projects
  • Help others get started with Perfect-Lab-System
  • Help organize wikis on all repos (make wikis more structural)
  • Help organize GitHub Wenlab teams
  • Manage lab members accessibility to Wenlab GitHub repositories and Nutstore

Contributing

Contributions are welcome! Please add issues and make pull requests. There are no stupid questions. All ideas are welcome. This is an experimental project. Be excellent to each other.

Clone this wiki locally