Creates a guide-template to update all guides from #2

Open
wants to merge 7 commits into
base: master
from

Reformat markdown and trim down from rails heroku

- Reformat markdown properly.
 - Splats * for list items not dashes.
 - Wrap to 80 chars.
- Trims some content from rails heroku setup guide, keeping just enough to have
some clear examples of what sections look like. The rails heroku setup guide is
one of our cleanest with the most consistent style, hence it's being used to
create this guide template.
  • Loading branch information...
bengitscode committed Dec 11, 2017
commit 05c8a88e79c7c06de42437862764f518c0131cae
Copy path View file
201 README.md
@@ -2,56 +2,75 @@

# Guide Template

Use this template to structure your READMEs for guides. Remove text from this section, or use it to frame the guide. Good framing answers the question "Why am I learning/doing this?".
Use this template to structure your READMEs for guides. Remove text from this
section, or use it to frame the guide. Good framing answers the question "Why am
I learning/doing this?".

Be sure to include a recent LICENSE and Markdown linter configuration (.remarkrc). Also, include an appropriate .gitignore; these are usually found in specific technology templates, for example js-template.
Be sure to include a recent LICENSE and Markdown linter configuration
(.remarkrc). Also, include an appropriate .gitignore; these are usually found in
specific technology templates, for example js-template.

## Prerequisites

- [ga-wdi-boston/rails-api](https://github.com/ga-wdi-boston/rails-api)
- [ga-wdi-boston/rails-activerecord-crud](https://github.com/ga-wdi-boston/rails-activerecord-crud)
- This guide assumes you have followed [these installation instructions](https://github.com/ga-wdi-boston/rails-api-template#installation) unequivocally.
* [ga-wdi-boston/rails-api](https://github.com/ga-wdi-boston/rails-api)
* [ga-wdi-boston/rails-activerecord-crud](https://github.com/ga-wdi-boston/rails-activerecord-crud)
* This guide assumes you have followed
[these installation instructions](https://github.com/ga-wdi-boston/rails-api-template#installation)
unequivocally.

## Objectives

- What should developers accomplish by following this guide.
- Write objectives that focus on demonstrating knowledge.
- Write learning objectives that begin with an [imperative
verb](https://en.wikipedia.org/wiki/Imperative_mood).
- Avoid objectives that start with "Use" or "Understand".
- Rewrite objecives that begin with "Use" by inverting sentence structure.
- End each objective with a period.

* What should developers accomplish by following this guide.
* Write objectives that focus on demonstrating knowledge.
* Write learning objectives that begin with an
[imperative verb](https://en.wikipedia.org/wiki/Imperative_mood).
* Avoid objectives that start with "Use" or "Understand".
* Rewrite objecives that begin with "Use" by inverting sentence structure.
* End each objective with a period.

## Preparation

Often there will be setup instructions preceding the core objectives of the setup guide, such as `create an account on foo or bar`
The following is an example using heroku.
Often there will be setup instructions preceding the core objectives of the
setup guide, such as `create an account on foo or bar` The following is an
example using heroku.

1 **Create a Heroku account**, at
[https://www.heroku.com](https://www.heroku.com). You will be sent an activation
email, so be sure to check your inbox so that you can activate your account.

1 **Create a Heroku account**, at [https://www.heroku.com](https://www.heroku.com).
You will be sent an activation email, so be sure to check your inbox so that
you can activate your account.
1. Install the Heroku Command Line Tools: run `brew install heroku`.
1. **Log into Heroku** by running `heroku login` from the console and providing
your Heroku credentials when asked. Once you log in, if you're prompted
to add these credentials to your keychain, say yes. *You will not be able*
*to see your password*
your Heroku credentials when asked. Once you log in, if you're prompted to
add these credentials to your keychain, say yes. _You will not be able_ _to
see your password_

## Checklist

### Checklist
Each step for guide should be represented in here as a checklist item and below
this checklist as an individual third-level header.

Each step for guide should be represented in here as a checklist item and below this checklist
as an individual third-level header.
* [x] [Inital](#push-master-to-heroku)
* [ ] [Homebrew](#update-herokus-database)
* [ ] [Node](node.md)
* [ ] [Ruby](ruby.md)
* [ ] [PostgreSQL](postgres.md)
* [ ] [Atom](atom.md)
* [ ] [Chrome](chrome.md)

- [x] [Github and Initial Setup](github.md)
- [ ] [Homebrew](homebrew.md)
- [ ] [Node](node.md)
- [ ] [Ruby](ruby.md)
- [ ] [PostgreSQL](postgres.md)
- [ ] [Atom](atom.md)
- [ ] [Chrome](chrome.md)
### Setup Guide: Checklist

Provide checklist of steps outlined above.

### Push `master` to Heroku
* [ ] Checklist should read as a concise list
* [ ] Push your latest code to Heroku (`git push heroku master`)
* [ ] Update your heroku database by telling Heroku to run your migration files
(`heroku run rake db:migrate`). If you have any other rake tasks that need
to run (e.g. `rake db:seed`), run those with `heroku run` as well.
* [ ] Set your secrets. (Either by using the [command line](#set-your-secrets)
or by using the heroku app panel in your browser) [ ] Check your work by
restarting heroku and opening your heroku application.

## Push `master` to Heroku

Only keep clean, working code on `master`. After you complete a feature merge it
onto `master`. Push your updated `master` to GitHub, then to Heroku.
@@ -111,7 +130,12 @@ You'll probably see something like this:

That's normal, **unless** you have defined a root route.

### Change Your App's Name (optional)
### Change Your App's Name (optional/additional)

Any optional steps should be included at the end of the checklist.
Optional/additional steps could include renaming a deployed application, how to
redeploy, or any additional information the developers should be aware of going
forward.

If you wish you can rename your app at any time. It must be unique across all
apps deployed to heroku.
@@ -123,98 +147,45 @@ heroku apps:rename newname
Your app will become immediately available at it's new subdomain,
`newname.herokuapp.com`.

## Heroku Command Reference

A full list of Heroku commands can be access by running `heroku --help`; below
are some of the more common ones.

| Commands | Behavior |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `heroku apps:info` | Get info about ALL of our Heroku apps. |
| `heroku apps:info --app {name_of_app}` | Get info about a specific Heroku app. |
| `heroku apps:open --app {name_of_app}` | Open any given Heroku app <br> (other than the one we're currently working with.) |
| `heroku logs` | Logs from the currently running app. |
| `heroku ps` | Processes running in your heroku application. |
| `heroku releases` | Each time you deploy to heroku you are creating a "release". This command shows all releases. |
| `heroku pg:info` | Access Postgres from within Heroku and show the heroku plan, connections, pg version, data size, tables. |
| `heroku pg:psql` | ... and open a `psql` console. |
| `heroku run ...` | Run a program from within Heroku. |
| `heroku config` | Environmental variables in your current Heroku app. |
| `heroku config:set SECRET_KEY_BASE=$(rake secret)` | Set Secret Key |
| `heroku config:set SECRET_TOKEN=$(rake secret)` | Set TOKEN |
| `heroku config:set CLIENT_ORIGIN=https://yourgithubname.github.io` | Set CLIENT_ORIGIN |
| `heroku apps:rename newname (optional)` | Rename heroku app name (entirely optional) |
| `heroku restart` | restart heroku |
| `heroku open` | Open your heroku app in default browser |
| `heroku --help` | Displays a heroku CLI usage summary. |


## WARNING: Ephemeral Filesystem.

One serious limitation of Heroku is that it provides an 'ephemeral filesystem';
in other words, if you try to save a new file inside the repo (e.g. an uploaded
image file), it will disappear when your app is restarted or redeployed.

As an example, try running the following commands:

```sh
heroku run bash
touch happy.txt; echo 'is happy' > happy.txt
cat happy.txt
```

Then, hit Ctrl-D to get out of heroku bash shell. If you re-open the shell and
run `ls -l`, `happy.txt` will be missing!

The typical workaround is to save files in cloud storage such as [Amazon
S3](https://aws.amazon.com/s3/); more on this in the near future.

<img width="400" alt="herokuapp_png_1_366x768_pixels" src="http://www.thehinzadventures.com/wp-content/uploads/2015/03/54843046.jpg">

## Setup Guide: Checklist

Provide checklist of steps outlined above.

- [ ] Run `heroku create` in the command line in the root of your Rails API to create a new (blank) app on Heroku.
- [ ] Push your latest code to Heroku (`git push heroku master`)
- [ ] Update your heroku database by telling Heroku to run your migration files (`heroku run rake db:migrate`).
If you have any other rake tasks that need to run (e.g. `rake db:seed`), run
those with `heroku run` as well.
- [ ] Set your secrets. (Either by using the [command line](#set-your-secrets) or by using the
heroku app panel in your browser)
[ ] Check your work by restarting heroku and opening your heroku application.


## Troubleshooting

Provide troubleshooting resources/gotchas if needed.

These are the commands required for deploying to heroku with rails. If your heroku deployment isn't working as expected, review these steps carefully.
This can ve a review of the steps made in guide, suggested troubleshooting
steps, or common commands used to debug the guide's focus.

The following is an example from the
[Heroku Rails Setup Guide](https://git.generalassemb.ly/ga-wdi-boston/rails-heroku-setup-guide):

These are the commands required for deploying to heroku with rails. If your
heroku deployment isn't working as expected, review these steps carefully.

- `heroku create`
- `git push heroku master`
- `heroku run rake db:migrate`
- `heroku run rake db:seed`
- `heroku config:set SECRET_KEY_BASE=$(rake secret)`
- `heroku config:set SECRET_TOKEN=$(rake secret)`
- `heroku config:set CLIENT_ORIGIN=https://yourgithubname.github.io`
- `heroku apps:rename newname` (optional)
- `heroku restart`
- `heroku open`
* `heroku create`
* `git push heroku master`
* `heroku run rake db:migrate`
* `heroku run rake db:seed`
* `heroku config:set SECRET_KEY_BASE=$(rake secret)`
* `heroku config:set SECRET_TOKEN=$(rake secret)`
* `heroku config:set CLIENT_ORIGIN=https://yourgithubname.github.io`
* `heroku apps:rename newname` (optional)
* `heroku restart`
* `heroku open`

## Additional Resources

- Any useful links should be included in the talk material where the link is
first referenced.
- Additional links for further study or exploration are appropriate in this
section.
- Links to relevant resources or documentation not included in the guide, or tools tangentially used but not part of the focus of the guide/task are also appropriate.
- Examples:
- [Heroku Command Line](https://devcenter.heroku.com/categories/command-line)
- [Heroku Rails Deployment](https://devcenter.heroku.com/articles/getting-started-with-rails5)
* Any useful links should be included in the talk material where the link is
first referenced.
* Additional links for further study or exploration are appropriate in this
section.
* Links to relevant resources or documentation not included in the guide, or
tools tangentially used but not part of the focus of the guide/task are also
appropriate.
* Examples:
* [Heroku Command Line](https://devcenter.heroku.com/categories/command-line)
* [Heroku Rails Deployment](https://devcenter.heroku.com/articles/getting-started-with-rails5)

## [License](LICENSE)

1. All content is licensed under a CC­BY­NC­SA 4.0 license.
1. All software code is licensed under GNU GPLv3. For commercial use or
alternative licensing, please contact legal@ga.co.
alternative licensing, please contact legal@ga.co.
ProTip! Use n and p to navigate between commits in a pull request.