Lesson 13.3: A pull request #

The last lesson closes the circle of the course: a fix learners make for themselves goes back to the project, so it is in the next release and nobody has to carry it alone. In this lesson learners prepare a small, real change (often a fix to these help pages) as a pull request, with every check a reviewer expects.

At a glance #

Learning objectives #

After this lesson, learners can:

• fork a repository and add the fork as a remote of their clone;
• make a focused change on a branch of its own;
• write a commit subject with the right prefix and run the checks and the manifest;
• push the branch to the fork and open a pull request with a useful description;
• respond to review comments with changes on the same branch, then squash and rebase it onto main.

Trainer's notes #

How to present it #

Sources: Develop with Git, Contribute a change with a pull request and CONTRIBUTING.md in the installation root.

1. Why (2 minutes). A fix kept only on your site has to be re-applied after every update; a merged fix is in the next release for everyone.
2. The license (2 minutes). Exponential is under the GNU GPL, version 2 or later; contributions are released under the same license (CONTRIBUTING.md). Documentation is free under the GNU FDL 1.3.
3. The steps (5 minutes). Fork on GitHub; git remote add fork https://github.com/<you>/<repository>.git; a branch per change; the change; the checks of lesson 12.3; for the kernel, the manifest (make manifest-fix); a commit Fixed: ...; git push -u fork <branch>; open the pull request from the link GitHub prints (or gh pr create).
4. A good description (3 minutes). What was wrong, what the change does, how it was tested, and anything the reviewer should look at. One topic per pull request.
5. Review (2 minutes). Answer comments and change the code on the same branch. For the kernel, 7x requires the pull request to be squashed and rebased onto main while it is open: git fetch origin, git rebase -i origin/main, git push --force-with-lease to the pull request branch only; the pull request updates itself. After the merge, main is never rewritten.

Common questions #

Can I contribute to an extension the same way? Yes: each extension is its own repository with its own origin; the steps are the same inside extension/<name>.

What if CI fails on my pull request? Read the failing step; its summary names the problem (a stale manifest line, a commit subject, a syntax error). Fix it with another commit on the branch.

Do I need write access to the project? No. You push to your fork; the pull request asks the project to take the change.

How long does review take? Prepare learners for many rounds: 7x reviews a commit or pull request in many more rounds than usual, sometimes hundreds of revisions, until the change is simple to accept (Code reviews).

Do I have to sign anything? For a code contribution to the kernel, yes: 7x and the Exponential Foundation merge it only once the author's signed Contributor Licensing Agreement has been received. Say plainly what it means: by signing and submitting, the author assigns the copyright in the contribution to the Exponential Foundation and 7x, which become its owners, and gives up control over it; 7x may use, change, relicense and distribute it in any way, without asking or paying the author, who cannot withdraw it or set conditions on it. It is signed once. A pull request opened in the course can wait for it. Learners' own extensions are not affected (Copyright assignment (CLA)).

Pitfalls #

• Working on main. Always a branch; one change per branch.
• Secrets in the commit. settings/override/ and settings/siteaccess/ may hold passwords; never commit them. Check git diff --cached --name-only before every commit.
• A pull request that does many things. Split it; small pull requests are reviewed faster.
• "Fixing" deliberate behavior. Some reported bugs are negative features: on purpose, or open to interpretation, and other sites depend on them. Changing one needs a clear justification and several review rounds, so steer learners to a different first fix, or to an option instead of a new default.

Hands-on exercise #

In the kernel clone of your development installation (or in the clone of an extension you used in the course).

1. Find something small to improve: a typo or an unclear sentence in a help page you read during the course, or a missing test.

2. Create a branch: git switch -c fix-<short-name>.

3. Make the change. For a documentation page, check its links with the help checker: php bin/php/console exp:help check --below=help/<folder>/.

4. Run the checks of lesson 12.3 that apply; for the kernel, update the manifest: make manifest-fix.

5. Review what will be committed: git status and git diff --cached --name-only after git add. Nothing from settings/override/ or var/.

6. Commit: git commit -m "Fixed: <what the change does>".

7. If you have a GitHub account: fork the repository on GitHub, add your fork and push:

   git remote add fork https://github.com/<you>/exponential.git
   git push -u fork fix-<short-name>

8. Open the pull request from the link GitHub prints. Describe what was wrong, what you changed and how you checked it.

9. Without an account: show the trainer git log --oneline -1 and git show --stat instead.

Expected result #

• Step 3: the help checker reports no errors for the folder of the changed page.
• Step 6: one focused commit whose subject starts with Fixed: (or another allowed prefix).
• Step 8: an open pull request on GitHub with a clear description, and CI starting on it.
• The trainer reviews one learner's pull request description with the group.

Quiz #

1. Where do you push your branch: to origin or to your fork?
2. Which file explains how to contribute to the kernel? A. README.md B. CONTRIBUTING.md C. composer.json D. share/filelist.md5
3. What belongs in a pull request description?
4. How do you answer a review comment that asks for a change?
5. Under which license are code contributions to Exponential released?

Further reading #

• Develop with Git: clones, branches, pull requests and keeping up to date.
• Source control and releases.
• Free documentation: improving these pages.
• Pull request etiquette and Contributing back upstream.

Related pages #

• Module 13: RAD, Velocity and contributing
• Developers: course overview
• Trainers: start here
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.