Working in Team: From Basic to Professional GitHub

Capstone Design

Imron Rosyadi

Collaborative Workflow for ECE Software Projects

This deck is designed to walk students from “I can push to GitHub” to “I can work like an engineer using pull requests and reviews.”

Emphasize that they probably already know some basics, but the goal is professional habits: branches, PRs, reviews, and protected main.

Learning Objectives

By the end of this session, you will be able to:

1. Set up and configure your GitHub account and local tools.
2. Clone a team repository and work locally using VS Code.
3. Commit and push changes so your team can see your work.
4. Explain why professional teams use branches, pull requests, and protected main.
5. Create a feature branch, open a Pull Request (PR), review code, and handle merge conflicts.

Read the objectives, but focus especially on the last two: this is where we move from “student GitHub” to “professional GitHub.”

Tie back to ECE context: firmware repos, FPGA projects, data-processing pipelines all use these same workflows.

Big Picture: How Teams Use GitHub

• GitHub is more than file storage; it’s a collaboration platform.
• Your team works in a shared Organization with a shared repository.
• Each of you:
  • Works on your local copy.
  • Sends changes back to the remote repo.
  • Uses pull requests to get code reviewed before it reaches main.

Highlight the “remote repo ↔︎ local clone” idea and the flow into PRs and then into main.

Mention that this diagram is exactly what professional ECE/embedded teams use for firmware, HDL, signal processing libraries, etc.

1. Setting Up Your GitHub Account

Before writing code, you need a GitHub identity.

• Go to https://github.com and click Sign up.
• Use your student email address if possible:
  • May unlock the GitHub Student Developer Pack (free tools and credits).
• Verify your email.
• Turn on Two-Factor Authentication (2FA) for security.
• Action: Share your GitHub username with your instructor.

Important

Why 2FA matters for engineers

Losing access to your GitHub is like losing access to your lab notebook, code, and design files at once. 2FA is required in many companies and research labs.

Mention that many organizations now require 2FA to even be added as a collaborator.

If time allows, quickly show where to enable 2FA in GitHub settings.

2. Installing Your Toolkit

To work efficiently, install these three tools:

Tool	Purpose
Git	Version control engine tracking changes to your code.
GitHub Desktop	GUI to manage repositories without the command line.
VS Code	Editor/IDE where you write and edit code.

1. Download Git: https://git-scm.com/ (accept defaults).
2. Download GitHub Desktop: https://desktop.github.com/.
3. Download VS Code: https://code.visualstudio.com/.

Clarify:

• Git is the underlying tool.
• GitHub is a hosting service on top of Git.
• GitHub Desktop uses Git under the hood but is friendlier when you are starting.

ECE angle: Same tools are used for C/C++, Python, Verilog, MATLAB scripts (via plugins), etc.

3. Getting Into the Organization and Team Repo

Once your instructor adds you to the GitHub Organization:

• Accept the email / in‑GitHub invitation.
• Go to the Organization’s main page.
• Find your team repository, e.g., Team-A-Project.
• Click the green Code button.
• Select Open with GitHub Desktop.

Tip

If “Open with GitHub Desktop” doesn’t appear, first install GitHub Desktop and sign in with the same GitHub account.

Explain what an “Organization” is on GitHub: a container for multiple repos, access control, teams.

Relate it to a company’s engineering org or a research lab’s shared GitHub.

4. Cloning: Getting a Local Copy

When you “Open with GitHub Desktop,” it will ask: Where should I save this?

• This process is called cloning.
• Choose a folder you’ll remember, e.g., Documents/GitHub/Team-A-Project.
• Click Clone.

Conceptual View

• Remote repository: lives on GitHub servers.
• Local clone: full copy on your laptop.
• You always edit the local copy, then sync with the remote.

Stress: never treat GitHub as a Google Docs editor for code. Edit locally in a proper editor.

Mention that cloning includes full history, not just latest files.

5. Opening the Project in VS Code

With the repo cloned:

• In GitHub Desktop, select your repository.
• Click Open in Visual Studio Code.
• VS Code opens directly in the project folder.

Inside VS Code:

• Left sidebar shows Explorer with project files.
• Click a file to open it.
• Create new files as needed (e.g., index.html, script.js, main.c, filter.py).
• Save frequently: Ctrl+S (Windows/Linux) or Cmd+S (macOS).

Warning

Git only tracks saved changes. If you forget to save, your work is not in the next commit.

Demonstrate making a trivial change: add a comment line in a file and hit save.

ECE example: show a simple C file with a comment // TODO: read ADC value.

6. Local Changes → Commit → Push

Once you’ve completed a small task or feature:

1. Switch to GitHub Desktop.
   • You’ll see a list of changed files.
2. Write a Commit Message (bottom left).
   • Example: Add UART initialization or Fix FFT windowing bug.
3. Click Commit to main (or current branch).
   • This saves a snapshot in your local repo.
4. Click Push origin (top).
   • This uploads your commit(s) to the GitHub remote.

Note

Think of a commit as a checkpoint in your lab notebook. Push sends that checkpoint to the shared notebook on GitHub.

Emphasize small, meaningful commits.

Give examples:

• Bad: stuff or changes.
• Good: Implement debounce for button input or Refactor ADC driver into module.

7. Pulling Your Teammates’ Work

You are not working alone. Before you start each session:

• Open GitHub Desktop.
• Click Fetch origin.
• If new commits exist on GitHub, click Pull.

This updates your local files with your teammates’ latest work.

Important

Pull before you start coding each day. This reduces merge conflicts and keeps everyone aligned.

Use analogy: pulling is like syncing your local lab notes with the shared notebook before you take new measurements.

If students skip pulling, they’re effectively writing on an old copy of the design.

8. From “Student GitHub” to “Professional GitHub”

So far: you can clone, edit, commit, push, and pull.

In many student projects:

• Everyone has Write access to main.
• Every push goes directly into main.

In professional teams:

• main is often protected.
• You cannot push directly to main.
• You work in branches and use Pull Requests (PRs).

Tip

You can already start using this professional model in class projects, even if GitHub doesn’t force it. Just agree as a team to use branches + PRs.

Explain why:

• Protects production code (e.g., firmware released to hardware in the field).
• Ensures someone else reviews your design or fix.

9. Protected Branches: Guarding main

A protected branch (usually main):

• Rejects direct pushes.
• Requires all changes to go through a Pull Request.
• Can require:
  • At least N approvals.
  • Status checks (e.g., automated tests) to pass.

Important

On real engineering teams, main often represents production code:

• Deployed firmware.
• FPGA bitstreams.
• Released software versions.

In class, “production” might be the version that passes all tests and demos.

If instructor configures protected branches, students will experience real-world workflow.

10. Branches: Working on Features Safely

Instead of pushing to main:

• Create a feature branch for each task.
• Name it clearly, e.g.:
  • feature-login-ui
  • bugfix-adc-saturation
  • lab3-filter-implementation

Typical workflow:

1. Start from up‑to‑date main.
2. Create a new branch.
3. Commit changes into your branch.
4. Push your branch to GitHub.
5. Open a Pull Request from your branch into main.

Relate branches to ECE:

• One branch per hardware revision, or per feature like “add SPI peripheral,” “implement PWM control,” etc.

Point out that branches keep unfinished work from breaking the “known good” main.

11. Creating a Branch (GitHub Desktop)

In GitHub Desktop:

1. Make sure you’ve pulled the latest main.
2. Click Current Branch → New Branch.
3. Enter a descriptive name, e.g., feature-sensor-readout.
4. Base it on main.
5. Click Create Branch.

You’re now on that branch:

• Changes and commits belong to feature-sensor-readout.

Tip

Include your initials or issue number if helpful: feature-sensor-readout-az or issue-42-sensor-calibration.

Demonstrate creating a branch live if possible.

Explain that branches are cheap: don’t be afraid to create many small ones.

12. Making and Committing Changes on Your Branch

On your feature branch:

• Open the repo in VS Code.
• Implement your change:
  • Example: add a new module sensor.c and sensor.h.
  • Or modify main.py to add plotting.
• Save your files.

Then in GitHub Desktop:

• Confirm you are still on your feature branch.
• Review the list of changed files.
• Write a descriptive commit message.
• Click Commit to <your-branch>.
• Click Push origin to push the branch to GitHub.

Reinforce: commits still work the same on a branch—only the destination differs.

ECE analogy: a branch is a separate test setup on your lab bench; commits are snapshots of tests.

13. Opening a Pull Request (PR)

Once your feature is ready:

1. Go to GitHub in your browser.
2. Navigate to your team repository.
3. GitHub often shows a banner:
   • “Compare & pull request” for your recently pushed branch.
4. Click New pull request if needed.
5. Set:
   • Base branch: main (or the protected branch).
   • Compare branch: your feature branch (e.g., feature-sensor-readout).
6. Write a clear title and description:
   • Title: Add temperature sensor readout.
   • Description: what changed, why, any test results.

Note

A PR is a request for review, not just a “merge button.”

Show a screenshot or live demo if possible.

Mention including links to requirements, issues, or diagrams in PR description.

14. Who Reviews Your PR?

In a three-person team:

• Authors: the person who wrote the code opens the PR.
• Reviewers: usually the other two teammates.
• In some courses:
  • Instructor or TA may also act as a maintainer.

GitHub settings can:

• Require 1 or 2 approvals before merging.
• Block self-approval (you cannot approve your own PR).

Important

Cultural rule used by many teams: > “No one merges their own code without review.”

Connect to industry:

• Many companies make code review mandatory for safety, reliability, and maintainability (especially in embedded and controls).

15. Review and Acceptance Flow

Detailed steps:

1. Student A pushes feature-login.
2. Student A opens PR → target main.
3. Students B and C review:
   • Comment on code, request changes, or approve.
4. When approvals + checks are satisfied, Merge button turns green.
5. A maintainer (or the author, if allowed) clicks Confirm merge.

Highlight that review is not punishment—it’s collaboration.

Encourage constructive comments: “Can we rename this variable?” “What happens if sensor data is out of range?”

ECE tie‑in: helps catch edge cases in control logic, timing, or numeric overflow.

16. What Reviewers Actually Do

Reviewers should:

• Read the PR description.
• Scan the files changed tab.
• Check for:
  • Logic bugs.
  • Style consistency (naming, formatting).
  • Missing tests or documentation.
  • Safety issues (e.g., unbounded loops, unchecked I/O).
• Use comments to ask questions or suggest improvements.

Common GitHub review actions:

• Comment — leave general or line‑specific feedback.
• Request changes — PR must be updated before approval.
• Approve — PR is ready to merge.

Tip

As a reviewer, try to understand the intent: “If I had to maintain this code later, would I understand what it does?”

Mention that in embedded/ECE work, code review also checks for timing assumptions, power constraints, and hardware interactions.

Encourage students to rotate who reviews whose code to learn from each other.

17. Merging the PR

After approvals:

• The PR status will show all required checks green.
• The Merge button becomes active.
• Click Merge pull request → Confirm merge.

Result:

• The feature branch code is combined into main.
• main now has the new functionality.
• Optionally, delete the feature branch to keep things tidy.

Note: some teams also use “Squash and merge” to combine all branch commits into one commit on main. You can mention but don’t need to go deep for this class.

18. Handling Merge Conflicts

Conflicts happen when:

• Two people edit the same line of a file in different ways.
• Git cannot automatically decide which version to keep.

GitHub will:

• Block the merge.
• Mark the PR as having conflicts.

The person attempting to merge must:

1. Pull the latest main.
2. Merge main into their feature branch locally.
3. Resolve conflicts in affected files (choose/merge code).
4. Commit the resolved changes.
5. Push the updated branch.

Warning

Ignoring conflicts is not an option—Git will not merge until they are resolved.

Show a simple example of a conflicting line in a text file if time permits.

Reassure students that conflicts are normal; the goal is to learn not to panic, but to read and resolve them carefully.

19. Example Scenario: Team of Three

Let’s walk through a complete cycle:

• Student A: implements “login” feature on feature-login.
• Student B: implements “dashboard” on feature-dashboard.
• Student C: fixes “sensor bug” on bugfix-sensor.

Each student:

1. Pulls latest main.
2. Creates a new branch.
3. Commits and pushes their work.
4. Opens a PR into main.
5. Reviews at least one teammate’s PR.

Question for students: How would you decide who reviews which PR to balance workload?

Use this scenario for an in‑class activity:

• Assign roles and ask them to sketch out the branches and PRs on paper or a whiteboard.

20. Real-World ECE Application Example

Imagine your team is building a signal acquisition and processing pipeline:

• One student works on ADC driver (branch feature-adc-driver).
• Another on DSP filter (branch feature-dsp-filter).
• Another on data logger (branch feature-logging).

Professional workflow:

• Each feature in its own branch.
• PR for each feature.
• Team reviews each PR for:
  • Sampling rate assumptions.
  • Overflow/underflow in fixed‑point math.
  • Correct interface between modules.

Protecting main ensures:

• The version running on actual hardware is always tested and reviewed.

Connect to safety-critical or high‑reliability systems (medical, automotive).

In such domains, unreviewed changes can have serious consequences; hence PRs and approvals are mandatory.

21. “Best Practice” Rule for Your Team

Even if your instructor allows direct pushes to main, adopt this team rule:

No one merges their own code into main without at least one teammate’s review.

This helps you:

• Catch bugs early.
• Share knowledge of each part of the codebase.
• Practice professional workflows you’ll use in internships and jobs.

Tip

Write this rule in your repository’s README.md as part of your team contract.

Encourage students to treat this like any lab safety rule—simple, but very effective.

Mention that many companies literally have the same policy written down.

22. Quick Practice Checklist

Before next lab, try this with your team:

1. Ensure everyone can:
   • Sign in to GitHub.
   • Access the Organization and team repo.
2. Each person:
   • Creates a personal branch.
   • Makes a small change (e.g., add your name to a TEAM.md file).
   • Commits and pushes.
   • Opens a PR into main.
3. Pair up and review each other’s PRs.
4. Merge the PRs and pull the new main.

This is a low-stakes way to practice the whole pipeline before you apply it to real lab code.

Ask them to note anything confusing in the process to discuss in the next session.

Summary / Key Points

• You work within a GitHub Organization and a shared team repository.
• Use Git, GitHub Desktop, and VS Code to:
  • Clone the repo, edit locally, commit, and push.
• Always pull before starting work to sync with your teammates.
• Professional workflows rely on:
  • Protected main branches.
  • Feature branches for changes.
  • Pull Requests for review and controlled merges.
• In a PR workflow:
  • Authors push to branches and open PRs.
  • Reviewers approve or request changes.
  • Conflicts must be resolved before merging.
• Adopting “no self‑merge to main” prepares you for real engineering teams.

Encourage students to view GitHub not just as a submission system, but as their professional engineering collaboration tool.

Invite questions specifically about any step in the PR flow or about how this maps to their ongoing lab projects.