Skip to content

Commit 8f73c48

Browse files
khin-alukhin-alu
committed
Improve the README
1 parent 81cbf96 commit 8f73c48

File tree

2 files changed

+179
-13
lines changed

2 files changed

+179
-13
lines changed

‎HELP.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Rails Tutorial Help
2+
3+
This is the Help page for the [*Ruby on Rails Tutorial*](https://www.railstutorial.org/) (8th Edition).
4+
See also the [7th edition Help page](https://github.com/learnenough/sample_app_7th_ed/blob/main/HELP.md).
5+
6+
## General suggestions
7+
8+
Web development is a tricky business, and despite our collective best efforts it’s likely that you’ll run into trouble at some point. If you do, I suggest comparing your code to the [reference implementation of the sample app](https://github.com/learnenough/rails_tutorial_sample_app_8th_ed) to track down any discrepancies. You can also post your question at [Stack Overflow](https://stackoverflow.com/), but I suggest you do so after trying all the debugging tips listed below.
9+
10+
## Debugging tips
11+
12+
While it’s impossible to anticipate every potential problem, here are
13+
some debugging tips that might help:
14+
15+
- Have you compared your code to the [reference implementation of the sample app](https://github.com/mhartl/rails_tutorial_sample_app_8th_ed)?
16+
- Are you using the exact gem versions (including Rails) used in the
17+
tutorial?
18+
- Did you try Googling the error message?
19+
- Did you stop the Rails web server (with Ctrl-C) and restart?
20+
- Did you try stopping Spring using `bin/spring stop`?
21+
- Did you copy-and-paste from the book’s code? (Experience shows that typing in code, while a better learning technique in general, is error-prone, so when in doubt be sure to copy all code exactly.)
22+
- Did you try Googling the error message?
23+
- Did you re-run `bundle install`?
24+
- Did you try running `bundle update`?
25+
- Did you examine the Heroku logs using `heroku logs` or `heroku logs --tail`?
26+
- Did you make sure the `sqlite3` gem is listed only in the `development` and `test` environments in the `Gemfile`?
27+
- Did you look for the answer at Stack Overflow?
28+
- Did you try Googling the error message?
29+
30+
If your problem is of a general nature, such as having issues installing
31+
Rails or configuring your system, I suggest posting to [Stack
32+
Overflow](https://stackoverflow.com/). This will allow other
33+
people running into your issue (and not just those following the Rails
34+
Tutorial) to benefit from the discussion. For issues
35+
deploying to [Heroku](https://heroku.com/), please contact [Heroku
36+
technical support](https://support.heroku.com/).
37+
38+
When asking your question on any mailing list or forum, be sure to
39+
include as much relevant information as possible. To maximize your chances
40+
of a helpful reply, I especially recommend the article [How To Ask Questions The Smart
41+
Way](http://www.catb.org/esr/faqs/smart-questions.html) by [Eric
42+
Raymond](http://www.catb.org/esr/).
43+
44+
## Error reports
45+
46+
Suspected errors, typos, and bugs can be emailed to <michael@learnenough.com>. All such reports are gratefully received, but please double-check with the [online version of the tutorial](https://www.railstutorial.org/book) and the [reference implementation](https://github.com/learnenough/rails_tutorial_sample_app_7th_ed) before submitting.

‎README.md‎

Lines changed: 133 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,144 @@
1-
# README
1+
# Ruby on Rails Tutorial sample application
22

3-
This README would normally document whatever steps are necessary to get the
4-
application up and running.
3+
This is the sample application for the
4+
[_Ruby on Rails Tutorial:
5+
Learn Web Development with Rails_](https://www.railstutorial.org/)
6+
by [Michael Hartl](https://www.michaelhartl.com/).
57

6-
Things you may want to cover:
8+
See also the [7th edition README](https://github.com/learnenough/rails_tutorial_sample_app_7th_ed/blob/main/README.md).
79

8-
* Ruby version
10+
## License
911

10-
* System dependencies
12+
All source code in the [Ruby on Rails Tutorial](https://www.railstutorial.org/)
13+
is available jointly under the MIT License and the Beerware License. See
14+
[LICENSE.md](LICENSE.md) for details.
1115

12-
* Configuration
16+
## Getting started
1317

14-
* Database creation
18+
To get started with the app, clone the repo and then install the needed gems. You can clone the repo as follows:
1519

16-
* Database initialization
20+
```
21+
$ git clone https://github.com/learnenough/rails_tutorial_sample_app_8th_ed
22+
$ cd rails_tutorial_sample_app_8th_ed/
23+
```
1724

18-
* How to run the test suite
25+
To install the gems, you will need the same versions of Ruby and Bundler used to build the sample app, which you can find using the `cat` and `tail` commands as follows:
1926

20-
* Services (job queues, cache servers, search engines, etc.)
27+
```
28+
$ cat .ruby-version
29+
<Ruby version number>
30+
$ tail -n1 Gemfile.lock
31+
<Bundler version number>
32+
```
2133

22-
* Deployment instructions
34+
Next, install the versions of `ruby` and the `bundler` gem from the above commands. The Ruby installation is system-dependent; on the cloud IDE recommended in the tutorial, it can be installed as follows:
2335

24-
* ...
36+
```
37+
$ rvm get stable
38+
$ rvm install <Ruby version number>
39+
$ rvm --default use <Ruby version number>
40+
```
41+
42+
See the section [Up and running](https://www.learnenough.com/ruby-on-rails-7th-edition-tutorial#sec-up_and_running) for more details. Once Ruby is installed, the `bundler` gem can be installed using the `gem` command:
43+
44+
```
45+
$ gem install bundler -v <version number>
46+
```
47+
48+
Then the rest of the necessary gems can be installed with `bundle` (taking care to skip any production gems in the development environment):
49+
50+
```
51+
$ bundle _<version number>_ config set --local without 'production'
52+
$ bundle _<version number>_ install
53+
```
54+
55+
Here you should replace `<version number>` with the actual version number. For example, if `<version number>` is `2.6.7`, then the commands should look like this:
56+
57+
```
58+
$ gem install bundler -v 2.6.7
59+
$ bundle _2.6.7_ config set --local without 'production'
60+
$ bundle _2.6.7_ install
61+
```
62+
63+
If you run into any trouble, you can remove `Gemfile.lock` and rebundle at any time:
64+
65+
```
66+
$ rm -f Gemfile.lock
67+
$ bundle install
68+
```
69+
70+
Next, migrate the database:
71+
72+
```
73+
$ rails db:migrate
74+
```
75+
76+
Finally, run the test suite to verify that everything is working correctly:
77+
78+
```
79+
$ rails test
80+
```
81+
82+
If the test suite passes, you’ll be ready to seed the database with sample users and run the app in a local server:
83+
84+
```
85+
$ rails db:seed
86+
$ rails server
87+
```
88+
89+
Follow the instructions in [Section 1.2.2 `rails server`](https://www.railstutorial.org/book#sec-rails_server) to view the app. You can then register a new user or log in as the sample administrative user with the email `example@railstutorial.org` and password `foobar`.
90+
91+
## Deploying
92+
93+
To deploy the sample app to production, you’ll need a Heroku account as discussed [Section 1.4 Deploying](https://www.railstutorial.org/book/beginning#sec-deploying).
94+
95+
The full production app includes several advanced features, including sending email with [SendGrid](https://sendgrid.com/) and storing uploaded images with [AWS S3](https://aws.amazon.com/s3/). As a result, deploying the full sample app can be rather challenging. The suggested method for testing a deployment is to use the branch for Chapter 10 (“Updating users”), which doesn’t require more advanced settings but still includes sample users.
96+
97+
To deploy this version of the app, you’ll need to create a new Heroku application, switch to the right branch, push up the source, run the migrations, and seed the database with sample users:
98+
99+
```
100+
$ heroku create
101+
$ git checkout updating-users
102+
$ git push heroku updating-users:main
103+
$ heroku run rails db:migrate
104+
$ heroku run rails db:seed
105+
```
106+
107+
Visiting the URL returned by the original `heroku create` should now show you the sample app running in production. As with the local version, you can then register a new user or log in as the sample administrative user with the email `example@railstutorial.org` and password `foobar`.
108+
109+
## Branches
110+
111+
The reference app repository includes a separate branch for each chapter in the tutorial (Chapters 3–14). To examine the code as it appears at the end of a particular chapter (with some slight variations, such as occasional exercise answers), simply check out the corresponding branch using `git checkout`:
112+
113+
```
114+
$ git checkout <branch name>
115+
```
116+
117+
A full list of branch names appears as follows (preceded the number of the corresponding chapter in the book):
118+
119+
```
120+
3. static-pages
121+
4. rails-flavored-ruby
122+
5. filling-in-layout
123+
6. modeling-users
124+
7. sign-up
125+
8. basic-login
126+
9. advanced-login
127+
10. updating-users
128+
11. account-activation
129+
12. password-reset
130+
13. user-microposts
131+
14. following-users
132+
```
133+
134+
For example, to check out the branch for Chapter 7, you would run this at the command line:
135+
136+
```
137+
$ git checkout sign-up
138+
```
139+
140+
## Help with the Rails Tutoiral
141+
142+
Experience shows that comparing code with the reference app is often helpful for debugging errors and tracking down discrepancies. For additional assistance with any issues in the tutorial, please consult the [Rails Tutorial Help page](https://github.com/learnenough/rails_tutorial_sample_app_7th_ed/blob/main/HELP.md).
143+
144+
Suspected errors, typos, and bugs can be emailed to <michael@learnenough.com>. All such reports are gratefully received, but please double-check with the [online version of the tutorial](https://www.railstutorial.org/book) and this reference app before submitting.

0 commit comments

Comments
 (0)