dwyl / dwyl/contributing

Branch and Pull Request Naming

Open
#100 1 comment 0 reactions 0 assignees View on GitHub
bug help wanted
Dominant language
No language data
Stars
91
Forks
9
PR merge metrics
No merged PRs in 30d

Description

We have notes creating Good Pull Requests:
[github.com/dwyl/contributing#notes-on-creating-good-pull-requests](https://github.com/dwyl/contributing/tree/a7fa2bd8714bfc0bbf8d5293fd582fc9a35a130f#notes-on-creating-good-pull-requests)
However we are _still_ getting PRs that are named in an _unhelpful_ way ... 😞
![poor-branch-and-pr-name](https://user-images.githubusercontent.com/194400/28962651-4126f9de-78fe-11e7-96f1-dadb47c026d8.png)

What does a branch (_and corresponding pull request_) named "**test**" _add_ to (_fix or remove from_) the project?

People keep _forgetting_ that the _purpose_ of writing code
and (then) getting it merged it into a project
is to _communicate_ as much as possible with teammates.

> "_**Programs** must be written **for people to read**, and only incidentally for machines to execute._" ~ [Harold Abelson](https://en.wikipedia.org/wiki/Hal_Abelson)

> "_Any fool can write code that a computer can understand. **Good programmers write code** that **humans can understand**._" ~ Martin Fowler

Some teams/organisations have a branch naming convention
e.g: https://github.com/agis/git-style-guide#branches

@nvie has a _detailed_ post on this: http://nvie.com/posts/a-successful-git-branching-model
_however_ I would not describe it as "_beginner friendly_" ... we _should_ encourage people to read it as "further" or "background" reading, but we should distill it to a simple rule that _anyone_ can follow without "advanced" git knowledge.

## Proposal for Git Branch Naming

+ Git branches should be named _descriptively_.
+ Avoid _one_ word names like `test` or `fix`.
+ Include the issue number in the branch name

A _good_ (_descriptive/helpful_) branch name and PR name/description:
![image](https://user-images.githubusercontent.com/194400/28964326-386d7cfe-7904-11e7-8e4a-fa20e3dda1e0.png)

> Note: I am guilty of using branch names that are not "team friendly" so trying not to ["throw stones"](https://en.wikipedia.org/wiki/Those_who_live_in_glass_houses_should_not_throw_stones).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.