Skip to content

Commit 24d95ee

Browse files
WilHallWilHall
authored
Combine style, best practice, and protocol guides (thoughtbot#615)
This change addresses thoughtbot#610. We remove the arbitrary grouping of guides into "style", "best practices", and "protocols". Instead, all guides now live at the top-level of the repository. This makes it easier to find a guide, and reduces the chance of information being duplicated between different types of guides for the same topic. This change also updates the main `README.md` with a grouped table of contents of all the guides.
1 parent 4240c34 commit 24d95ee

File tree

89 files changed

+882
-1782
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

89 files changed

+882
-1782
lines changed

‎CONTRIBUTING.md

+6
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,9 @@ Decisions about which libraries to use should live in template projects such
2020
as [Suspenders].
2121

2222
[Suspenders]: https://github.com/thoughtbot/suspenders
23+
24+
### The Anatomy of a Guide
25+
26+
Whether you're creating a new guide or adding to an existing one, you can reference [the template guide] if you're unsure where to put things.
27+
28+
[the template guide]: /_template/

‎README.md

+88-46
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,107 @@
1-
Guides
2-
======
1+
# Guides
32

43
[![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)
54

6-
Guides for getting things done, programming well, and programming in style.
7-
8-
* [Best Practices](./best-practices)
9-
* [Code Review](./code-review)
10-
* [Tech Stack](./stack)
11-
* [How to](./how-to)
12-
* [Protocol](./protocol)
13-
* [Communication](./protocol/communication)
14-
* [Accessibility](./protocol/accessibility)
15-
* [Git](./protocol/git)
16-
* [iOS](./protocol/ios)
17-
* [Open Source](./protocol/open-source)
18-
* [Product Review](./protocol/product-review)
19-
* [Rails](./protocol/rails)
20-
* [React](./protocol/react)
21-
* [Security](./security)
22-
* [Style](./style)
23-
* [Web Performance](./web-performance)
24-
* [Working Together](./working-together)
25-
26-
High level guidelines:
27-
28-
* Be consistent.
29-
* Don't rewrite existing code to follow this guide.
30-
* Don't violate a guideline without a good reason.
31-
* A reason is good when you can convince a teammate.
32-
33-
A note on the language:
34-
35-
* "Avoid" means don't do it unless you have good reason.
36-
* "Don't" means there's never a good reason.
37-
* "Prefer" indicates a better option and its alternative to watch out for.
38-
* "Use" is a positive instruction.
39-
40-
Contributing
41-
------------
5+
Guides for working together, getting things done, programming well, and programming in style.
6+
7+
## High level guidelines
8+
9+
- Be consistent.
10+
- Don't rewrite existing code to follow this guide.
11+
- Don't violate a guideline without a good reason.
12+
- A reason is good when you can convince a teammate.
13+
14+
## A note on the language
15+
16+
- "Avoid" means don't do it unless you have good reason.
17+
- "Don't" means there's never a good reason.
18+
- "Prefer" indicates a better option and its alternative to watch out for.
19+
- "Use" is a positive instruction.
20+
21+
## Guides by category
22+
23+
- [thoughtbot Tech Stack](/tech-stack/)
24+
- [General](/general/)
25+
26+
### Collaboration
27+
28+
- [Code Review](/code-review/)
29+
- [Communication](/communication/)
30+
- [Inclusive Culture](/inclusive-culture/)
31+
- [Open Source](/open-source/)
32+
- [Product Review](/product-review/)
33+
- [Working Together](/working-together/)
34+
35+
### Protocols
36+
37+
- [Accessibility](/accessibility/)
38+
- [Data](/data/)
39+
- [Email](/email/)
40+
- [Object-Oriented Design](/object-oriented-design/)
41+
- [Security](/security/)
42+
- [Web](/web/)
43+
- [Web Performance](/web-performance/)
44+
45+
### Languages
46+
47+
- [Bash](/bash/)
48+
- [CoffeeScript](/coffeescript/)
49+
- [CSS](/css/)
50+
- [Elixir](/elixir/)
51+
- [ERB](/erb/)
52+
- [HAML](/haml/)
53+
- [Handlebars](/handlebars/)
54+
- [Haskell](/haskell/)
55+
- [HTML](/html/)
56+
- [Java](/java/)
57+
- [JavaScript](/javascript/)
58+
- [Objective-C](/objective-c/)
59+
- [Python](/python/)
60+
- [Ruby](/ruby/)
61+
- [SASS](/sass/)
62+
- [Scala](/scala/)
63+
- [Shell](/shell/)
64+
- [Swift](/swift/)
65+
- [TypeScript](/typescript/)
66+
67+
### Frameworks and platforms
68+
69+
- [Android](/android/)
70+
- [Angular](/angular/)
71+
- [Ember](/ember/)
72+
- [iOS](/ios/)
73+
- [Rails](/rails/)
74+
- [React](/react/)
75+
- [Testing with Jest](/testing-jest/)
76+
- [Testing with RSpec](/testing-rspec/)
77+
78+
### Tools
79+
80+
- [Git](/git/)
81+
- [GraphQL](/graphql/)
82+
- [Postgres](/postgres/)
83+
- [Relational Databases](/relational-databases/)
84+
85+
## Contributing
4286

4387
Please read the [contribution guidelines] before submitting a pull request.
4488

45-
In particular: **if you have commit access, please don't merge changes without
46-
waiting a week for everybody to leave feedback**.
89+
In particular: **if you have commit access, please don't merge changes without waiting a week for everybody to leave
90+
feedback**.
4791

4892
[contribution guidelines]: /CONTRIBUTING.md
4993

50-
Credits
51-
-------
94+
## Credits
5295

5396
Thank you, [contributors](https://github.com/thoughtbot/guides/graphs/contributors)!
5497

5598
![thoughtbot](http://presskit.thoughtbot.com/images/thoughtbot-logo-for-readmes.svg)
5699

57100
Guides is maintained by [thoughtbot, inc](https://thoughtbot.com).
58101

59-
License
60-
-------
102+
## License
61103

62-
Guides is © 2020 thoughtbot, inc. It is distributed under the [Creative Commons
63-
Attribution License](http://creativecommons.org/licenses/by/3.0/).
104+
Guides is © 2020 thoughtbot, inc. It is distributed under the
105+
[Creative Commons Attribution License](http://creativecommons.org/licenses/by/3.0/).
64106

65107
The names and logos for thoughtbot are trademarks of thoughtbot, inc.

‎_template/README.md

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Template
2+
3+
In a sentence or two, describe what this guide is about. A guide can be about a programming language or framework, a design or development tool, or an entirely non-technical topic.
4+
5+
## Best Practices
6+
7+
In this section (or as many sections as you need) convey the best practices around the topic of the guide.
8+
9+
This typically takes one of three forms:
10+
11+
1. A section or sections with lists of specific [guidelines]
12+
2. Primarily textual sections
13+
3. A combination of both
14+
15+
[guidelines]: /README.md#a-note-on-the-language
16+
17+
## How to...
18+
19+
This section, if applicable, should index a list of "How-to" guides for this guide's topic. These should be stored relative to this `README.md` file in a folder named `how-to`.
20+
21+
Here are some examples:
22+
23+
- [Do something](./how-to/do-something.md)
24+
- [Do something else](./how-to/do-something-else.md)

‎_template/how-to/do-something-else.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## How to Do Something Else
2+
3+
This is an example how-to guide. Write anything you want here!

‎_template/how-to/do-something.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## How to Do Something
2+
3+
This is an example how-to guide. Write anything you want here!

‎protocol/accessibility/README.md ‎accessibility/README.md

File renamed without changes.

‎android/README.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Android
2+
3+
In addition to [java](/java/) best practices:
4+
5+
- Properties of views should be alphabetized, with the exception of `id`, `layout_width`, and `layout_height` which
6+
should be placed first in that order.

‎style/android/android_layout.xml ‎android/android_layout.xml

File renamed without changes.

‎angular/README.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
Angular
2+
-------
3+
4+
* [Avoid manual dependency annotations][annotations]. Disable mangling or use a
5+
[pre-processor][ngannotate] for annotations.
6+
* Prefer `factory` to `service`. If you desire a singleton, wrap the singleton
7+
class in a factory function and return a new instance of that class from the
8+
factory.
9+
* Prefer the `translate` directive to the `translate` filter for [performance
10+
reasons][angular-translate].
11+
* Don't use the `jQuery` or `$` global. Access jQuery via `angular.element`.
12+
13+
[annotations]: http://robots.thoughtbot.com/avoid-angularjs-dependency-annotation-with-rails
14+
[ngannotate]: https://github.com/kikonen/ngannotate-rails
15+
[angular-translate]: https://github.com/angular-translate/angular-translate/wiki/Getting-Started#using-translate-directive

‎bash/README.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
## Bash
2+
3+
In addition to [shell](/shell/) best practices:
4+
5+
- Prefer `${var,,}` and `${var^^}` over `tr` for changing case.
6+
- Prefer `${var//from/to}` over `sed` for simple string replacements.
7+
- Prefer `[[` over `test` or `[`.
8+
- Prefer process substitution over a pipe in `while read` loops.
9+
- Use `((` or `let`, not `$((` when you don't need the result

0 commit comments

Comments
 (0)