Working with GitHub: From an idea to a change you can explain

Once you start building with AI, producing changes can get surprisingly easy. Keeping track of what changed, why it changed, and whether it actually helped takes more attention.

You’ve probably already experienced some version of this: the app worked, you asked for one improvement, and now several other things are different. Some might even be better! But you’d like to know what happened.

GitHub gives us a way to make that work visible and manageable. It can also connect the entrepreneurial side of your project—questions, interviews, experiments, decisions—to the technical work those activities inform.

By the end of this lesson, you should be able to:

Organize venture work and technical work in the same project.
Break a larger outcome into manageable issues.
Explain the relationship between branches, commits, pull requests, and merges.
Review an AI-assisted change before accepting it.
Leave a record that helps you or someone else continue the work.

We’ll start with organizing the work, follow one change through the development process, and then practice with your project.

1. Give the work a home

Git tracks changes to files over time. GitHub hosts repositories and adds tools for coordinating, discussing, and reviewing work.

A repository, or repo, contains your project’s tracked files and their history. Alongside those files, GitHub provides issues and pull requests.

For our purposes, start with one repository per venture and a simple GitHub Project board. That gives you a place to connect what you’re learning with what you’re building.

Here are the pieces we’ll use:

Piece	What it helps you answer
Issue	What work needs to happen, and how will we know it’s finished?
Label	What kind of work is this?
Epic / parent issue	What larger outcome does this work support?
Project status	Where does the work stand?
Milestone	Which sprint or target does it belong to?
Project view	Which part of the work do I want to see right now?

You don’t need an elaborate system to begin. A few useful distinctions, applied consistently, will get you a long way.

2. Use issues for work you can act on

An issue can describe a bug, a feature, a customer interview, a marketing experiment, or a decision that needs evidence.

“Work on marketing” leaves quite a bit to the imagination. “Test whether a parent referral produces consultation requests” gives you something to investigate.

A useful issue explains:

Purpose: What problem or question are you addressing?
Action: What will you do?
Completion: What observable result or record will tell you the task is finished?
Ownership: Who is responsible for moving it forward?

For example, here’s a hypothetical venture issue:

Title: Observe how three people choose a restaurant

Purpose: We need to understand where dinner decisions get stuck before choosing which part of the experience to improve.

Action: Ask three reachable participants to walk through a real dinner decision. Record their options, constraints, current tools, and points of hesitation.

Done when: We’ve recorded the observations, identified a pattern or meaningful differences, and explained what we’ll test next.

Three participants is a manageable example, not evidence about an entire market. The value comes from what you observe and how carefully you interpret it.

A code issue needs similarly concrete completion criteria:

Title: Let a diner filter restaurant cards by price

Done when: Choosing a price range updates the displayed cards correctly, clearing the filter restores them, and an empty result explains what happened.

Those completion criteria are often called acceptance criteria. They give you something to check beyond “the AI says it’s done.”

Keep small steps as a checklist inside an issue. Make a separate issue when a piece of work needs its own owner, discussion, or completion decision.

3. Separate venture and code work with labels

Start with two labels:

track:venture — discovery, customer tests, pricing, outreach, operations, and business decisions.
track:code — software changes, bugs, integrations, and technical tests.

These are naming conventions we’re choosing. GitHub doesn’t give the word track special powers.

For individual tasks, choose the primary track. If an issue includes both interviewing customers and implementing a feature, it probably deserves to become two linked issues.

Labels categorize work and make it filterable. GitHub’s label guide explains how to create and apply them.

In your Project board, use a short status sequence:

Backlog → Ready → In progress → Done

“Ready” means the task is clear enough to begin. Keep “In progress” honest; putting twelve things there won’t give you twelve pairs of hands.

Create views for Venture, Development, and Current sprint. Views show different slices of the same work, so you don’t need to duplicate issues. GitHub’s view guide covers those filters.

If your repository belongs to an organization, you may also see issue types, such as Task, Bug, and Feature. Those can coexist with track labels: an issue might be a Bug with track:code. There’s no need to add a second label that repeats the type. GitHub’s issue-type guide explains the organization-level setup.

4. Use an epic when the outcome needs several issues

An epic is a larger piece of work that needs to be broken into smaller pieces. For this class, represent it as a parent issue, with related issues attached as sub-issues.

A label such as epic makes it easy to recognize. The parent/sub-issue relationship is what actually groups the work. GitHub supports creating new sub-issues or attaching existing ones. Sub-issue guide

Consider this hypothetical parent issue:

Epic: Determine whether a small restaurant-selection tool helps people choose dinner

Sub-issue	Track
Observe people’s current decision process	Venture
Assemble a small set of restaurant options for the experiment	Venture
Build a basic card-selection interaction	Code
Fix a problem that prevents someone from finishing the task	Code
Observe people using the tool and compare with their current approach	Venture
Summarize the evidence and choose the next step	Venture

The parent issue should explain the intended outcome and what would count as completing the investigation. It can span both tracks; the child issues provide the separation.

A few useful boundaries:

Start with one parent level and small, actionable children.
Use an epic when grouping helps you make sense of several tasks.
Keep unrelated goals in separate epics.
Review the parent’s outcome before closing it. Completed child tasks don’t automatically establish customer value.

An experiment can be complete even when the idea doesn’t work. Record the finding and resulting decision. If you abandon planned work, close it with an explanation rather than implying that it was performed.

Epics, milestones, and dependencies do different jobs

An epic groups work toward an outcome. A milestone groups work toward a target, such as Sprint 2. An epic can span several sprints, and a sprint can include work from several epics.

GitHub milestones group issues and pull requests within a repository and can have due dates. For a single-repository student project, a sprint milestone is a reasonable starting point. Avoid maintaining the same sprint information in several places. Milestone guide

A dependency means one task genuinely needs another to happen first. Observing someone use your prototype may depend on fixing a broken start button. Interviewing them about their current process probably doesn’t.

GitHub supports “blocked by” relationships between issues. Use them when they explain an actual obstacle. Issues and dependencies quickstart

5. Follow a code issue through the development workflow

Suppose you’re ready to implement the price filter.

The usual sequence is:

Issue → branch → changes → commits → push → pull request → review → merge

The issue explains the work. The remaining steps manage changes to repository files.

Branch: give the change its own working space

A branch lets you develop a change separately from the project’s main line of work. The default branch is often called main.

Start from an up-to-date main and create a descriptive branch, such as add-price-filter. Keep unrelated work on separate branches.

This is the basic approach in GitHub flow. You can follow it through a graphical tool or with an AI assistant; learning the relationships matters more than memorizing commands.

Commit: record a meaningful checkpoint

A commit records a snapshot of the changes you’ve selected, with a message explaining them.

Saving a file and committing are separate actions. Your editor saves the file; Git records the selected change in project history when you commit.

Use messages that help someone understand the work:

Add price-range filter to restaurant list
Explain when no restaurants match the selected price

“Updates” is technically a message. It’s just not doing much for future you.

Aim for coherent changes that you can explain. One issue might take several commits.

Push: send your commits to GitHub

A push sends local commits to the remote repository on GitHub. It makes them available beyond your computer.

Committing locally does not automatically push your work. Pushing a feature branch does not automatically merge it into main. GitHub’s push guide

Pull request: make the proposed change reviewable

A pull request, or PR, proposes bringing changes from one branch into another. It brings together the explanation, changed files, discussion, and checks.

One PR can contain several commits. For our work, aim for one focused change per PR.

A useful PR description answers:

What problem does this address?
What changed?
How did you check it?
What still needs attention?

Open a draft PR if you want to share unfinished work. When you push more commits to its branch, the PR updates. GitHub’s pull-request reference explains the review surface and draft status.

Link the PR to the right issue

If the PR fully completes code issue #24, putting Closes #24 in the PR description can close that issue automatically when the PR merges into the repository’s default branch.

If it only contributes to the issue, use an ordinary reference such as Related to #24.

Be especially careful with the epic. Shipping the price filter completes a software task. The customer experiment still needs to happen, so the PR shouldn’t close the entire investigation. Issue-linking guide

6. Review the change before merging it

A diff shows what was added, removed, or changed. In a GitHub PR, you can inspect it under Files changed.

Use the issue’s acceptance criteria to guide your review:

Does the feature behave as described?
What happens with an empty, missing, or unexpected input?
Did anything unrelated change?
Are the tests or checks relevant to this change?
Are there files here that shouldn’t be shared, such as credentials or private customer records?

You don’t need to understand every line immediately. You do need to notice unfamiliar changes and ask for explanations. “Why did adding a filter change our login system?” is a very reasonable question.

Ask the AI to walk through the diff, then check the behavior yourself. A second AI review can help find problems, but it still needs evidence behind its conclusions.

Even when you’re working alone, review your own PR. When working with a peer, give specific feedback tied to the intended result. GitHub’s review walkthrough shows where to inspect changes.

Merge: incorporate the reviewed change

A merge incorporates changes into the target branch. After the relevant checks and review are complete, merge the PR according to your repository’s rules.

If several merge options appear, follow the repository’s convention. For a small student project with focused PRs, Squash and merge is a reasonable default when available: it combines the PR’s commits into one commit on the target branch. Merge guide

Afterward, update your local main before starting the next branch. Delete the finished feature branch when you no longer need it.

Deployment is another step

Deployment makes a version of the application run in its intended environment.

Your hosting setup may deploy automatically after a merge to main. Check whether it actually did, then try the changed behavior at the live address. A merged PR and a successful live feature are separate things to verify.

7. Handle the confusing bits deliberately

A merge conflict needs a decision

A conflict occurs when Git can’t automatically reconcile competing changes—for example, two edits to the same lines.

Resolving it means choosing the correct final content. Review what both changes were trying to accomplish, preserve the intended behavior, and test the result. Automatically accepting whichever version looks newer can discard useful work. Merge-conflict guide

A merged mistake can still be corrected

If a merged change causes a problem, make a focused fix or use a revert to undo the change through another recorded change. Ask for help before rewriting shared history.

Small, understandable changes make recovery much easier.

A venture issue may never need a PR

An interview issue might finish with an evidence summary and a decision recorded in its comments. That’s a complete workflow.

If you change a research document stored in the repository, those file changes can go through a PR. PRs can review documents as well as code.

Keep sensitive interview material in an appropriately restricted location. A label or filtered view doesn’t change who can access an issue.

8. Give your AI assistant a bounded task

An issue is useful context for an AI assistant because it defines purpose, scope, and a way to evaluate the result.

For a code task, try:

Read issue #24 and the project instructions. Explain the intended behavior and propose a small implementation plan. Work on a new branch and keep the changes focused on this issue. Run the relevant checks, then report what you verified and what remains untested. Open a PR with a clear explanation and wait for my review before merging.

For a venture task:

Read this research issue and help me improve the experiment. Identify leading questions, assumptions, and practical obstacles. Suggest a smaller test if possible. Keep proposed observations separate from evidence we have actually collected.

The human sandwich still applies: set the direction, let AI help execute, then evaluate the result. GitHub gives you places to preserve those decisions.

9. Practice with one real piece of work

Use your existing project and choose a small task.

Write one venture issue. Identify a consequential question, a feasible action, and what evidence you’ll record.
Create a parent issue if needed. Use it only if your outcome genuinely needs several independently manageable tasks.
Identify a supporting code issue. If the experiment doesn’t require code, choose a separate small improvement to practice the development workflow.
Organize the issues. Apply track labels, assign responsibility, and place them in the appropriate project status and sprint milestone.
Take one repository change through a branch, commit, push, and PR.
Review the result. Explain what changed, demonstrate the relevant behavior, and identify anything still uncertain.
Merge when ready and update the issue record. Record what was completed and what comes next.

Before calling the exercise finished, explain this distinction to someone else:

What did you change in the product, and what have you learned about whether that change is useful?

Being able to answer both questions gives you a much stronger basis for deciding what to do next.