Guidelines for Commits

Please help keeping code and changes comprehensible for years. Provide a readable commit-history following this guideline.

A commit

  • stands alone as a single, complete, logical change,

  • has a descriptive commit message (see below),

  • has no extraneous modifications (whitespace changes, fixing a typo in an unrelated file, etc.),

  • follows established coding conventions (PEP 8) closely.

Avoid committing several unrelated changes in one go. It makes merging difficult, and also makes it harder to determine which change is the culprit if a bug crops up.

If you did several unrelated changes before committing, git gui makes committing selected parts and even selected lines easy. Try the context menu within the windows diff area.

This results in a more readable history, which makes it easier to understand why a change was made. In case of an issue, it’s easier to git bisect to find breaking changes any revert those breaking changes.

In Detail

A commit should be one (and just one) logical unit. It should be something that someone might want to patch or revert in its entirety, and never piece-wise. If it could be useful in pieces, make separate commits.

  • Make small patches (i.e. work in consistent increments).

  • Reformatting code without functional changes will generally not be accepted (for rationale see #2727). If such changes are required, separate it into a commit of its own and document as such.

    This means that when looking at patches later, we don’t have to wade through loads of non-functional changes to get to the relevant parts of the patch.

  • Especially don’t mix different types of change, and put a standard prefix for each type of change to identify it in your commit message.

  • Abstain refactorings! If any, restrict refactorings (that should not change functionality) to their own commit (and document).

  • Restrict functionality changes (bug fix or new feature) to their own changelists (and document).

  • If your commit-series includes any “fix up” commits (“Fix typo.”, “Fix test.”, “Remove commented code.”) please use git rebase -i … to clean them up prior to submitting a pull-request.

  • Use git rebase -i to sort, squash, and fixup commits prior to submitting the pull-request. Make it a readable history, easy to understand what you’ve done.

Please Write Good Commit Messages

Please help keeping code and changes comprehensible for years. Write good commit messages following this guideline.

Commit messages should provide enough information to enable a third party to decide if the change is relevant to them and if they need to read the change itself.

PyInstaller is maintained since 2005 and we often need to comprehend years later why a certain change has been implemented as it is. What seemed to be obvious when the change was applied may be just obscure years later. The original contributor may be out of reach, while another developer needs to comprehend the reasons, side-effects and decisions the original author considered.

We learned that commit messages are important to comprehend changes and thus we are a bit picky about them.

We may ask you to reword your commit messages. In this case, use git rebase -i … and git push -f … to update your pull-request. See Updating a Pull-Request for details.

Content of the commit message

Write meaningful commit messages.

  • The first line shall be a short sentence that can stand alone as a short description of the change, written in the present tense, and prefixed with the subsystem-name. See below for details.

  • The body of the commit message should explain or justify the change, see below for details.

Examples of good commit messages are @5c1628e or @73d7710.

The first Line

The first line of the commit message shall

  • be a short sentence (≤ 72 characters maximum, but shoot for ≤ 50),

  • use the present tense (“Add awesome feature.”) 1,

  • be prefixed with an identifier for the subsystem this commit is related to (“tests: Fix the frob.” or “building: Make all nodes turn faster.”),

  • always end with a period.

  • Ending punctuation other than a period should be used to indicate that the summary line is incomplete and continues after the separator; “…” is conventional.

1

Consider these messages as the instructions for what applying the commit will do. Further this convention matches up with commit messages generated by commands like git merge and git revert.

The Commit-Message Body

The body of a commit log should:

  • explain or justify the change,

    • If you find yourself describing implementation details, this most probably should go into a source code comment.

    • Please include motivation for the change, and contrasts its implementation with previous behavior.

    • For more complicate or serious changes please document relevant decisions, contrast them with other possibilities for chosen, side-effect you experienced, or other thinks to keep in mind when touching this peace of code again. (Although the later might better go into a source code comment.)

  • for a bug fix, provide a ticket number or link to the ticket,

  • explain what changes were made at a high level (The GNU ChangeLog standard is worth a read),

  • be word-wrapped to 72 characters per line, don’t go over 80; and

  • separated by a blank line from the first line.

  • Bullet points and numbered lists are okay, too:

    * Typically a hyphen or asterisk is used for the bullet, preceded by a
  single space, with blank lines in between, but conventions vary here.

* Use a hanging indent.

  • Do not start your commit message with a hash-mark (#) as git some git commands may dismiss these message. (See this discussion. for details.)

Standard prefixes

Please state the “subsystem” this commit is related to as a prefix in the first line. Do learn which prefixes others used for the files you changed you can use git log --oneline path/to/file/or/dir.

Examples for “subsystems” are:

  • Hooks for hook-related changes

  • Bootloader, Bootloader build for the bootloader or it’s build system

  • depend for the dependency detection parts (PyInstaller/depend)

  • building for the building part (PyInstaller/building)

  • compat for code related to compatibility of different Python versions (primary PyInstaller/compat.py)

  • loader

  • utils, utils/hooks

  • Tests, Test/CI: For changes to the test suite (incl. requirements), resp. the CI.

  • modulegraph: changes related to PyInstaller/lib/modulegraph

  • Doc, Doc build for the documentation content resp. it’s build system. You may want to specify the chapter or section too.

Please set the correct Author

Please make sure you have setup git to use the correct name and email for your commits. Use the same name and email on all machines you may push from. Example:

# Set name and email
git config --global user.name "Firstname Lastname"
git config --global user.email "your_email@youremail.com"

This will set this name and email-address to be used for all git-repos you are working on on this system. To set it for just the PyInstaller repo, remove the --global flag.

Alternatively you may use git gui ‣ Edit ‣ Options … to set these values.

Further Reading

Further hints and tutorials about writing good commit messages can also be found at: