Please help keeping code and changes comprehensible for years. Provide a readable commit-history following this guideline.
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,
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.
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
to clean them up prior to submitting a pull-request.
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 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
to update your pull-request. See
Updating a Pull-Request
Write meaningful commit messages.
The first line of the commit message shall
|||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 body of a commit log should:
explain or justify the change,
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
. for details.)
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
Examples for “subsystems” are:
Hooksfor hook-related changes
Bootloader buildfor the bootloader or it’s build system
dependfor the dependency detection parts (
buildingfor the building part (
compatfor code related to compatibility of different Python versions (primary
Test/CI: For changes to the test suite (incl. requirements), resp. the CI.
modulegraph: changes related to
Doc buildfor the documentation content resp. it’s build system. You may want to specify the chapter or section too.
Further hints and tutorials about writing good commit messages can also be found at:
This page was composed from material found at