Semantic commits

Writing commits is a fast and simple process which we do all day. Imagine them becoming powerful for us which finally give them some attention. The following semantic commits will do so and have the aim to:

• Generate a changelog with commits for end-user
• Generate a speaking summary for customer
• Generate a easy to read list of changes for developer
• In general: Make commits parseable by some script

This is solved by the easy trick to use a well known structure (esp. PHP):

• Class names and Methods can be detected by using their semantic.
• Functions have a leading "()" which is obvious to detect.
• More fuzzy commits without one particular target can get a "tag".

Please leave a comment below if you are missing something in this prequel or in the ABNF.

Example

I just thought this would be nice as a commit message (almost full example):

\Foo_Class::barMethod() can now print a baz (#123)

In order to work as a human, I need to move in any SITUATION.
But this meant a big load of work for humanity, which is a PROBLEM.
As a human, I want to have a SOLUTION so that I can be lazy again.

- funcPrint42() has been deleted
- \Meh\Output has been extended for that purpose
- \Foo_Class::barMethod() will pass "baz" to the output
  if it is in a good mood
- /url/path has no need for human interaction till that
- humanity: is no longer disturbed by work
  because we all like to be lazy
- Except writing these lines one time

The header describes in general where the change is, what and give some reference. After that follows an optional short text about the situation before (which can be a user story), the problems with that and what the solution now is (also possible user story) - feel free to add the pros and cons. In the end follows a list of changes that can be extended by describing if-clauses or the matter (because) why the change needed to happen. You might note that functions, classes, methods and URLs can be referenced as well as tags (followed by colon) and non-referencing simple sentences. It is very flexible because an user story can be the classic ones from Connextra, the simpler ones by Mike Cohn, the "Feature Injection Stories" by Chris Matts or a user story that would answer the proven "Five Ws".

Benefit

Imagine a parser running through your code, mapping the references to according sections in an documentation and generating whole diff or manuals for developers. It can fetch the "long descriptions" / "paper questions part" to give your customer a brief text of what has been done to his website or application. For the most out there the heading is enough to gather text for a changelog.

Mapping

You can output the "tags" directly or filter them like this:

[
  '\Class_Foo'               => 'Usability',
  '\Class_Foo::someMethod()' => 'Hints for customer',
  'humanity'                 => 'Human interaction'
]

Generate changelogs for end-user

With appropriate commits that follow the "Semantic Commits" as described you can generate this:

# Usability

- Customer can now login more easily

## Hints for customer

- Reseller get a security question when kicking customer
- Customer get a notice via mail when they have been kicked

This was the example of three commits getting together through some tool generating a changelog or feature list for end-user.

Give your client a text he understands

The client you service the application for might want to see the problem and how it has been solved:

# Usability

As a customer five steps are too much for logging in.
Therefore we put everything on one page and eliminate the obvious.

# Hints for customer

Reseller may accidentally kick customer from their list.
To avoid that a security question is nagging before.

Kicked customer won't recognize that they have no account any more.
As a customer who got deleted from the system,
I receive an E-Mail because I want to be informed.

Still the same three commits as before but a total different view of things for a total different person with other needs.

Have fun writing ad-hoc documentations, changelog, feature lists, comments on user stories ..........

Technical part

Recent commits to the Repository of the VCS GIT brought me the idea and had big influence on the structure. If you find something in capital letters not defined here then it's probably part of ABNF: http://tools.ietf.org/html/rfc2234