diff --git a/README.md b/README.md index cfe3ab1..de15ed3 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -#dwyl Style Guide +#dwyl Style Guide >A style guide is a set of standards [which] establish and enforce style to improve communication. @@ -6,6 +6,8 @@ **_This style guide is a work in progress and is being put together over the course of [#dwylsummer](https://github.com/dwyl/summer-2015)_**. +[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/dwyl/style-guide/issues) Please open an issue if you have an questions or comments at all! + For now, the **visual** and **coding styles** [will live in the _same repo_](https://github.com/dwyl/summer-2015/issues/22). If the size of this readme gets out of hand or if we have a lot of requests to separate them, we'll do so. ##Contents Guide @@ -13,6 +15,11 @@ For now, the **visual** and **coding styles** [will live in the _same repo_](htt + [General guidelines](#general) + [Indentation](#indentation) + [Intelligently commenting your code](#intelligently-commenting-your-code) ++ [Git](#git) + + [Issues](#issues) + + [Commits](#commits) + + [Pull requests](#pull-requests) + + [Naming repositories](#naming-repos) + [Markdown](#markdown) + [ ] [CSS](#css) + [ ] [JavaScript](#javascript) @@ -22,7 +29,7 @@ For now, the **visual** and **coding styles** [will live in the _same repo_](htt **Consistency**. Every developer likes to do things their own way. -Even though we have our own idea of what maintainable code looks like, _the important thing isn't how many spaces we indent our code with_ but that **everything is consistent** so new people _don't have to work through personal formatting quirks_ of previous developers and can **focus on the code**. +Even though we have our own idea of what maintainable code looks like, _the important thing_ isn't how many spaces we indent our code with but that **everything is consistent** so new people _don't have to work through personal formatting quirks_ of previous developers and can **focus on the code**.

@@ -59,6 +66,61 @@ else { ```
+##Git + +###Issues ++ Your issue title should be **short but descriptive** ++ Use **labels** please! ++ If you want someone specific to look at your issue, **assign it to them** ++ **When referring to a file**, always do so within the **context of a specific commit** (as that file could be constantly changing and your issue will quickly stop making sense) + + Example: [https://github.com/dwyl/style-guide/blob/dea0009638b7923521a13190f17090af37a7ff22/README.md](https://github.com/dwyl/style-guide/blob/dea0009638b7923521a13190f17090af37a7ff22/README.md) and _not_ https://github.com/dwyl/style-guide/blob/master/README.md + + To get this URL, go to the _History_ tab on the top right of your document and choosing a commit form the list that appears + history-tab-on-git-documents ++ **When referring to a specific piece of code, include the line number** that code is on + + You can either add this by add `#L` and the line number to the end of the URL (e.g. https://github.com/dwyl/hapi-socketio-redis-chat-example/blame/b26354e3f37b2bdd0414b9b01bfe45db7ee9504e/lib/chat.js#L6) **or** + + Go to a specific commit (as above), click on 'View' and then click on 'Blame' in the top right hand corner + blame-tab-on-git-documents + + You can now click on any line and the line number will be added to the URL + +###Commits ++ Use the **third person present tense** in your commit messages, as if you were finishing off the sentence _"This commit message..."_ + + For example _"adds riot.js to index"_ or _"fixes #12 disappearing content bug"_ ++ **Include an issue number in _every commit message_** + + The commit message will then appear within that issue and ensure traceability of every contribution + +commit-message-referenced-from-issue ++ Keep your commits **'common sensibly small'** + + A good rule of thumb is that _if you have to use the word 'and' in your commit message, you're probably doing too much in a single commit_ unless the things you're committing are intrinsically tied together. ++ **If you're pairing**, consider giving your pair some credit in your commit messages by including their initials: + +paired-commit-message ++ Did you know you can [use emojis in your commit messages](https://github.com/dwyl/start-here/issues/49)? It's totally a thing. +emojis-in-commit-messages + + + +###Pull Requests +Good pull requests (PR) reduce the back and forth required between the person submitting the PR and the assigned reviewer, saving everyone time. ++ Before submitting a PR, **open a new issue** so you can _confirm the need_ for the functionality you are intending to add (like in [this example](https://github.com/indexzero/ps-tree/issues/10)) ++ When you submit your pull request, include: + + A **descriptive title** that answers the question "What does this PR do?" + + A reference to the issue that the PR solves + + An explanation of what the PR includes (**bullet pointed lists** are sometimes helpful to make things clearer) and the _implementation detail_ + + An **update to the documentation** (often the repo's readme) + + **Assign your pull request** to someone for review (this person will be the first point of contact if the PR merges a bug into the production environment) + +A good example is this one: https://github.com/indexzero/ps-tree/pull/12 + +####Reviewing pull requests ++ [Inline comments on github](https://help.github.com/articles/commenting-on-the-diff-of-a-pull-request/) are very useful when reviewing pull requests, both for traceability and speed of review. + +add-comment-inline-in-pr-comment-box + +###Naming repos ++ We favour one-word names for **node modules** (make sure the name is available [on npm](http://www.npmjs.com)) and descriptive names for everything else (especially tutorials!) + +
+ ##Markdown [This is a good reference for markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). For readability, we use `_` _underscores_ `_` for _italics_ and `**` **double asterisks** `**` for **bold**.