# COMP523/S26

Hi all,

My name is Louie, and I am your TA for COMP523. I have served as a TA for this course in F23, S25, and F25; this is my fourth semester in this position.

My goal is to **help you succeed in this course** and **remove obstacles** for you. I want every team to successfully deliver a high-quality project to their client by the end of the semester.

## What I Want You To Know

### 1. Time Management

We have approximately 12 weeks to work on the project. This is not a lot of time when you account for holidays, midterms, finals, and job interviews.

I understand you have other commitments, but please manage your time effectively from day one.

### 2. Team Dynamics & Contributions

Please let me know **immediately** if you see significant contribution imbalances (free-riding) within your team.

If you wait until the last 2 or 3 weeks of the semester to report an issue, it is too late for me to intervene.

Early communication allows us to remove obstacles and get the team back on track.

### 3. AI Usage Policy

You are strongly encouraged to use AI tools to assist with your project (e.g., coding assistance, debugging, iteration).

However, you MUST NOT generate written deliverables or assignments directly from AI tools/LLMs without significant human revision and oversight.

See:

* Guidance on Generative AI Use: https://handbook.unc.edu/generativeai.html
* Generative AI Resources for Learning: https://ai.unc.edu/learning/
* UNC Honor Code: https://studentconduct.unc.edu/

### 4. Reference Project Websites

You may review project websites from previous semesters to understand the expected format:

* F25: https://www.cs.unc.edu/~stotts/COMP523-f25
* S25: https://www.cs.unc.edu/~stotts/COMP523-s25
* S23: https://www.cs.unc.edu/~stotts/COMP523-s23

## Grading & Assessment

### COMP523 Manager Form

* For each meeting, I will record the following metrics:
* Attendance
* Web journal updates
* Achievement of the weekly plan
* Plan for the upcoming week
* Demo status (Gave a demo? Did it work?)
* Deliverable status (On the web? Changes made?)

### Final Report

At the end of the semester, I will submit a holistic report for each team to the Professor.

This report evaluates your progress throughout the semester, i.e. teams that make consistent progress will be rated more favorably than teams that rush to generate content in the final week.

I will assess the final product on the following scale:

* A: Excellent project, all things considered.
* B: Good to very good, considering the circumstances.
* C: Could have done better, but didn't.

Note: While I provide these evaluations, the final grade is determined by the Professor.

## Semester Requirements

For this semester, I am enforcing the following technical standards to ensure project maintainability.

## Bi-weekly Meeting

This semester, we are piloting a bi-weekly meeting schedule (meeting zoom every two weeks). However, to ensure steady progress, reporting remains weekly.

### Reporting Requirements

Every week (regardless of whether we have a meeting), you MUST complete the following by 11:59 PM on the day before your regularly scheduled meeting slot:

1. Update the Project Website: Post a concise progress report following the PPP Format:
* **Progress (What happened)**: Specific tasks completed and deliverables finished. Crucial: Also list what you tried but failed at (e.g., Tried JWT auth but stuck on token refresh).
* **Plans (What is next)**: Specific goals you commit to finishing by next week.
* **Problems (Where you are stuck)**: Any blockers, bugs, or external issues (e.g., waiting on client feedback) hindering your progress. (If you have no problems, state None).
2. Send Confirmation: Send me an email with link to notifying me that the website has been updated.

## Project Website

### Hosting Preference:

1. TarHeels.live: https://web.unc.edu/
1. Google Sites: https://sites.google.com
1. Others

Tech stack is not a problem, but you MUST make sure that the project website will still exist after the course eneded.

### Naming Convention of the Handler in TarHeels.live

Please use the following naming format:

Team[Your Team Alphabet]COMP523S26

For example, if I am Team T, the handler of my project website should be:

TeamTCOMP523S26

## Version Control (Git)

You MUST use Git to manage your code repository.

### Hosting Preference

1. GitHub
2. Bitbucket
3. GitLab

Again, Git hosting is not a problem, but you MUST make sure that the code repository will still exist after the course eneded.

### Branching Strategy

You are required to use the Gitflow workflow (or a similarly structured branching strategy).

See how Gitflow workflow works: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow

### Git Commit Messages

You must maintain consistent and meaningful Git commit messages. Choose a style guide and strictly adhere to it.

* [How to Write a Git Commit Message](https://cbea.ms/git-commit/)
* [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)

Note: If you use AI to generate commit messages, you must verify they are accurate and match your chosen style.

### Git hooks

You are required to use Git hooks (e.g., pre-commit) to enforce at least:

1. Commit message style checks.
2. Coding style/linting checks.

Use [pre-commit](https://pre-commit.com/) or equivelet templates to do this. DO NOT use AI/LLM to enforce this, see:

* https://pre-commit.com/
* https://www.atlassian.com/git/tutorials/git-hooks
* Examples:
* Education case: https://github.com/sysprog21/lab0-c/blob/master/scripts/pre-commit.hook
* Industry case: https://github.com/commaai/openpilot/blob/master/.pre-commit-config.yaml

#### Coding Style

* Select an auto formatter
* clang-format
* python-black
* eslint
* ...
* Enforce it via Git hook or editor settings (format on save).

### Git commands

Learn Git commands.

* https://learngitbranching.js.org/
* http://onlywei.github.io/explain-git-with-d3/

### Git Commit General Tips

* Make commits as atomic (focused on one task) as possible.
* NEVER commit secret credentials (API keys, passwords).

## Project Tracking

You **MUST** use Kanban to manage your project progress. (Or other agile method learn from the course).

See:

* https://www.atlassian.com/agile/kanban

Tip: If using GitHub, the "Projects" tab has a built-in Kanban template.

## The Computer Scientist as Toolsmith

By Fred Brooks: https://www.cs.unc.edu/~brooks/Toolsmith-CACM.pdf

Two of our criteria for success in a tool are:
* It must be so easy to use that a full professor can
use it, and
* It must be so productive that full professors will use it.

## AI Tools

In this semester, you MUST use AI tools as much as you can to assist you and your team.

* Anthropic Claude
* Google Gemini
* OpenAI ChatGPT
* Microsoft Copilot from UNC

And make sure that you:

1. Review the code from it (not just copy/paste)
2. DO NOT leak sensitive information to LLMs (e.g. personal info, business secret, HIPPA-related info)