Tutorial GitHub Onboarding & Project Management - CHI-CityTech/StudentResearch GitHub Wiki
CHI GitHub Onboarding & Project Management Tutorial
Introduction
Welcome to the CHI-CityTech GitHub Onboarding & Project Management Tutorial. This guide will walk you through the process of setting up and managing your work in the CHI-CityTech GitHub Organization, ensuring smooth collaboration and efficient tracking of tasks.
Purpose of This Guide
This tutorial is designed to help CHI team members:
- Onboard onto GitHub and gain access to the necessary repositories.
- Understand the CHI GitHub structure and how different repositories support various projects.
- Set up Issue Templates to standardize weekly reports and task assignments.
- Use GitHub Issues and Projects for effective task tracking and progress updates.
- Collaborate through GitHub Discussions and the Wiki for knowledge sharing and documentation.
- Follow best practices for branching, committing changes, and making Pull Requests.
- Explore automation opportunities such as email-to-Issue creation for easier task management.
What’s in This Document?
| Section | Description |
|---|---|
| 1. What is GitHub? | Overview of GitHub and the components we will be using |
| 2. Understanding the CHI GitHub Structure | Overview of repositories and their roles in BSP projects. |
| 3. Getting Started with GitHub | Step-by-step guide to creating an account and joining the CHI-CityTech organization. |
| 4. Creating Custom Issue Templates | Instructions for setting up Weekly Report and Task templates for consistency. |
| 5. Managing Tasks with GitHub Projects | How to create Issues, track progress, and use Project Boards effectively. |
| 6. Using GitHub Discussions & Wiki | How to participate in discussions and document work in the Wiki. |
| 7. Final Thoughts & Next Steps | Checklist for onboarding completion and future integration efforts. |
By the end of this tutorial, you’ll be equipped with the essential skills to navigate, contribute, and manage your work within the BSP GitHub environment. 🚀
1. What is GitHub?
GitHub is a platform for version control and collaboration, primarily used for managing code, but also widely applied in research, documentation, and project management.
Key Features of GitHub
- Version Control: GitHub allows teams to track changes to files over time, preventing data loss and enabling collaboration.
- Collaboration: Multiple contributors can work on the same project simultaneously, with structured workflows to integrate their contributions.
- Project Management: GitHub includes tools like Issues, Pull Requests, and Projects to help teams organize and track their work.
- Documentation & Knowledge Sharing: GitHub Wikis and Discussions provide structured spaces for recording and exchanging information.
- Automation & Integration: GitHub can connect with external tools and services, automating workflows and enhancing productivity.
GitHub is widely used in software development, research, education, and digital content creation. In the BSP Project, we use GitHub as a central hub for managing work, tracking progress, and collaborating on documentation and creative assets.
Key GitHub Components Used in BSP
Before diving in, here’s a quick overview of the GitHub components we’ll be using in the BSP project:
GitHub Components & Basic Actions
GitHub Components
| GitHub Component | Description |
|---|---|
| Team | A group of organization members with shared permissions for collaboration on repositories, projects, and discussions. |
| Repository | A storage space for project files, code, and documentation. Repositories are organized by Activity. Each repository contains Issues, Branches, and Project tracking. |
| Project | A management tool used to track Issues and organize workflow. Each person or team will have their own Project. |
| Issue | A task, assignment, or other "to-do" associated with a specific repository that can be assigned to one or more individuals. Issues and progress are tracked within the appropriate Project. |
| Branch | A separate version of a repository used for making changes safely. This allows each person to work independently and merge changes when ready. |
| Discussion | A forum-like space for brainstorming, Q&A, and team-wide communication. |
| Wiki | A structured documentation area for storing project knowledge and guidelines. |
Basic GitHub Actions
| GitHub Action | Description |
|---|---|
| Create a Branch | Creates a separate version of the repository for working on changes without affecting the main version. |
| Commit a Change | Saves changes with a historical record, allowing for version tracking and restoration if needed. |
| Push a Change | Uploads local changes to GitHub, updating the repository with new commits. |
| Make a Pull Request (PR) | Proposes merging changes from one branch into another for review and approval. |
| Create an Issue | Logs a new task, assignment, or discussion item in a repository for tracking progress. |
Repositories
A repository (repo) is a storage space for code, documents, and project files.
- Each CHI repository houses materials for a specific project (e.g., Blended Reality Performance, Shadow Puppet Unreal).
- Files and folders are structured to allow version control and team collaboration.
- CHI team members will use one or more repositories for their research and project activities.
- A list of repositories can be found on the CHI repository page.
- More specific information about the repository structure and active repositories can be found on the .github README.
GitHub Projects
A GitHub Project is a code sharing and project management tool used for tracking Issues and managing workflow.
- The tool has multiple views, allowing for different types of visualization.
- The primary view will be a Kanban-style task board
- BSP team members will use GitHub Projects to organize tasks and monitor progress.
- Tasks are represented as Issues, which move through different project stages (
To Do,In Progress,Completed). - Each member will be assigned to a separate project (or a team project, with multiple people).
Issues
An Issue is a task, bug report, or discussion item within a repository.
- Each weekly report and task assignment will be created as an Issue.
- Issues can be labeled, assigned to team members, and added to a Project Board.
Branches
A GitHub repository may be used by many people. Because of this, it is possible for someone to overwrite another's work. For this reason we use separate branches, and is one of the more powerful Git features.
A branch is a separate version of a repository used to make changes without affecting the main version.
- Team members will create branches to work on new features or documentation.
- Once changes are finalized, they are merged back into the main branch using a Pull Request.
Commits
A commit is a snapshot of the repository at a specific point in time.
- Each time you make a change and save it, you create a commit.
- Commits should have clear messages explaining what was changed.
Pull Requests (PRs)
A Pull Request (PR) is used to propose changes made in a branch before merging them into the main branch.
- PRs allow team members to review and discuss changes before they become part of the repository.
Discussions
GitHub Discussions provide a forum-style space for open conversations.
- Used for brainstorming, project updates, and general questions.
- Unlike Issues, Discussions are not tied to a specific task or problem.
Wiki
The GitHub Wiki is a structured documentation space where teams can store information, research findings, and guidelines.
- Each BSP project will maintain a Wiki for easy access to project knowledge.
- The Wiki is different from the repository,and is intended to store final information, guidelines, system documentation, etc.
2. Understanding the CHI GitHub Structure
The CHI_CityTech GitHub Organization serves as the central hub for BSP and related projects. Each team member will contribute to repositories using a structured workflow involving Issues, Branches, Commits, and Pull Requests.
Key CHI & BSP Repositories
Blended Shadow Puppet & Performance Projects
| Repository | Description |
|---|---|
| Blended Shadow Puppet | The BSP meta-project integrating shadow puppetry with modern technology. |
| Blended Shadow Puppet Theatre | Theatrical-specific repository for BSP, including documentation and production assets. |
| Blended Reality Performance System | Modular system exploring Balanced Blended Space in performing arts. |
| Shadow Puppet Unreal | Unreal Engine-based BSP simulations for virtual world integration. |
| Unity BSP | Unity-based implementation for BSP projects. |
CHI Meta-Projects & Administration
| Repository | Description |
|---|---|
| Balanced Blended Space | Universal framework for integrating physical, virtual, and conceptual spaces. |
| CHIIDS | Center for Holistic Integration’s Integrated Digital System. |
| CHI-Admin | Administrative repository for CHI projects. |
| CHI-Branding | Graphics and branding materials for CHI and related projects. |
| CHI-CityTech.github.io | CHI organization website. |
Research, Anti-Hate Initiative, & Quantum Music
| Repository | Description |
|---|---|
| Student Research | Repository for student research proposals and activities. |
| Anti-Hate | City Tech’s contribution to the CUNY Anti-Hate campaign. |
| Quantum Music | Exploring quantum computing in musical composition. |
Support & Storage Repositories
| Repository | Description |
|---|---|
| BSP Graphic Imagery | Storage for graphic images used in various BSP projects. |
| .github | Repository for organization-wide settings and templates. |
3. Getting Started with GitHub
✅ Goal: Ensure all BSP team members have GitHub accounts and access to the CHI_CityTech organization.
Step 1: Create a GitHub Account
- Sign up at GitHub if you don’t already have an account.
- Set up two-factor authentication for security (recommended).
- Choose a professional username aligned with your real name.
- Provide your username to the BSP team lead for repository access.
Step 2: Join the CHI_CityTech GitHub Organization
- Accept your invitation via email.
- Navigate to CHI_CityTech on GitHub.
- Locate and access your assigned repositories.
4. Creating Custom Issue Templates
✅ Goal: Standardize task reporting and project updates through custom Issue templates.
Step 1: Create an Issue Template Directory
- Navigate to your repository.
- Go to the .github folder (create it if it doesn’t exist).
- Inside
.github, create a new folder namedISSUE_TEMPLATE.
Step 2: Create a Weekly Report Template
- Inside
ISSUE_TEMPLATE, create a new file namedweekly_report.md. - Add the following Markdown template:
--- name: "Weekly Report" about: "Weekly progress report for BSP team members." title: "[Weekly Report] - Your Name - YYYY/MM/DD" labels: ["Weekly Report"] assignees: ["@your-username"] --- ## **Weekly Progress Report** **Team Member:** @your-username **Week of:** YYYY/MM/DD ### **1. What did you work on this week?** - [ ] Task 1 - [ ] Task 2 ### **2. What challenges did you face?** - List any blockers or issues. ### **3. What are your goals for next week?** - List upcoming tasks.