Learn to write good commit message and description

[webknjaz]

It's a follow-up for:

@decentral1se @ssbarnea I've got a collection of articles about writing meaningful commit messages. I'll post it as a separate issue so that anyone could go through this and we could be on the same page...
Sounds fair?

Originally posted by @webknjaz in #1883 (comment)

---

                                                 

According to common commit style guides, it is required to write messages in an imperative manner. Make them actionable and atomic. Also avoid using -m as you often need to express more detail in a long way. Here's several articles sharing best practices:

• http://chris.beams.io/posts/git-commit/
• http://alistapart.com/article/the-art-of-the-commit
• https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message
• https://github.com/erlang/otp/wiki/writing-good-commit-messages
• https://wiki.openstack.org/wiki/GitCommitMessages
• http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
• https://dev.to/gonedark/when-to-make-a-git-commit

N.B. This all applies to issues and PRs as well. If you submit a patch, everything in diff should refer to only one logical change making it atomic. Ideally, applying a single PR should transition a project from one working state to another completely working state, meaning there shouldn't be a change submitted via two PRs and there shouldn't be anything more than needed to fulfill what's in description and title of the PR.

P.S. Don't scare (other) maintainers with huge changes. Reviewing a PR is hard work. The bigger it is the more chance is that somebody will postpone it until better times (trying to find an appropriate slot in their calendars to the review in one pass).
Smaller changes attract more viewers and people, in general, are more likely to understand tiny patches and their impact.

[webknjaz]

There's also a number of things I encourage people to learn about Git. Maybe you will find something for yourselves.

• ProGit 2 🇺🇦
• Try Git
• Try Git Branching
• Interactive diagram/cheatsheet about git
• You're using git wrong

Extras:

• A useful template for commit messages
• Understanding the GitHub Flow
• Closing issues using keywords

[decentral1se]

A serious resource! I wonder should you have a canonical URL on http://webknjaz.me/ :)

[webknjaz]

@decentral1se what do you mean about canonical URL there? :)

Are you suggesting to put up a web page with those links? I normally post this as GitHub issues/tasks in repos for my mentees...

[webknjaz]

Read a good advice recently: https://twitter.com/jefflembeck/status/1118892291995734016

[ssbarnea]

While this ticket is still very useful I will be closing it because there is no end to it as it not molecule specific.

Most of this coud be included in a docs page but the next question would be: why to document this in molecule when we could just defer this to ansible itself.