Skip to content

Clarify whether WIP commits require the type of the in-progress commit #72

Description

@javier-godoy

Summary

The convention already requires the subject of a WIP: commit to begin with the type of
the in-progress commit, i.e. WIP: feat: subject. This issue asks whether that requirement is
intended as written, and if so, whether it should be stated more explicitly.

From conventional-commits.md, WIP commits:

In order to mark a commit as work-in-progress:

  • The commit type must be WIP: (uppercase)
  • The commit subject must begin with the type of the in-progress commit, followed by
    the subject of the in-progress commit.
WIP: fix: prevent orders with negative amount of items

So, as written today:

Header Per the convention
WIP: feat: add support for exporting concatenated columns valid
WIP: add support for exporting concatenated columns invalid — the subject does not begin with a type

The question

Three alternatives for the type of the in-progress commit:

  • Require it (the convention as written): WIP: feat: subject is the only valid form.
  • Allow it: both WIP: feat: subject and WIP: subject are valid. The type is used when
    the in-progress work has one, and omitted when it does not.
  • Forbid it: WIP: subject is the only valid form.

Why it is worth asking

Two tensions inside the document itself:

  1. §1 Type states that "WIP: commits are necessarily not atomical". The WIP section
    then requires the subject to begin with the type of the in-progress commit — singular.
    If a non-atomic WIP commit is going to be split into, say, a feat: and a test:, there
    is no single type to name, and the requirement gives no answer.

  2. §3 Subject limits the header to fewer than 72 characters, which leaves no room for the
    five characters of the WIP: prefix, so some valid final headers cannot be expressed as
    WIP commits at all. That is the same contradiction Commit Header Length Exception for Reverts #61 resolved for revert:, and it is
    filed separately as Header length limit does not account for the five characters added by the WIP prefix #73.

Arguments for requiring it

  • Symmetry with revert:, which the document treats the same way: a prefix followed by the
    full header of another commit, for the same reason — the header the commit will end up
    having should travel with it.
  • The final message is a rewrite of the WIP message, so squashing becomes "delete the WIP:
    prefix" instead of deciding the type at the end, when the change is largest.
  • The reviewer can see what the eventual commit will claim to be.
  • The semantic versioning level of the eventual change is visible while the branch is still in
    progress — which the stated rationale for classifying WIP as NONE ("the level of semantic
    versioning change cannot be decided from the commit message alone"
    ) assumes to be
    impossible, even though the current format rule makes it possible.

Arguments for allowing it

  • It answers both tensions above without a special rule for either. When the in-progress work
    has no single type, the type is omitted rather than invented; when the header does not fit
    in 72 characters, the type is omitted rather than the subject truncated.
  • It keeps the information whenever the developer has it, which is the common case: most WIP
    commits do become a single commit of a known type.
  • The cost of omitting is paid by the developer who omits, at squash time, and by nobody else.
    A WIP commit is temporary by definition, so a missing type is never inherited by the
    permanent history.

Arguments for forbidding it

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions