Markdown Formatting “Best Practices”

adminBest Practices0 Comments

Markdown Formatting Best Practices

Using Markdown is essential for clear communication on mediums such as GitHub, Slack or just plan text. Here are some of our recommendations on when to use certain conventions.

Code Blocks

Use code blocks for anything more than 1 line. Use `code` for inline code, filenames, commands, etc.

```
# This is a code block
```

Tables

Use tables to communicate lists of options. 

:--------: should be used for “Default” and “Required” values

:--------- should be used for all other columns

Use  ``  for empty defaults

Use `value`for all values

Here's an example:

|  Name       |  Default |  Description                                  | Required |
|:------------|:--------:|:----------------------------------------------|:--------:|
| namespace   | ``       | Namespace (e.g. `cp` or `cloudposse`)         | Yes      |
| stage       | ``       | Stage (e.g. `prod`, `dev`, `staging`)         | Yes      |
| name        | ``       | Name  (e.g. `bastion` or `db`)                | Yes      |
| attributes  | []       | Additional attributes (e.g. `policy`)         | No       |
| tags        | {}       | Additional tags  (e.g. `map("Foo","XYZ")`)    | No       |

Which will render to something like this:

Features 

Use this format describe the features & benefits.

```
1. **Feature 1** - Explanation of benefits
2. **Feature 2** - Explanation of benefits
```

Quotes

Reference copyrighted text, quotes, and other unoriginal copy using `> `

```
> Amazon Simple Storage Service (Amazon S3) makes it simple and practical to collect, store, and analyze data - regardless of format – all at massive scale.
```

GitHub Repository “Best Practices”

adminBest Practices0 Comments

GitHub Repository Best Practices

Create a New Repository

1. Always initialize repository with a README.md and .gitignore

2. If it's an Open Source project, initialize it with the APACHE2 license

3. Update LICENSE file (if applicable)


Copyright {yyyy} {name of copyright owner}
should be
Copyright 2018 Cloud Posse, LLC

4. Set a meaningful Description that describes the purpose repository

4. Add some useful tags to help discovery of the project

5. Submit all new work as PR.

6. Create new label wip for “Work in Progress”

Repository Settings

  • Disable “Merge Commit” and disable “Rebase Merging”
  • Enable Branch Protections

IMPORTANT: If CI enabled then require status checks to pass.