X4 Complete one documentation task

11:05–11:40 · 35 minutes

Complete E01-T2 through a branch, a pull request, a review, a merge, and the automatic closing of the Issue.
NoteAt a glance
  • Time: 35 minutes
  • You produce: one merged pull request that adds the section “Research question and scope” to the README and closes the Issue E01-T2.
  • New terms: branch, commit, pull request, review, merge. All terms are in the cheat sheet.

Why this step

In X1 you changed main directly. That is acceptable for a first README, but it skips two safeguards. A branch keeps a change apart until it is ready. A pull request shows the change, links it to the Issue that asked for it, and invites a review before the change enters main.

The link between the pull request and the Issue closes the loop of the plan. The keyword Closes #4 in the pull request description tells GitHub to close Issue #4 when the pull request merges. The Project workflows then move the item to In review when the link appears and to Done when the Issue closes. The plan and the work agree without extra clicks.

A review is a human check against the acceptance criteria. An automatic AI reviewer can appear if your account enables it. In the test run on 12 October 2026, it failed with a quota message. Do not treat an AI review as the review.

Before you start

  • You finished X3. Issue E01-T2 exists. Note its number (for example #4).

  • Command-line route: open a terminal in the folder projm-thesis. Define the helper issue as in X3, if this is a new terminal:

    issue() { gh issue list --state all --limit 100 --json number,title \
  --jq ".[] | select(.title | startswith(\"$1 \")) | .number"; }

  • Pair up if possible. Your partner reviews your pull request, and you review theirs.

Steps

Edit on a new branch

  1. Open README.md and click the pencil icon.
  2. Place the cursor before the line ## Visibility.
  3. Paste the text below.
  4. Click Commit changes….
  5. Type the message docs: add research question and scope.
  6. Select Create a new branch for this commit and start a pull request. Keep the proposed branch name or type docs/e01-t2-scope.
  7. Click Propose changes.

  1. Create a branch for E01-T2 and switch to it. The branch is linked to the Issue.

    gh issue develop $(issue E01-T2) --name docs/e01-t2-scope --checkout

  2. Open README.md in a text editor.

  3. Paste the text below before the line ## Visibility.

  4. Save the file.

  5. Save the change as a commit and send the branch to GitHub:

    git add README.md
git commit -m "docs: add research question and scope"
git push

The text to paste:

## Research question and scope

**Research question:** How did the landscape of Swiss periodicals change between 1830 and 1960 by language, place, and subject?

| In scope                                                  | Out of scope                                   |
| --------------------------------------------------------- | ---------------------------------------------- |
| 30 synthetic periodical records (German, French, Italian) | Real archival records or digitised page images |
| Place, language, frequency, and years of publication      | Content analysis of articles                   |
| Reuse status of the fictional scans                       | Readers, subscribers, or other personal data   |

Open the pull request

  1. Type the title docs: add research question and scope.
  2. In the description, write Closes #4 on the first line. Use the number of your E01-T2.
  3. Copy the acceptance criteria of E01-T2 below it and tick the boxes that your change meets.
  4. Click Create pull request.
  5. Open your Project. E01-T2 now shows the Status In review. The Project workflow Pull request linked to issue sets it. The workflow runs with a delay. If the Status did not change, wait one minute and reload the page. If it still did not change, check the workflow as in X3.
Pull request #43 “docs: add research question and scope”. It merges one commit from the branch docs/e01-t2-scope into main. The description starts with “Closes #3” and repeats the acceptance criteria as checked boxes. In the sidebar, Copilot is listed as a reviewer.
(1) From the branch into main; (2) Closes; (3) Automatic AI reviewer (account setting). Captured 2026-10-12.
The workflow “Pull request linked to issue” is on. When a pull request is linked to an issue, it sets the value Status: In review.
(1) Trigger; (2) Action; (3) true. Captured 2026-10-12.

  1. Print the number of your E01-T2 with issue E01-T2.

  2. In a text editor, write the description of the pull request. Write Closes # and this number on the first line, for example Closes #4.

  3. Copy the acceptance criteria of E01-T2 below it. Tick the boxes that your change meets: - [x].

  4. Save the description as pr-body.md in the folder that contains projm-thesis.

  5. Open the pull request:

    gh pr create --title "docs: add research question and scope" --body-file ../pr-body.md

  6. Check the Status of E01-T2 in the Project. The result is In review. The Project workflow Pull request linked to issue sets it.

    gh issue view $(issue E01-T2) --json projectItems --jq '.projectItems[] | .title + ": " + .status.name'

  7. The workflow runs with a delay. If the result is not In review, wait one minute and run the command again.

Review and merge

  1. Open the tab Files changed.
  2. Check the change against each acceptance criterion.
  3. Click Submit review. A partner selects Approve; on your own pull request, select Comment and write what you checked.
  4. Return to Conversation and click Merge pull request, then Confirm merge.
  5. Click Delete branch.
  6. Open your Project. E01-T2 shows the Status Done. The workflow runs with a delay. If the Status did not change, wait one minute and reload the page.
The “Files changed” tab of pull request #43. README.md shows ten added lines in green: the section “Research question and scope” with a research question and a table of what is in and out of scope. The buttons “Submit review” and “Ready to merge” are at the top.
(1) Added lines; (2) Submit review; (3) Merge status. Captured 2026-10-12.

  1. Show the change and check it against each acceptance criterion:

    gh pr diff

  2. Submit the review. On your own pull request, write a comment that says what you checked. A partner approves with gh pr review NUMBER --approve.

    gh pr review --comment --body "Checked the three acceptance criteria."

  3. Merge the pull request and delete the branch. gh then switches your folder back to main and gets the merged state.

    gh pr merge --merge --delete-branch

  4. Check that E01-T2 is closed and that the Project shows Done:

    gh issue view $(issue E01-T2) --json state,projectItems --jq '.state, (.projectItems[] | .status.name)'

  5. The workflow runs with a delay. If the result is not CLOSED and Done, wait one minute and run the command again.

Expected state

Issue #3 “E01-T2 Write the research question and scope” is closed. The timeline says “closed this as completed in #43”. The sidebar shows milestone M1 at 25 percent, the parent issue E01 with 1 of 4 sub-issues done, and under Development the pull request and the release tag.
(1) Closed by the merged pull request; (2) Milestone progress; (3) Development links. Captured 2026-10-12.

If something goes wrong

Problem Cause Recovery
The Issue did not close. The keyword is missing or has the wrong number. Edit the pull request description before the merge. After the merge, close the Issue by hand and link the pull request.
You cannot approve your own pull request. GitHub does not allow it. Use Comment, or ask a partner.
The Status did not change. The Project workflow is off or broken. Open Workflows; check Pull request linked to issue and Item closed. Set the Status by hand.
“This branch has conflicts”. Someone else changed the same lines. Click Resolve conflicts, keep both texts, and mark the conflict as resolved.
You committed to main instead. Wrong option in the dialog, or no git switch before the commit. Close the Issue by hand with a comment that links the commit. Use a branch next time.
A command fails. Usually the installation, the sign-in, or the folder. See Command-line problems, or do the step in the browser.

Alternatives

  • Pair: exchange review rights. Add your partner as a collaborator so that they can approve.
  • Private path: identical. Branch protection for private repositories needs a paid plan, but this exercise does not need it.

Official documentation

Next

Break (11:40–11:50), then X5 Prepare a reusable output.

Back to top