NiiL

Collaborate with a change history

English translation

AI Applications · Week 4

This week's goal · Record file change history, review edits made in a separate workflow, and merge them into the base version.

Example: an external contributor proposes changes for review

Illustrative scenario · The fictional situation below explains why a Git collaboration process is needed. This exercise uses your own repository and does not assign contributions to an external project.

When working alone, you can edit main directly and record history with Commits. A small team able to coordinate closely can invite a friend as a Collaborator, share edit permissions, and apply changes directly. A separate review request is not always required.

What if someone you do not know offers to improve the explanation? You may want to consider the suggestion without granting permission to change the base version directly. A useful workflow lets them propose changes from their own copy for a maintainer to review and apply. Even familiar teammates can use the same review process for a shared base version.

While using public exercise code for the first time, you discover a missing setup step in the README. You cannot edit this repository directly, but want to improve the instructions and propose the change to a maintainer.

  1. 1. Check the current original instructions · mainFind the missing explanation on main, the original Repository's default Branch. A Repository stores files and their change history.
  2. 2. Edit in your own workspace · Fork and BranchFork the original into a separate Repository in your account. Create a practice Branch in that copy and edit the instructions. You can prepare changes without permission to edit the original directly.
  3. 3. Record what changed · CommitRecord the change with the description “Add setup steps before execution.” Later, you can check when and why instructions changed or compare them with earlier content.
  4. 4. Review whether others can follow the instructions · Pull Request (PR)Request that changes made on practice in your copy be applied to main in the original. If a maintainer says, “The preparation location is missing,” update the same Branch and Commit. Additional changes reflected on GitHub are reviewed in the same PR.
  5. 5. Use the reviewed instructions together · MergeAfter a maintainer reviews and Merges the changes into the original main, other users see the improved instructions. For the next task, synchronize your copy with the latest original changes and start on a new Branch.
Prepare changes without direct edit permission → Request review → A maintainer applies them to the original. Branches separate work, Commits record changes, PRs gather reviews, and Merges combine reviewed changes.

In this case, the team exchanged both edited files and a history showing what changed. Next, examine Commits that record history, Branches that separate it, and PR review and Merge in order. Start with change records, the foundation of collaboration.

1. The unit of change history: Commit

In the earlier README example, saving a file alone does not record “which preparation step was added” in the change history. A Commit records selected changes with a description. Later comparison and review use this record. Use git status to inspect changed files and git diff to inspect their changes.

Distinguish saving a file from commit

Git add stages changes for the next commit. Committing does not automatically send them to GitHub. Push sends local history to the remote.

2. Branches separate change histories

Once you can record changes with Commits, distinguish the base version from work in progress. Branches manage separate change histories in the same repository. As in the earlier example, creating practice from main and committing lets you compare and review changes on practice while preserving main.

Create a branch and edit one place in a file

Before changing branches, save files and use git status to check for uncommitted changes. If edits seem missing, check the current Branch and whether the Commit appears in git log.

3. A PR requests review of changes

A Pull Request (PR) requests review of changes made in a separate workflow, a Branch, before merging them into another Branch. For example, propose applying changes from practice to the default Branch main. Creating a PR alone does not change main. Actually combining reviewed changes is called Merge. State the purpose in the title and describe the actual changes in the description. Reviewers inspect the differences under Files changed.

A PR requests review of changes

A Collaborator works with permissions on the original repository. Forking creates a separate repository copy in your account from which you send PRs to the original. A Collaborator pushes changes to the authorized original repository; with a Fork, you push to the copy in your own account.

4. Roles of Git and GitHub

Commits and Branches are change histories managed by Git. They work in folders on your computer or in Colab. GitHub shares repositories online and manages PR review comments and whether changes are incorporated.

Thus, Commit records changes, while Push sends that history to GitHub; these are separate operations. A Commit made on your computer appears on GitHub after a Push. The earlier collaboration example, performed locally, follows edit and Commit → Push → PR.

When editing files directly on the GitHub website

When you edit and Commit a file on the website, that history is already on GitHub. You can create a PR without a separate local Push. In this exercise, practice PRs and Merges through the GitHub website.

Check your understanding

  1. Can you explain the difference between saving a file, Commit, and Push?
  2. Did you check the source Branch of the PR changes and the target Branch for merging?
  3. Can you find the edited content and its history on main after Merge?

Official GitHub documentation

Practice materials