Make and Submit a Small Perl Core Patch Safely

You will finish with a local branch containing a tested Perl core change, a reviewable commit, and a GitHub pull request ready for the Perl project. This is the short path for a documentation fix, regression test or other small patch. Allow 30 to 60 minutes for a small change, plus the time taken by the test suite.

The examples describe the installed perlhack(1) from perl-doc 5.38.2-3.2ubuntu0.6, which documents Perl v5.38.2. Perl development moves, so check the copy in the repository before starting:

$ perl -v
$ perldoc pod/perlhack.pod

You need Git, a compiler toolchain suitable for Perl, and enough disk space for a source checkout and build. Normal checkout, editing and testing commands do not need sudo. Do not use a system package directory as your working tree.

1. Clone the Perl source

Choose a directory where you keep source checkouts, then clone the official repository. HTTPS is the least surprising option on a machine where SSH keys are not already configured:

$ git clone https://github.com/Perl/perl5.git perl
$ cd perl
$ git status --short

A clean new checkout prints no lines for the status command. The repository contains the long Perl history, so the clone can take a while. If you already have a checkout, do not clone over it: inspect its current branch and changes first.

2. Create an isolated branch

Base a branch on blead, the main Perl development branch. Give it a short name describing the work:

$ git switch blead
$ git pull --ff-only
$ git switch -c fix-perlhack-typo
$ git status --short --branch

If your Git is older and does not have git switch, the equivalent documented form is git checkout -b fix-perlhack-typo. A branch keeps your change separate from the checkout used for other work. If git pull --ff-only refuses because you have local commits or changes, stop and resolve that repository state before branching.

3. Make the smallest useful change

Edit only the files needed to correct the problem. Follow the surrounding code style. Perl's core guidance calls for four-space indentation, spaces rather than tabs in new code, and lines normally no wider than 79 columns. Comments should explain why a surprising choice exists, not merely repeat what the code says.

For a code fix, add or update a test that demonstrates the bug and fails for the old behaviour. For a documentation-only change, a test may not be needed. Keep generated files, editor backups and unrelated formatting changes out of the branch.

Review the working tree before testing:

$ git status --short
$ git diff --check
$ git diff -- path/to/changed-file

git diff --check should produce no output. Read the diff as a reviewer would. In particular, check that a broad search-and-replace did not alter examples, generated data or another platform's code.

4. Configure and run the tests

The installed manual gives this baseline for a development checkout:

$ ./Configure -des -Dusedevel
$ make test

-des selects a non-interactive Configure run with the standard answers, while -Dusedevel marks the build as a development build. Configuration writes build files into the checkout, so do not run it in a directory containing unrelated work. The command can take several minutes and the test suite is much longer than a single unit test.

When the test command finishes, verify its exit status before doing anything else:

$ printf 'test exit status: %s\n' "$?"
test exit status: 0

That status belongs to the command immediately before printf. A non-zero result is a stop sign, not a reason to commit anyway. Read the failing test output, reproduce the smallest relevant case, and continue fixing until the complete suite passes. If the failure looks unrelated to your patch, record the platform, configuration and exact failing test for the review.

5. Review and stage only your change

Do not use a blanket add command when the checkout contains build output or unrelated files. Current upstream guidance recommends selecting the files deliberately, with either explicit paths or interactive staging:

$ git add path/to/changed-file path/to/changed-test
$ git diff --cached --check
$ git diff --cached

For a larger change, git add -i lets you choose files or hunks. The staged diff should contain exactly what you intend to submit. If it contains generated build output, remove that path from the index with git restore --staged path/to/unwanted-file, then inspect again. This changes only staging; it does not delete the file.

6. Write a useful commit

Use a short title that says what changed and where. Perl's current guidance treats about 50 characters as a useful limit, because the title is what people see in a compact log. Put the reason and implementation details in the body when they will help a future maintainer:

$ git commit -m 'perlhack: Fix spelling error'
$ git show --stat --oneline HEAD
$ git status --short

Git should report a new commit, and the final status should contain no unstaged or untracked files that belong to this change. If you need to amend a commit before publishing it, edit the files, rerun the relevant tests, stage the corrected paths and use git commit --amend.

7. Submit from a fork

Create a fork of Perl/perl5 on GitHub, then add your fork as a remote. Replace MyUser with your GitHub account name:

$ git remote add fork [email protected]:MyUser/perl5.git
$ git push -u fork fix-perlhack-typo

If SSH is not configured, use your fork's HTTPS URL instead. The push creates or updates a branch on your fork; it does not change Perl's official repository. Open a pull request from that branch to blead. For a small patch, the pull request is the normal review route. The project's issue tracker is also useful for checking whether the bug has already been reported.

If you do not want your name and email added to Perl's public contributor list, review the current Porting/updateAUTHORS.pl guidance before submitting. Do not run contributor-record commands without understanding what they will publish.

8. Recover without destroying work

If you need to abandon a branch, preserve anything valuable first. Create a patch or another branch, then switch away. Do not copy the manual's git reset --hard or git clean -dxf examples into a recovery script: those commands can discard local changes and untracked files irreversibly.

For routine cleanup, prefer inspection:

$ git status --short
$ git log --oneline --decorate -5
$ git diff
$ git diff --cached

If a test failed after configuration, keep the failure output and the output of perl -V for the report. If the branch was pushed but the pull request is not ready, leave it open and push later after another review. A local commit can be amended; a published commit deserves extra care because reviewers may already have seen it.