Improvements on dev docs (#2616)
* Correct installation documentation * Add stylized titles * Add some changes to the getting started documentation * Add changes for the backend guide * Add changes for the design guide * Add testing / Q&A guide improvements * Minor fixes to contributing docs * More improvements to the general doc * Improvements for frontend guide
This commit is contained in:
rhymes
Ben Halpern
parent
4b91dd5912
commit
9210f6793b
47 changed files with 568 additions and 372 deletions
|
|
@ -9,7 +9,7 @@
|
|||
"target": "_blank"
|
||||
},
|
||||
{
|
||||
"title": "dev.to",
|
||||
"title": "DEV",
|
||||
"href": "https://dev.to",
|
||||
"target": "_blank"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -2,6 +2,27 @@
|
|||
title: Admin Panel
|
||||
---
|
||||
|
||||
# Acessing the Admin Panel
|
||||
# Accessing the admin panel
|
||||
|
||||
There is an admin panel located at `/admin`. To access this admin panel, you must use `pudit` to give a user the `admin` role.
|
||||
There is an admin panel located at <http://localhost:3000/admin>.
|
||||
|
||||
To access the panel, you must be logged with a user with the `admin` role activated.
|
||||
|
||||
To activate such a role, you can follow these instructions:
|
||||
|
||||
- open the Rails console
|
||||
|
||||
```shell
|
||||
rails console
|
||||
```
|
||||
|
||||
1. load the user object of for _bob_ (or whatever the username is)
|
||||
|
||||
```ruby
|
||||
Loading development environment (Rails 5.2.3)
|
||||
[1] pry(main)> user = User.find_by(username: "bob")
|
||||
[2] pry(main)> user.add_role(:admin)
|
||||
[3] pry(main)> user.save!
|
||||
```
|
||||
|
||||
Now you'll be able to access the [administration panel](http://localhost:3000/admin).
|
||||
|
|
|
|||
|
|
@ -2,43 +2,49 @@
|
|||
title: Algolia
|
||||
---
|
||||
|
||||
# Algolia for Search and Caching
|
||||
# Algolia for Search
|
||||
|
||||
Algolia is a third party service which powers the search and is a caching layer for various endpoints. When working with the API is very likely would need to utilize Algolia. You will need to sign up for a free-tier account, retrieve the keys and provide those keys to the Rails application.
|
||||
Algolia is a third party service which powers the search. When working with the API is very likely would need to utilize Algolia. You will need to sign up for a free-tier account, retrieve the keys and provide those keys to the Rails application.
|
||||
|
||||
## Algolia: Sign up
|
||||
## Sign up
|
||||
|
||||
1. Go to the Algolia sign up [page](https://www.algolia.com/apps/AJVD3Q9KL3/dashboard).
|
||||
|
||||
2. Choose one of the three methods of signing up. (email, github or google)
|
||||
2. Choose one of the three methods of signing up: email, github or google.
|
||||
|
||||
3. Fill in your information.
|
||||
|
||||
|
||||
|
||||
4. Select the datacenter's region.
|
||||
|
||||
|
||||
|
||||
5. Fill in or skip the project information.
|
||||
|
||||
|
||||
|
||||
6. You are all set up now! You can go to your dashboard.
|
||||
|
||||
|
||||
|
||||
7. You can skip the tutorial, we will guide you through the process. Accept the [Terms and Conditions](https://www.algolia.com/policies/terms).
|
||||
|
||||
|
||||
|
||||
8. All good! You can get your API keys now.
|
||||
|
||||
## Algolia: Get API keys
|
||||
## Get API keys
|
||||
|
||||
1. [Sign up](#algolia-sign-up) or [Sign in](https://www.algolia.com/users/sign_in) to your Algolia account.
|
||||
|
||||
2. From your **Dashboard**, click on **API Keys**.
|
||||
|
||||
|
||||
|
||||
3. Change your keys accordingly (name of Algolia key -> name of our `ENV` variable):
|
||||
|
||||
```
|
||||
```text
|
||||
Application ID -> ALGOLIASEARCH_APPLICATION_ID
|
||||
Search-Only API Key -> ALGOLIASEARCH_SEARCH_ONLY_KEY
|
||||
Admin API KEY -> ALGOLIASEARCH_API_KEY
|
||||
|
|
|
|||
|
|
@ -4,16 +4,17 @@ title: GitHub Authentication
|
|||
|
||||
# GitHub App and Authentication
|
||||
|
||||
Dev.to allows you to authenticate using Github. To use this authentication method in local development, you will need to set up a GitHub App and retrieves keys. Then you'll need to provide theses keys to the Rails application.
|
||||
DEV allows you to authenticate using GitHub. To use this authentication method in local development, you will need to set up a GitHub App and retrieve its keys. Then you'll need to provide these keys to the Rails application.
|
||||
|
||||
1. [Sign in](https://github.com/settings/applications/new) in your GitHub account.
|
||||
|
||||
2. Fill in the form with an application name, descriptions and URLs `http://localhost:3000/`. Replace the `3000` port if you run DEV on other port.
|
||||
2. Fill in the form with an application name, description and the URL `http://localhost:3000/`. Replace the port `3000` if you run DEV on another port.
|
||||
|
||||
|
||||
|
||||
3. You will be redirected in the app's **Developer settings**. Here you will find the keys. Change them accordingly (name of Github key -> name of our `ENV` variable):
|
||||
3. You will be redirected in the app's **Developer settings**. Here you will find the keys. Change them accordingly (name of GitHub key -> name of our `ENV` variable):
|
||||
|
||||
```
|
||||
```text
|
||||
Client ID -> GITHUB_KEY
|
||||
Client Secret -> GITHUB_SECRET
|
||||
```
|
||||
|
|
@ -21,12 +22,14 @@ Dev.to allows you to authenticate using Github. To use this authentication metho
|
|||
|
||||
|
||||
4. You will need a personal token as well. From the same dashboard, navigate to **Personal access tokens** and generate a new token.
|
||||
|
||||
|
||||
|
||||
5. Fill in the token description and generate the token.
|
||||
|
||||
6. Be sure that you copy the token right away, because it is the only time you will see it. Change it accordingly.
|
||||
|
||||
```
|
||||
```shell
|
||||
Personal access tokens -> GITHUB_TOKEN
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,35 +1,40 @@
|
|||
---
|
||||
title: Twitter Authenication
|
||||
title: Twitter Authentication
|
||||
---
|
||||
|
||||
# Twitter App and Authentication
|
||||
|
||||
Dev.to allows you to authenicate using Twitter. In order to use this authenication method in local development you will need to setup a Twitter App and retrieves keys. Then you'll need to provide theses keys to the Rails application.
|
||||
DEV allows you to authenticate using Twitter. In order to use this authentication method in local development you will need to setup a Twitter App and retrieve its keys. Then you'll need to provide these keys to the Rails application.
|
||||
|
||||
## Twitter: Sign up
|
||||
## Sign up
|
||||
|
||||
1. [Sign in](https://developer.twitter.com/apps) to your Twitter account.
|
||||
|
||||
2. In order to get the API keys, you will have to apply for a developer account. Click the **Apply** button.
|
||||
|
||||
|
||||
|
||||
3. Setup your Twitter account. Be sure you have your phone number and email address filled in.
|
||||
|
||||
|
||||
|
||||
4. Fill in your account information and give a name to your **developer account**.
|
||||
|
||||
|
||||
|
||||
5. Write down the reasons that you want to use Twitter API. Mention DEV community and describe the issues and tests and things that you want to work on. Copy it, you might use it later ;)
|
||||
5. Write down the reasons that you want to use Twitter API. Mention DEV's community and describe the issues and tests and things that you want to work on. Copy it, you might use it later ;)
|
||||
|
||||
|
||||
|
||||
6. Read :) and accept the Terms and Conditions.
|
||||
|
||||
|
||||
|
||||
7. Verify your email address once more and you will be done.
|
||||
|
||||
8. You are done.
|
||||
|
||||
## Twitter: Get API keys
|
||||
## Get API keys
|
||||
|
||||
1. [Sign up](#twitter-sign-up) or [sign in](https://developer.twitter.com/apps) to your Twitter developer account.
|
||||
|
||||
|
|
@ -37,27 +42,34 @@ Dev.to allows you to authenicate using Twitter. In order to use this authenicati
|
|||
|
||||
|
||||
3. Fill in the app name, description and URL `https://dev.to`.
|
||||
|
||||
|
||||
|
||||
4. Check the **Enable Sign in with Twitter** option and fill in the Callback URL `http://localhost:3000/users/auth/twitter/callback` (or whatever port you run DEV on).
|
||||
|
||||
|
||||
|
||||
5. Fill in the DEV information, **Terms of Service** `http://dev.to/terms` and **Privacy policy** `http://dev.to/privacy`.
|
||||
|
||||
|
||||
|
||||
6. Write down (or paste) the things that you will work on. Press **Create**.
|
||||
|
||||
|
||||
|
||||
7. Review the [Twitter Developer Terms](https://developer.twitter.com/en/developer-terms/agreement-and-policy.html) and agree to do nothing sketchy.
|
||||
|
||||
|
||||
|
||||
8. The app is all set!
|
||||
|
||||
9. One more change... From the app dashboard go to **Permissions** and check **Request email addresses from users** option.
|
||||
|
||||
|
||||
|
||||
10. From the same dashboard access the **Keys and tokens** and change them accordingly (name of Twitter key -> name of our `ENV` variable):
|
||||
|
||||
```
|
||||
```text
|
||||
API key -> TWITTER_KEY
|
||||
API secret key -> TWITTER_SECRET
|
||||
Access Token -> TWITTER_ACCESS_TOKEN
|
||||
|
|
|
|||
|
|
@ -4,9 +4,9 @@ title: Authentication
|
|||
|
||||
# Authentication
|
||||
|
||||
Authenication is handled by [Devise](https://github.com/plataformatec/devise) and [OmniAuth](https://github.com/omniauth/omniauth)
|
||||
Authentication is handled by [Devise](https://github.com/plataformatec/devise) and [OmniAuth](https://github.com/omniauth/omniauth).
|
||||
|
||||
On DEV.to you can only authenicate through Github or Twitter. Please check out the respective guides on how to authenicate:
|
||||
On DEV you can only authenticate through GitHub or Twitter. Please check out the respective guides on how to authenticate:
|
||||
|
||||
- [Twitter App and Authenication](/installation/auth-github)
|
||||
- [Github App and Authenication](/installation/auth-twitter)
|
||||
- [Github authentication](/backend/auth-github)
|
||||
- [Twitter authentication](/backend/auth-twitter)
|
||||
|
|
|
|||
|
|
@ -4,12 +4,10 @@ title: Authorization
|
|||
|
||||
# Authorization
|
||||
|
||||
Authorization is handled by the third party gem [pundit](https://github.com/varvet/pundit).
|
||||
Authorization is handled by the third party gem [Pundit](https://github.com/varvet/pundit) through the `authorize` method which you can find in various controllers, look for statements like:
|
||||
|
||||
The policies can be found in `/app/policies`
|
||||
|
||||
Authorization is handled by the `authorize` method which you will find in various controllers
|
||||
|
||||
```rb
|
||||
authorize @user
|
||||
```ruby
|
||||
authorize @user
|
||||
```
|
||||
|
||||
All authorization policies can be found in `/app/policies`.
|
||||
|
|
|
|||
|
|
@ -4,5 +4,6 @@ title: Previewing Emails
|
|||
|
||||
# Previewing emails in development
|
||||
|
||||
You can modify the test in `/test/mailers/previews`
|
||||
You can view the previews at (for example) `http://localhost:3000/rails/mailers/notify_mailer/new_reply_email`
|
||||
You can view email previews at <http://localhost:3000/rails/mailers>.
|
||||
|
||||
Previews are setup in the directory `spec/mailers/previews`.
|
||||
|
|
|
|||
|
|
@ -2,25 +2,27 @@
|
|||
title: Pusher
|
||||
---
|
||||
|
||||
# Pusher - Real-Time Notification
|
||||
# Pusher for Realtime Notifications
|
||||
|
||||
Pusher is third party service being used to power the chat system. When both DEV.to members follow each other they have the ability to use chat and converse with each other.
|
||||
Pusher is a third party service being used to power the [chat system](https://dev.to/connect).
|
||||
|
||||
In order to use the chat functionality within you development enviroment
|
||||
you will need to sign up for a free-tier Pusher account and retrieves
|
||||
keys. Then you'll need to provide those keys to the Rails application.
|
||||
you will need to sign up for a free-tier Pusher account and retrieve
|
||||
its keys. Then you'll need to provide those keys to the Rails application.
|
||||
|
||||
1. [Sign up](https://dashboard.pusher.com/accounts/sign_up) or [sign in](https://dashboard.pusher.com/) to your Pusher account.
|
||||
|
||||
2. Once signed in, fill in the prompt to create a new Pusher Channels app.
|
||||
|
||||
|
||||
|
||||
3. In your new Pusher Channels app, click the "App Keys" tab.
|
||||
|
||||
|
||||
|
||||
4. Change your keys accordingly (name of Pusher key -> name of our application key):
|
||||
|
||||
```
|
||||
```text
|
||||
app_id -> PUSHER_APP_ID
|
||||
key -> PUSHER_KEY
|
||||
secret -> PUSHER_SECRET
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ items:
|
|||
- auth-twitter.md
|
||||
- auth-github.md
|
||||
- authorization.md
|
||||
- aloglia.md
|
||||
- algolia.md
|
||||
- pusher.md
|
||||
- admin.md
|
||||
- previewing-emails.md
|
||||
|
|
|
|||
|
|
@ -18,20 +18,26 @@ For more information on how to use GitDocs read the [GitDocs guide](https://gitd
|
|||
|
||||
Install the [GitDocs NodeJs library](https://www.npmjs.com/package/gitdocs)
|
||||
|
||||
```shell
|
||||
npm install gitdocs -g
|
||||
```
|
||||
|
||||
Specifying `-g` will install the library globally which is what you want to do.
|
||||
|
||||
```
|
||||
npm install gitdocs -g
|
||||
If you use yarn you can instead issue:
|
||||
|
||||
```shell
|
||||
yarn global add gitdocs
|
||||
```
|
||||
|
||||
Once installed, to run gitdocs you need to navigate to the root
|
||||
directory of the DEV.to codebase and run
|
||||
|
||||
```
|
||||
```shell
|
||||
gitdocs serve
|
||||
```
|
||||
|
||||
This will start a server on port `8000`
|
||||
This will start a server where you can browse the documentation: <http://localhost:8000/>
|
||||
|
||||
When you add new markdown pages you'll have to stop and start the
|
||||
websever before you see them.
|
||||
When you add new markdown pages or rename existing ones, you'll have to restart
|
||||
the server before you notice any changes.
|
||||
|
|
|
|||
|
|
@ -1,16 +1,16 @@
|
|||
---
|
||||
title: Branding Guideline
|
||||
title: Branding Guidelines
|
||||
---
|
||||
|
||||
# Branding Guideline
|
||||
# Branding Guidelines
|
||||
|
||||
## Themeing
|
||||
## DEV Theme
|
||||
|
||||
DEV's design inspiration is meant to be a throwback. In personality and design it is ATARI inspired. Magazines like PAPER are also an inspiration in terms of being a [bold contrast with some more indy](https://www.google.com/search?biw=1440&bih=780&tbm=isch&sa=1&ei=KSN8W5WVLoy55gLI77TgBA&q=paper+magazine+cover&oq=paper+magazine+cover).
|
||||
|
||||
We also think in terms of how people use the DEV brand for their own purposes. Profiles are very much public-facing records of what people have put out into the world. `dev.to/{username}` is your dev identity.
|
||||
|
||||
Imagine a developer’s face with the DEV heading above them. If we existed in the 80’s we would be DEV MAGAZINE, with the exact same branding.
|
||||
Imagine a developer's face with the DEV heading above them. If we existed in the 80's we would have been "DEV MAGAZINE", with the exact same branding.
|
||||
|
||||
## Branding Rules
|
||||
|
||||
|
|
@ -24,4 +24,4 @@ Imagine a developer’s face with the DEV heading above them. If we existed in t
|
|||
## Acknowledgments
|
||||
|
||||
- We use the [Joystick](http://www.pixelsagas.com/?download=joystick) font by Neale Davidson and [Pixel Sagas](http://www.pixelsagas.com/) for the DEV Logo. We have a commercial license.
|
||||
- Thank you to [EmojiOne](https://www.emojione.com/) for providing free emoji icons
|
||||
- Thank you to [EmojiOne](https://www.emojione.com/) for providing free emoji icons.
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
---
|
||||
title: Designer Guide
|
||||
title: Design Guide
|
||||
items:
|
||||
- brand.md
|
||||
- theming-model.md
|
||||
- branding.md
|
||||
- theming.md
|
||||
---
|
||||
|
||||
# Designer Guide
|
||||
# Design Guide
|
||||
|
|
|
|||
|
|
@ -1,12 +1,18 @@
|
|||
---
|
||||
title: Theming Model
|
||||
title: Theming Guidelines
|
||||
---
|
||||
|
||||
# Theming Model
|
||||
# Theming Guidelines
|
||||
|
||||
DEV.to supports different themes such as Normal, Dark, Pink. These themes are powered by [css custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) which are loaded at runtime by javascript via `layouts/_user_config.html.erb`.
|
||||
DEV supports different themes such as Default, Night, Pink.
|
||||
|
||||
```
|
||||
You can switch the theme at <http://localhost:3000/settings/misc> in the "Style Customization" section.
|
||||
|
||||
These themes are powered by [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties), loaded at runtime by Javascript via `layouts/_user_config.html.erb`.
|
||||
|
||||
An example of how it works:
|
||||
|
||||
```javascript
|
||||
<script>
|
||||
try {
|
||||
var bodyClass = localStorage.getItem('config_body_class');
|
||||
|
|
@ -37,8 +43,12 @@ DEV.to supports different themes such as Normal, Dark, Pink. These themes are po
|
|||
--theme-social-icon-invert: invert(100)</style>'
|
||||
```
|
||||
|
||||
Within scss files located at `/app/assets/stylesheets` you will see `var` which will call these css custom properties. If a css custom property is not defined `var` will fall back on the second parameter provided which are css variables defined in `app/assets/stylesheets/variables.scss`
|
||||
Within SCSS files located at `app/assets/stylesheets` you will see `var()` statements, which will call these CSS custom properties. If a CSS custom property is not defined `var()` will fall back on the second parameter provided, which are be a SCSS variable defined in `app/assets/stylesheets/variables.scss`
|
||||
|
||||
```
|
||||
color: var(--theme-color, $black);
|
||||
An example of how to use `var()`:
|
||||
|
||||
```scss
|
||||
div {
|
||||
color: var(--theme-color, $black);
|
||||
}
|
||||
```
|
||||
|
|
@ -1,38 +0,0 @@
|
|||
---
|
||||
title: Plain Javascript and Intializers
|
||||
---
|
||||
|
||||
# Plain Javascript and JS Intializers
|
||||
|
||||
DEV.to has two javascript codebases. One is located at
|
||||
`/app/javascripts` and this is plain javascript being served using [spockets](https://github.com/rails/sprockets-rails)
|
||||
|
||||
The plain javascript codebase is not transpiled and will be limited to
|
||||
whatever flavour of javascript provided by the end-user's
|
||||
web-browser
|
||||
|
||||
`app/javascripts/application.js` is primary packaged javascript file
|
||||
which should be included in the primary template located within
|
||||
`app/layouts`. `application.js` automatically includes all javascript
|
||||
files via:
|
||||
|
||||
```
|
||||
//= require_tree .
|
||||
```
|
||||
|
||||
One javascript file it loads is `initializePage.js.erb` which boostraps
|
||||
the majority of functionality. You will see wtihin this file it manually
|
||||
loads multiple files:
|
||||
|
||||
```
|
||||
initializeBaseTracking();
|
||||
initializeTouchDevice();
|
||||
initializeCommentsPage();
|
||||
initEditorResize();
|
||||
initLeaveEditorWarning();
|
||||
initializeArticleReactions();
|
||||
initNotifications();
|
||||
initializeSplitTestTracking();
|
||||
```
|
||||
|
||||
Theses files are located at `/app/assets/javascripts/intializers`
|
||||
|
|
@ -4,9 +4,9 @@ title: Liquid Tags
|
|||
|
||||
# Liquid Tags
|
||||
|
||||
Liquid tags are a special element of the [dev.to](/) markdown editor.
|
||||
Liquid tags are special elements of the [DEV Markdown editor](https://dev.to/new).
|
||||
|
||||
They are custom embeds that are added via `{% %}` syntax. [Liquid](https://shopify.github.io/liquid/) is a templating language developed by Shopify.
|
||||
They are custom embeds that are added via a `{% %}` syntax. [Liquid](https://shopify.github.io/liquid/) is a templating language developed by Shopify.
|
||||
|
||||
Liquid embeds are for tweets, like `{% tweet 765282762081329153 %}` or a DEV user profile preview, like `{% user jess %}` etc.
|
||||
|
||||
|
|
@ -16,9 +16,9 @@ Liquid tags are sort of like functions, which have a name and take arguments. De
|
|||
|
||||
Liquid tags are "compiled" when an article is saved. So you will need to re-save articles to see HTML changes.
|
||||
|
||||
Here is a bunch of liquid tags supported on DEV.to
|
||||
Here is a bunch of liquid tags supported on DEV:
|
||||
|
||||
```
|
||||
```liquid
|
||||
{% link https://dev.to/kazz/boost-your-productivity-using-markdown-1be %}
|
||||
{% user jess %}
|
||||
{% tag git %}
|
||||
|
|
@ -38,6 +38,6 @@ Here is a bunch of liquid tags supported on DEV.to
|
|||
{% instagram BXgGcAUjM39 %}
|
||||
{% speakerdeck 7e9f8c0fa0c949bd8025457181913fd0 %}
|
||||
{% soundcloud https://soundcloud.com/user-261265215/dev-to-review-episode-1 %}
|
||||
% spotify spotify:episode:5V4XZWqZQJvbddd31n56mf %}
|
||||
{% spotify spotify:episode:5V4XZWqZQJvbddd31n56mf %}
|
||||
{% blogcast 1234 %}
|
||||
```
|
||||
|
|
|
|||
38
docs/frontend/plain-js.md
Normal file
38
docs/frontend/plain-js.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
title: Javascript and Initializers
|
||||
---
|
||||
|
||||
# Javascript and Initializers
|
||||
|
||||
DEV has two Javascript codebases.
|
||||
|
||||
One is located in the directory
|
||||
`app/assets/javascripts` and contains plain Javascript (mostly ES5+) being served using [Sprockets](https://github.com/rails/sprockets-rails) which packages static assets.
|
||||
|
||||
The other one is managed by Webpacker and you can read more about [in its own guide](/frontend/webpacker).
|
||||
|
||||
This source code is not transpiled, only packaged and minified, and will be limited to whatever flavour of Javascript can run on user's web browser.
|
||||
|
||||
`app/assets/javascripts/application.js` contains the manifest Javascript file
|
||||
which is included globally in the primary template, `app/views/layouts/application.html.erb`.
|
||||
|
||||
`application.js` automatically includes all JS files via the statement:
|
||||
|
||||
```erb
|
||||
//= require_tree .
|
||||
```
|
||||
|
||||
One JS file in particular, `app/assets/javascripts/initializePage.js.erb`, boostraps the majority of the functionality. You will notice, within this file, that major sections of the websites are bootstrapped, for example:
|
||||
|
||||
```javascript
|
||||
initializeBaseTracking();
|
||||
initializeTouchDevice();
|
||||
initializeCommentsPage();
|
||||
initEditorResize();
|
||||
initLeaveEditorWarning();
|
||||
initializeArticleReactions();
|
||||
initNotifications();
|
||||
initializeSplitTestTracking();
|
||||
```
|
||||
|
||||
All the "initializers" are in `/app/assets/javascripts/initializers`.
|
||||
|
|
@ -1,7 +1,11 @@
|
|||
---
|
||||
title: Preact Tests
|
||||
title: Preact
|
||||
---
|
||||
|
||||
# Writing Preact Tests
|
||||
# Preact
|
||||
|
||||
Preact is an alternative to React with the same modern API. Preact components are packaged using webpacker and the preact code is located in `app/javascript`
|
||||
[Preact](https://preactjs.com/) is an alternative to React with the same modern API.
|
||||
|
||||
Preact components are packaged using [Webpacker](/frontend/webpacker) and the Preact code is located in `app/javascript`.
|
||||
|
||||
The components are mounted when needed, look for `javascript_pack_tag` in the view pages inside `app/views`.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: Frontend Guide
|
||||
items:
|
||||
- js-initializers.md
|
||||
- plain-js.md
|
||||
- webpacker.md
|
||||
- preact.md
|
||||
- liquid-tags.md
|
||||
|
|
|
|||
|
|
@ -4,26 +4,23 @@ title: Webpacker
|
|||
|
||||
# Webpacker
|
||||
|
||||
DEV.to has two javascript codebases. One is located at
|
||||
`/app/javascripts` and this is plain javascript being served using `spockets`
|
||||
DEV has two Javascript codebases.
|
||||
|
||||
The other codebase is located at `/app/javascript` which is for preact
|
||||
components and is served via `webpack` which is integrated into the
|
||||
Rails app using `Webpacker`
|
||||
One contains plain Javascript and you can read about [in its own guide](/frontend/plain-js).
|
||||
|
||||
The other one is managed by [Webpacker](https://github.com/rails/webpacker) and it's located inside `/app/javascripts`, written using ES6+.
|
||||
|
||||
Currently it's mainly used for Preact components, served via `webpack` which is integrated into the Rails app using `Webpacker`.
|
||||
|
||||
There is a packs directory `/app/javascript/packs` where you can create
|
||||
new pack files.
|
||||
new "pack" files. Pack files are initializers for Webpacker.
|
||||
|
||||
Since DEV.to is not an SPA (Single Page Application)
|
||||
preact apps are mounted as needed by including the pack file in the erb
|
||||
files. eg
|
||||
Since DEV is not a Single Page Application (SPA), Preact components are mounted as needed by including the pack file in the view files.
|
||||
|
||||
```
|
||||
For example:
|
||||
|
||||
```erb
|
||||
<%= javascript_pack_tag "webShare", defer: true %>
|
||||
```
|
||||
|
||||
This pack would correspond with
|
||||
|
||||
```
|
||||
app/javascripts/packs/webShare.js
|
||||
```
|
||||
The include statement corresponds to the pack `app/javascripts/packs/webShare.js`
|
||||
|
|
|
|||
|
|
@ -2,16 +2,22 @@
|
|||
title: Configure Enviroment Variables
|
||||
---
|
||||
|
||||
# Set up your environment variables/secrets
|
||||
# Configure environment variables/secrets
|
||||
|
||||
- Take a look at `Envfile`. This file lists all the `ENV` variables we use and provides a fake default for any missing keys. You'll need to get your own free [Algolia credentials](http://docs.dev.to/get-api-keys-dev-env/#algolia) to get your development environment running.
|
||||
- This [guide](http://docs.dev.to/get-api-keys-dev-env/) will show you how to get free API keys for additional services that may be required to run certain parts of the app.
|
||||
- For any key that you wish to enter/replace:
|
||||
1. Create `config/application.yml` by copying from the provided template (ie. with bash: `cp config/sample_application.yml config/application.yml`). This is a personal file that is ignored in git.
|
||||
2. Obtain the development variable and apply the key you wish to enter/replace. ie:
|
||||
```
|
||||
GITHUB_KEY: "SOME_REAL_SECURE_KEY_HERE"
|
||||
GITHUB_SECRET: "ANOTHER_REAL_SECURE_KEY_HERE"
|
||||
```
|
||||
- If you are missing `ENV` variables on bootup, `envied` gem will alert you with messages similar to `'error_on_missing_variables!': The following environment variables should be set: A_MISSING_KEY.`.
|
||||
- You do not need "real" keys for basic development. Some features require certain keys, so you may be able to add them as you go.
|
||||
Take a look at `Envfile`. This file lists all the `ENV` variables we use and provides a fake default for any missing keys. You'll need to get your own free [Algolia credentials](/backend/algolia) to get your development environment running.
|
||||
|
||||
The [backend guide](/backend) will show you how to get free API keys for additional services that may be required to run certain parts of the app.
|
||||
|
||||
For any key that you wish to enter/replace:
|
||||
|
||||
1. Create `config/application.yml` by copying from the provided template (ie. with bash: `cp config/sample_application.yml config/application.yml`). This is a personal file that is ignored in git.
|
||||
1. Obtain the development variable and apply the key you wish to enter/replace. ie:
|
||||
|
||||
```shell
|
||||
GITHUB_KEY: "SOME_REAL_SECURE_KEY_HERE"
|
||||
GITHUB_SECRET: "ANOTHER_REAL_SECURE_KEY_HERE"
|
||||
```
|
||||
|
||||
If you are missing `ENV` variables on bootup, the [envied](https://rubygems.org/gems/envied) gem will alert you with messages similar to `'error_on_missing_variables!': The following environment variables should be set: A_MISSING_KEY.`.
|
||||
|
||||
You do not need "real" keys for basic development. Some features require certain keys, so you may be able to add them as you go.
|
||||
|
|
|
|||
|
|
@ -2,18 +2,20 @@
|
|||
title: Preparing the Database
|
||||
---
|
||||
|
||||
# Preparing the Database
|
||||
# Preparing the database
|
||||
|
||||
We need to create our database, load the database schema, and load seed
|
||||
data. This can be accomplished with:
|
||||
|
||||
`rake db:setup`
|
||||
```shell
|
||||
rails db:setup
|
||||
```
|
||||
|
||||
`db:setup` actually runs the following rake commands in order so
|
||||
you could alternatively run each of these to produce the same result.
|
||||
|
||||
```
|
||||
rake db:create
|
||||
rake db:schema:load
|
||||
rake db:seed
|
||||
```shell
|
||||
rails db:create
|
||||
rails db:schema:load
|
||||
rails db:seed
|
||||
```
|
||||
|
|
|
|||
|
|
@ -2,12 +2,12 @@
|
|||
title: Forking The Repo
|
||||
---
|
||||
|
||||
# Forking The Repo
|
||||
# Forking the repository
|
||||
|
||||
Fork dev.to repository, ie. `https://github.com/thepracticaldev/dev.to/fork`
|
||||
Fork DEV's repository: <https://github.com/thepracticaldev/dev.to/fork>
|
||||
|
||||
Clone your forked repository,
|
||||
Clone your forked repository:
|
||||
|
||||
```
|
||||
```shell
|
||||
git clone https://github.com/<your-username>/dev.to.git
|
||||
```
|
||||
|
|
|
|||
|
|
@ -2,12 +2,12 @@
|
|||
title: Preparing a Pull Request
|
||||
---
|
||||
|
||||
# Preparing a Pull Request
|
||||
# Preparing a pull request
|
||||
|
||||
- Try to keep the pull requests small. A pull request should try its very best to address only a single concern.
|
||||
- Make sure all tests pass and add additional tests for the code you submit. [More info here](https://docs.dev.to/testing/)
|
||||
- Document your reasoning behind the changes. Explain why you wrote the code in the way you did. The code should explain what it does.
|
||||
- If there's an existing issue related to the pull request, reference to it by adding something like `References/Closes/Fixes/Resolves #305`, where 305 is the issue number. [More info here](https://github.com/blog/1506-closing-issues-via-pull-requests)
|
||||
- Make sure all tests pass and add additional tests for the code you submit. Checkout the [testing guide](/testing).
|
||||
- Document your reasoning behind the changes. Explain why you wrote the code in the way you did. The code should be clear enough to explain what it does.
|
||||
- If there's an existing issue related to the pull request, reference to it by adding something like `References/Closes/Fixes/Resolves #305`, where 305 is the issue number. See [GitHub's own guide on closing issues via PR](https://github.com/blog/1506-closing-issues-via-pull-requests).
|
||||
- If you follow the pull request template, you can't go wrong.
|
||||
|
||||
_Please note: all commits in a pull request will be squashed when merged, but when your PR is approved and passes our CI, it will be live on production!_
|
||||
|
|
|
|||
|
|
@ -4,10 +4,10 @@ items:
|
|||
- forking.md
|
||||
- config-env.md
|
||||
- db.md
|
||||
- syncing.md
|
||||
- branching.md
|
||||
- committing.md
|
||||
- pull-request.md
|
||||
- syncing.md
|
||||
---
|
||||
|
||||
# Getting Started!
|
||||
|
|
|
|||
|
|
@ -1,53 +1,53 @@
|
|||
---
|
||||
title: Syncing Your Fork
|
||||
title: Keeping Your Fork In Sync
|
||||
---
|
||||
|
||||
# Syncing Your Fork
|
||||
# Keeping your fork in sync
|
||||
|
||||
Now that you have a copy of your fork, there is work you will need to do to keep it current.
|
||||
Now that you have a fork of DEV's source code, there is work you will need to do to keep it updated.
|
||||
|
||||
## Setup Your Upstream
|
||||
## Setup Your upstream
|
||||
|
||||
Inside your dev.to directory, add a remote to the official dev.to repo:
|
||||
Inside your DEV directory, add a remote to the official DEV repo:
|
||||
|
||||
```
|
||||
$ git remote add upstream https://github.com/thepracticaldev/dev.to.git
|
||||
```shell
|
||||
git remote add upstream https://github.com/thepracticaldev/dev.to.git
|
||||
```
|
||||
|
||||
## Rebasing from Upstream
|
||||
## Rebasing from upstream
|
||||
|
||||
Do this prior to every time you create a branch for a PR:
|
||||
|
||||
Make sure you are on the master branch
|
||||
Make sure you are on the master branch:
|
||||
|
||||
```
|
||||
```shell
|
||||
$ git status
|
||||
On branch master
|
||||
Your branch is up-to-date with 'origin/master'.
|
||||
```
|
||||
|
||||
If your aren't on `master`, resolve outstanding files / commits and checkout the `master` branch
|
||||
If your aren't on `master`, finish your work and checkout the `master` branch:
|
||||
|
||||
```
|
||||
$ git checkout master
|
||||
```shell
|
||||
git checkout master
|
||||
```
|
||||
|
||||
Do a pull with rebase against `upstream`
|
||||
|
||||
```
|
||||
$ git pull --rebase upstream master
|
||||
```shell
|
||||
git pull --rebase upstream master
|
||||
```
|
||||
|
||||
This will pull down all of the changes to the official `master` branch, without making an additional commit in your local repo.
|
||||
|
||||
(Optional) Force push your updated `master` branch to your GitHub fork
|
||||
|
||||
```
|
||||
$ git push origin master --force
|
||||
```shell
|
||||
git push origin master --force
|
||||
```
|
||||
|
||||
This will overwrite the `master` branch of your fork.
|
||||
|
||||
## Also see
|
||||
## Additional resources
|
||||
|
||||
- [Syncing a fork](https://help.github.com/articles/syncing-a-fork/)
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Docker [Beta]
|
||||
# Docker Installation [Beta]
|
||||
|
||||
1. Install `docker` and `docker-compose`
|
||||
1. `git clone git@github.com:thepracticaldev/dev.to.git`
|
||||
|
|
@ -7,4 +7,4 @@
|
|||
1. run `docker-compose run web rails db:setup`
|
||||
1. run `docker-compose run web yarn install`
|
||||
1. run `docker-compose up`
|
||||
1. That's it! Navigate to `localhost:3000`
|
||||
1. That's it! Navigate to <http://localhost:3000>
|
||||
|
|
|
|||
|
|
@ -4,4 +4,6 @@ title: GitPod
|
|||
|
||||
# GitPod
|
||||
|
||||
You can also [spin up a "local" instance of DEV in the cloud with GitPod (It's incredibly simple)](https://dev.to/ben/spin-up-a-local-instance-of-dev-in-the-cloud-with-gitpod-it-s-incredibly-simple-pij): https://gitpod.io/#https://github.com/thepracticaldev/dev.to
|
||||
If you prefer working on a cloud IDE, you can spin up your own instance of DEV in the cloud, using [GitPod](https://gitpod.io/#https://github.com/thepracticaldev/dev.to).
|
||||
|
||||
You can find more information about this, [in a DEV's article](https://dev.to/ben/spin-up-a-local-instance-of-dev-in-the-cloud-with-gitpod-it-s-incredibly-simple-pij).
|
||||
|
|
|
|||
|
|
@ -1,12 +1,8 @@
|
|||
---
|
||||
title: Linux
|
||||
---
|
||||
|
||||
# Installing DEV.to on Linux
|
||||
# Installing DEV on Linux
|
||||
|
||||
## Installing prerequisites
|
||||
|
||||
These prerequisites assume you're working on a Linux-based operating system but have been tested on Ubuntu 18.04.
|
||||
_These prerequisites assume you're working on a Linux-based operating system but they have only been tested on Ubuntu 18.04._
|
||||
|
||||
### Ruby
|
||||
|
||||
|
|
@ -19,37 +15,40 @@ For very detailed rbenv installation directions on several distros, please visit
|
|||
|
||||
There are two ways to install Yarn.
|
||||
|
||||
- Yarn's official [installation guide](https://yarnpkg.com/en/docs/install#debian-stable).
|
||||
- Yarn's official [installation guide](https://yarnpkg.com/en/docs/install#debian-stable) (recommended).
|
||||
- [DigitalOcean's detailed tutorial](https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-ubuntu-18-04) describes how to install [Node version Manager](https://github.com/creationix/nvm). By installing NVM you can select a Node version (we recommend either LTS or current), the guide will also explain how to install NPM. This way you'll have Node, NPM, and then you can run `npm install -g yarn` to install Yarn.
|
||||
|
||||
### PostgreSQL
|
||||
|
||||
1. run `sudo apt update && sudo apt install postgresql postgresql-contrib libpq-dev`.
|
||||
1. To test the installation you can run `sudo -u postgres psql` which should open a PostgreSQL prompt. Exit the prompt by running `\q` then run `sudo -u postgres createuser -s $YOUR_USERNAME` where \$YOUR_USERNAME is the username you are currently logged in as.
|
||||
1. Run `sudo apt update && sudo apt install postgresql postgresql-contrib libpq-dev`.
|
||||
1. To test the installation you can run `sudo -u postgres psql` which should open a PostgreSQL prompt. Exit the prompt by running `\q` then run `sudo -u postgres createuser -s $YOUR_USERNAME` where `$YOUR_USERNAME` is the username you are currently logged in as.
|
||||
|
||||
There are more than one way to setup Postgres. For additional configuration, check out our [postgres doc](/additional-postgres-setup) or the official [PostgreSQL](https://www.postgresql.org/) site for more information.
|
||||
There are more than one ways to setup PostgreSQL. For additional configuration, check out our [PostgreSQL setup guide](/installation/postgres) or the official [PostgreSQL](https://www.postgresql.org/) site for further information.
|
||||
|
||||
## Installing Dev.to
|
||||
## Installing DEV
|
||||
|
||||
1. Fork dev.to repository, ie. https://github.com/thepracticaldev/dev.to/fork
|
||||
1. Clone your forked repository, ie. `git clone https://github.com/<your-username>/dev.to.git`
|
||||
1. Fork DEV's repository, eg. <https://github.com/thepracticaldev/dev.to/fork>
|
||||
1. Clone your forked repository, eg. `git clone https://github.com/<your-username>/dev.to.git`
|
||||
1. Install bundler with `gem install bundler`
|
||||
1. Set up your environment variables/secrets
|
||||
|
||||
- Take a look at `Envfile`. This file lists all the `ENV` variables we use and provides a fake default for any missing keys. You'll need to get your own free [Algolia credentials](http://docs.dev.to/get-api-keys-dev-env/#algolia) to get your development environment running.
|
||||
- This [guide](http://docs.dev.to/get-api-keys-dev-env/) will show you how to get free API keys for additional services that may be required to run certain parts of the app.
|
||||
- Take a look at `Envfile`. This file lists all the `ENV` variables we use and provides a fake default for any missing keys. You'll need to get your own free [Algolia credentials](/backend/algolia) to get your development environment running.
|
||||
- The [backend guide](/backend) will show you how to get free API keys for additional services that may be required to run certain parts of the app.
|
||||
- For any key that you wish to enter/replace:
|
||||
|
||||
1. Create `config/application.yml` by copying from the provided template (ie. with bash: `cp config/sample_application.yml config/application.yml`). This is a personal file that is ignored in git.
|
||||
1. Obtain the development variable and apply the key you wish to enter/replace. ie:
|
||||
1. Create `config/application.yml` by copying from the provided template (ie. with bash: `cp config/sample_application.yml config/application.yml`). This is a personal file that is ignored in git.
|
||||
1. Obtain the development variable and apply the key you wish to enter/replace. ie:
|
||||
|
||||
```
|
||||
GITHUB_KEY: "SOME_REAL_SECURE_KEY_HERE"
|
||||
GITHUB_SECRET: "ANOTHER_REAL_SECURE_KEY_HERE"
|
||||
```
|
||||
```shell
|
||||
GITHUB_KEY: "SOME_REAL_SECURE_KEY_HERE"
|
||||
GITHUB_SECRET: "ANOTHER_REAL_SECURE_KEY_HERE"
|
||||
```
|
||||
|
||||
- If you are missing `ENV` variables on bootup, `envied` gem will alert you with messages similar to `'error_on_missing_variables!': The following environment variables should be set: A_MISSING_KEY.`.
|
||||
- If you are missing `ENV` variables on bootup, the [envied](https://rubygems.org/gems/envied) gem will alert you with messages similar to `'error_on_missing_variables!': The following environment variables should be set: A_MISSING_KEY.`.
|
||||
- You do not need "real" keys for basic development. Some features require certain keys, so you may be able to add them as you go.
|
||||
|
||||
1. Run `bin/setup`
|
||||
- While installing, you might run into an error due to the pg gem requiring PostgreSQL libraries. If so, please run `sudo apt-get install libpq-dev` before retrying.
|
||||
|
||||
### Possible error messages
|
||||
|
||||
While installing, you might run into an error due to the pg gem requiring PostgreSQL libraries. If so, please run `sudo apt-get install libpq-dev` before retrying.
|
||||
|
|
|
|||
|
|
@ -1,15 +1,15 @@
|
|||
---
|
||||
title: Mac
|
||||
title: macOS
|
||||
---
|
||||
|
||||
# Installing DEV.to on Mac
|
||||
# Installing DEV on macOS
|
||||
|
||||
## Installing prerequisites
|
||||
|
||||
### Ruby
|
||||
|
||||
1. If you don't already have a Ruby version manager, we highly recommend [rbenv](https://github.com/rbenv/rbenv). Please follow their [installation guide](https://github.com/rbenv/rbenv#installation).
|
||||
2. With the Ruby version manager, install the Ruby version listed on our badge. (ie with rbenv: `rbenv install 2.6.1`)
|
||||
1. If you don't already have a Ruby version manager, we highly recommend [rbenv](https://github.com/rbenv/rbenv). Please follow their [installation guide](https://github.com/rbenv/rbenv#installation).
|
||||
2. With the Ruby version manager, install the Ruby version listed on our badge. (ie with rbenv: `rbenv install 2.6.1`)
|
||||
|
||||
### Yarn
|
||||
|
||||
|
|
@ -17,35 +17,35 @@ Please refer to their [installation guide](https://yarnpkg.com/en/docs/install).
|
|||
|
||||
### PostgreSQL
|
||||
|
||||
Dev.to requires PostgreSQL version 9.4 or higher. The easiest way to get started is to use [Postgres.app](https://postgresapp.com/). Alternatively, check out the official [PostgreSQL](https://www.postgresql.org/) site for more granular version.
|
||||
DEV requires PostgreSQL version 9.4 or higher. The easiest way to get started is to use [Postgres.app](https://postgresapp.com/). Alternatively, check out the official [PostgreSQL](https://www.postgresql.org/) site for more installation options.
|
||||
|
||||
For additional configuration, [click here](/additional-postgres-setup)
|
||||
For additional configuration options, check our [PostgreSQL setup guide](/installation/postgres).
|
||||
|
||||
## Installing Dev.to
|
||||
## Installing DEV
|
||||
|
||||
1. Fork dev.to repository, ie. https://github.com/thepracticaldev/dev.to/fork
|
||||
1. Clone your forked repository, ie. `git clone https://github.com/<your-username>/dev.to.git`
|
||||
1. Fork DEV's repository, eg. <https://github.com/thepracticaldev/dev.to/fork>
|
||||
1. Clone your forked repository, eg. `git clone https://github.com/<your-username>/dev.to.git`
|
||||
1. Install bundler with `gem install bundler`
|
||||
1. Set up your environment variables/secrets
|
||||
|
||||
- Take a look at `Envfile`. This file lists all the `ENV` variables we use and provides a fake default for any missing keys. You'll need to get your own free [Algolia credentials](http://docs.dev.to/get-api-keys-dev-env/#algolia) to get your development environment running.
|
||||
- This [guide](http://docs.dev.to/get-api-keys-dev-env/) will show you how to get free API keys for additional services that may be required to run certain parts of the app.
|
||||
- Take a look at `Envfile`. This file lists all the `ENV` variables we use and provides a fake default for any missing keys. You'll need to get your own free [Algolia credentials](/backend/algolia) to get your development environment running.
|
||||
- The [backend guide](/backend) will show you how to get free API keys for additional services that may be required to run certain parts of the app.
|
||||
- For any key that you wish to enter/replace:
|
||||
|
||||
1. Create `config/application.yml` by copying from the provided template (ie. with bash: `cp config/sample_application.yml config/application.yml`). This is a personal file that is ignored in git.
|
||||
1. Obtain the development variable and apply the key you wish to enter/replace. ie:
|
||||
1. Create `config/application.yml` by copying from the provided template (ie. with bash: `cp config/sample_application.yml config/application.yml`). This is a personal file that is ignored in git.
|
||||
1. Obtain the development variable and apply the key you wish to enter/replace. ie:
|
||||
|
||||
```
|
||||
GITHUB_KEY: "SOME_REAL_SECURE_KEY_HERE"
|
||||
GITHUB_SECRET: "ANOTHER_REAL_SECURE_KEY_HERE"
|
||||
```
|
||||
```shell
|
||||
GITHUB_KEY: "SOME_REAL_SECURE_KEY_HERE"
|
||||
GITHUB_SECRET: "ANOTHER_REAL_SECURE_KEY_HERE"
|
||||
```
|
||||
|
||||
- If you are missing `ENV` variables on bootup, `envied` gem will alert you with messages similar to `'error_on_missing_variables!': The following environment variables should be set: A_MISSING_KEY.`.
|
||||
- If you are missing `ENV` variables on bootup, the [envied](https://rubygems.org/gems/envied) gem will alert you with messages similar to `'error_on_missing_variables!': The following environment variables should be set: A_MISSING_KEY.`.
|
||||
- You do not need "real" keys for basic development. Some features require certain keys, so you may be able to add them as you go.
|
||||
|
||||
1. Run `bin/setup`
|
||||
|
||||
#### Possible Error Messages
|
||||
### Possible error messages
|
||||
|
||||
**Error:** `rbenv: version '<version number>' is not installed (set by /Path/To/Local/Repository/.ruby-version)`
|
||||
|
||||
|
|
@ -53,10 +53,11 @@ For additional configuration, [click here](/additional-postgres-setup)
|
|||
|
||||
**Error:** `ruby-build: definition not found: <version number>` when `rbenv` was installed via `brew`.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
ruby-build: definition not found: <version number>
|
||||
|
||||
See all available versions with `rbenv install --list'. If the version you need is missing, try upgrading ruby-build:
|
||||
See all available versions with `rbenv install --list`.
|
||||
If the version you need is missing, try upgrading ruby-build:
|
||||
```
|
||||
|
||||
**_Solution:_**
|
||||
|
|
@ -64,13 +65,13 @@ Run the following to update `ruby-build`, `brew update && brew upgrade ruby-buil
|
|||
|
||||
**Error:**
|
||||
|
||||
```bash
|
||||
```shell
|
||||
== Preparing database ==
|
||||
Sorry, you can't use byebug without Readline. To solve this, you need to
|
||||
rebuild Ruby with Readline support. If using Ubuntu, try `sudo apt-get
|
||||
install libreadline-dev` and then reinstall your Ruby.
|
||||
rails aborted!
|
||||
LoadError: dlopen(/Users/nickytonline/.rbenv/versions/2.6.1/lib/ruby/2.6.0/x86_64-darwin18/readline.bundle, 9): Library not loaded: /usr/local/opt/readline/lib/libreadline.<some version number>.dylib
|
||||
LoadError: dlopen(/Users/<username>/.rbenv/versions/2.6.1/lib/ruby/2.6.0/x86_64-darwin18/readline.bundle, 9): Library not loaded: /usr/local/opt/readline/lib/libreadline.<some version number>.dylib
|
||||
```
|
||||
|
||||
**_Solution:_** Run `ln -s /usr/local/opt/readline/lib/libreadline.dylib /usr/local/opt/readline/lib/libreadline.<some version number>.dylib` from the command line then run `bin/setup` again. You may have a different version or libreadline, so replace `<some version number>` with the version that errored.
|
||||
|
|
|
|||
|
|
@ -1,18 +1,18 @@
|
|||
---
|
||||
title: Postgres
|
||||
title: PostgreSQL
|
||||
---
|
||||
|
||||
# Setup your application with PostgreSQL
|
||||
|
||||
Follow the instructions in the installation guide below that corresponds to your operating system:
|
||||
|
||||
1. macOS
|
||||
- [Postgres.app](https://postgresapp.com/): PostgreSQL installation as a Mac app
|
||||
- [Homebrew](https://brew.sh/): if you use Homebrew you can easily install PostgreSQL with `brew install postgresql`
|
||||
1. Linux (Ubuntu)
|
||||
- [Ubuntu `14.04`](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-14-04)
|
||||
- [Ubuntu `16.04 and higher`](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-16-04)
|
||||
1. [Windows](https://www.postgresql.org/download/windows/)
|
||||
1. macOS
|
||||
- [Postgres.app](https://postgresapp.com/): PostgreSQL installation as a Mac app
|
||||
- [Homebrew](https://brew.sh/): if you use Homebrew you can easily install PostgreSQL with `brew install postgresql`
|
||||
1. Linux (Ubuntu)
|
||||
- [Ubuntu `14.04`](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-14-04)
|
||||
- [Ubuntu `16.04 and higher`](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-16-04)
|
||||
1. [Windows](https://www.postgresql.org/download/windows/)
|
||||
|
||||
_You can find all installation options for a variety of operating systems [on the official PostgreSQL download page](https://www.postgresql.org/download/)_.
|
||||
|
||||
|
|
@ -24,15 +24,15 @@ The [official Rails guides](https://guides.rubyonrails.org/configuring.html#conn
|
|||
|
||||
### Setup `DATABASE_URL` in application.yml
|
||||
|
||||
1. Open your `config/application.yml`
|
||||
1. Open your `config/application.yml`
|
||||
|
||||
1. Add the following:
|
||||
1. Add the following:
|
||||
|
||||
```yml
|
||||
DATABASE_URL: postgresql://USERNAME:PASSWORD@localhost
|
||||
```
|
||||
```yml
|
||||
DATABASE_URL: postgresql://USERNAME:PASSWORD@localhost
|
||||
```
|
||||
|
||||
1. Replace `USERNAME` with your database username, `PASSWORD` with your database password.
|
||||
1. Replace `USERNAME` with your database username, `PASSWORD` with your database password.
|
||||
|
||||
You can find more details on connection strings in [PostgreSQL's own documentation](https://www.postgresql.org/docs/10/static/libpq-connect.html#LIBPQ-CONNSTRING).
|
||||
|
||||
|
|
@ -40,6 +40,8 @@ NOTE: due to how Rails merges `database.yml` and `DATABASE_URL` it's recommended
|
|||
|
||||
## Troubleshooting tests
|
||||
|
||||
- While running test cases, if you get an error message `postgresql connection timeout`. Go to your `spec/support/database_cleaner.rb` file. And rename `:truncation` with `:deletion`.
|
||||
- While running test cases, if you get an error message `postgresql connection timeout`, please re-run the tests by increasing the statement timeout, for example:
|
||||
|
||||
_Please, do not commit `database_cleaner.rb` to the repository either._
|
||||
```shell
|
||||
STATEMENT_TIMEOUT=10000 bundle exec rspec
|
||||
```
|
||||
|
|
@ -1,28 +1,29 @@
|
|||
---
|
||||
title: 'Installation'
|
||||
items:
|
||||
- mac.md
|
||||
- windows.md
|
||||
- linux.md
|
||||
- docker.md
|
||||
- gitpod.md
|
||||
- postgres.md
|
||||
- postgresql.md
|
||||
---
|
||||
|
||||
# Installation Guide
|
||||
|
||||
There are many different ways you can install the **development environment** so you can help contribute code to DEV.to.
|
||||
There are many different ways you can install the **development environment** so you can help contribute code to DEV.
|
||||
|
||||
## Installing Locally
|
||||
## Installing locally
|
||||
|
||||
You can install DEV.to to your local machine and we have instructions for [Mac](/installation/mac-os), [Windows](/installation/windows) and [Linux](/installation/linux)
|
||||
You can install DEV to your local machine and we have instructions for [Mac](/installation/mac-os), [Windows](/installation/windows) and [Linux](/installation/linux).
|
||||
|
||||
## Running Docker
|
||||
|
||||
Installing to your local machine can be troublesome for many reasons such as conflicting database and runtime versions. Another way you can get a development environment up and running is with Docker. Docker will install everything you need in an isolated , and you need not concern about the details.
|
||||
Installing to your local machine can be troublesome for many reasons such as a conflicting database and runtime versions.
|
||||
|
||||
We have instructions for installing with [Docker](/installation/docker)
|
||||
Another way you can get a development environment up and running is with Docker. Docker will install everything you need in an isolated container, and you need not concern about the details. We have instructions for installing with [Docker](/installation/docker).
|
||||
|
||||
## GitPod
|
||||
|
||||
If you are having trouble with local installation and Docker confuses you, then you can launch a **development environment** with the press of a button with GitPod. GitPod is an IDE in the cloud which is also attached to a web-server. It will install everything you need. If you are comfortable doing everything from a web-browser than we have instructions for installing with [GitPod](/installation/gitpod)
|
||||
If you are having trouble with local installation and Docker confuses you, then you can launch a **development environment** with the press of a button with GitPod.
|
||||
|
||||
GitPod is an IDE in the cloud which is also attached to a web server. It will install everything you need. If you are comfortable doing everything from a web browser, then we have instructions for installing with [GitPod](/installation/gitpod) as well.
|
||||
|
|
|
|||
|
|
@ -1,22 +1,18 @@
|
|||
---
|
||||
title: Windows
|
||||
---
|
||||
|
||||
# Installing DEV.to on Windows
|
||||
# Installing DEV on Windows 10
|
||||
|
||||
## Installing prerequisites
|
||||
|
||||
These prerequisites assume you're working on a 64bit Windows 10 operating system machine.
|
||||
_These prerequisites assume you're working on a 64bit Windows 10 operating system machine._
|
||||
|
||||
### Installing WSL
|
||||
|
||||
Since dev.to codebase is using Ruby on Rails framework, we will need to install Windows Subsystem for Linux. Some dependencies used by the source code triggered errors when installing on Windows, so using WSL allows you to work on the software and not fixing gem incompatibilities.
|
||||
Since DEV's codebase is using the Ruby on Rails framework, we will need to install Windows Subsystem for Linux. Some dependencies used by the source code triggered errors when installing on Windows, so using WSL allows you to work on the software and not having to fix gem incompatibilities.
|
||||
|
||||
First, let's enable Windows Subsystem for Linux in your machine. You can do this by opening Control Panel, going to Programs, and then clicking "Turn Windows Features On or Off". Looking for the "Windows Subsystem for Linux" option and check the box next to it. Windows will ask for a reboot.
|
||||
First, let's enable Windows Subsystem for Linux in your machine. You can do this by opening `Control Panel`, going to `Programs`, and then clicking `Turn Windows Features On or Off`. Look for the `Windows Subsystem for Linux` option and check the box next to it. Windows will ask for a reboot.
|
||||
|
||||
|
||||
|
||||
Once you've got this installed and after rebooting, follow [this link](https://www.microsoft.com/store/productId/9N9TNGVNDL3Q) to install Ubuntu 18.04 on Windows.
|
||||
Once you've got this installed and after rebooting, [install Ubuntu 18.04 on Windows](https://www.microsoft.com/store/productId/9N9TNGVNDL3Q).
|
||||
|
||||
On your first run, the system will ask for username and password. Take note of both since it will be used for `sudo` commands.
|
||||
|
||||
|
|
@ -24,14 +20,14 @@ On your first run, the system will ask for username and password. Take note of b
|
|||
|
||||
First, install Ruby language dependencies:
|
||||
|
||||
```
|
||||
```shell
|
||||
sudo apt-get update
|
||||
sudo apt-get install git-core curl zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev software-properties-common libffi-dev
|
||||
```
|
||||
|
||||
For installing Ruby, we recommend using [rbenv](https://github.com/rbenv/rbenv)
|
||||
For installing Ruby, we recommend using [rbenv](https://github.com/rbenv/rbenv):
|
||||
|
||||
```
|
||||
```shell
|
||||
cd
|
||||
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
|
||||
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
|
||||
|
|
@ -49,11 +45,11 @@ ruby -v
|
|||
|
||||
### Installing Rails
|
||||
|
||||
Since Rails ships with so many dependencies these days, we're going to need to install a Javascript runtime like NodeJS. This lets you use Coffeescript and the Asset Pipeline in Rails which combines and minifies your javascript to provide a faster production environment.
|
||||
Since Rails ships with so many dependencies these days, we're going to need to install a JavaScript runtime like NodeJS. This lets you use CoffeeScript and the Asset Pipeline in Rails which combines and minifies your JavaScript to provide a faster production environment.
|
||||
|
||||
To install NodeJS, we're going to add it using the official repository:
|
||||
|
||||
```
|
||||
```shell
|
||||
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
|
||||
sudo apt-get install -y nodejs
|
||||
node -v
|
||||
|
|
@ -64,30 +60,30 @@ If `npm -v` gives `Syntax error: word unexpected (expecting "in")`, restart the
|
|||
|
||||
And now, for rails itself:
|
||||
|
||||
```
|
||||
gem install rails -v 5.1.6
|
||||
```shell
|
||||
gem install rails -v 5.2.3
|
||||
```
|
||||
|
||||
Then run `rbenv rehash` to make Rails executable available. Check it out by using `rails -v` command
|
||||
Then run `rbenv rehash` to make the Rails executable available. Check it out by using `rails -v` command
|
||||
|
||||
```
|
||||
```shell
|
||||
rbenv rehash
|
||||
rails -v
|
||||
# Rails 5.1.6
|
||||
# Rails 5.2.3
|
||||
```
|
||||
|
||||
### Yarn
|
||||
|
||||
The fastest way to install Yarn for WSL would be from Debian package repository. Configure the repository with the following commands:
|
||||
|
||||
```
|
||||
```shell
|
||||
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
|
||||
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
|
||||
```
|
||||
|
||||
Then you can simply:
|
||||
Then you can simply issue:
|
||||
|
||||
```
|
||||
```shell
|
||||
sudo apt-get update && sudo apt-get install yarn
|
||||
```
|
||||
|
||||
|
|
@ -95,38 +91,38 @@ Make sure that Yarn is installed with `yarn -v`
|
|||
|
||||
### PostgreSQL
|
||||
|
||||
If you don't have PostgreSQL installed on your Windows system, You can do so here. WSL is able to connect to Windows Postgresql.
|
||||
If you don't have PostgreSQL installed on your Windows system, you can do so right now. WSL is able to connect to a PostgreSQL instance on your Windows machine. DEV requires PostgreSQL version 9.4 or higher.
|
||||
|
||||
Download [PostgreSQL for Windows](https://www.openscg.com/bigsql/postgresql/installers.jsp/) and install it.
|
||||
Download [PostgreSQL for Windows](https://www.openscg.com/postgresql/installers/) and install it.
|
||||
|
||||
Pay attention to the username and password you setup during installation of Postgres as you will use this to configure your Rails applications to login to Postgres later.
|
||||
Pay attention to the username and password you setup during installation of PostgreSQL as you will use this to configure your Rails applications to login to the database later.
|
||||
|
||||
## Installing Dev.to
|
||||
## Installing DEV
|
||||
|
||||
1. Fork dev.to repository, ie. https://github.com/thepracticaldev/dev.to/fork
|
||||
1. Clone your forked repository, ie. `git clone https://github.com/<your-username>/dev.to.git`
|
||||
1. Fork DEV's repository, eg. <https://github.com/thepracticaldev/dev.to/fork>
|
||||
1. Clone your forked repository, eg. `git clone https://github.com/<your-username>/dev.to.git`
|
||||
1. Install bundler with `gem install bundler`
|
||||
1. Set up your environment variables/secrets
|
||||
|
||||
- Take a look at `Envfile`. This file lists all the `ENV` variables we use and provides a fake default for any missing keys. You'll need to get your own free [Algolia credentials](http://docs.dev.to/get-api-keys-dev-env/#algolia) to get your development environment running.
|
||||
- This [guide](http://docs.dev.to/get-api-keys-dev-env/) will show you how to get free API keys for additional services that may be required to run certain parts of the app.
|
||||
- Take a look at `Envfile`. This file lists all the `ENV` variables we use and provides a fake default for any missing keys. You'll need to get your own free [Algolia credentials](/backend/algolia) to get your development environment running.
|
||||
- The [backend guide](/backend) will show you how to get free API keys for additional services that may be required to run certain parts of the app.
|
||||
- For any key that you wish to enter/replace:
|
||||
|
||||
1. Create `config/application.yml` by copying from the provided template (ie. with bash: `cp config/sample_application.yml config/application.yml`). This is a personal file that is ignored in git.
|
||||
1. Obtain the development variable and apply the key you wish to enter/replace. ie:
|
||||
1. Create `config/application.yml` by copying from the provided template (ie. with bash: `cp config/sample_application.yml config/application.yml`). This is a personal file that is ignored in git.
|
||||
1. Obtain the development variable and apply the key you wish to enter/replace. ie:
|
||||
|
||||
```
|
||||
GITHUB_KEY: "SOME_REAL_SECURE_KEY_HERE"
|
||||
GITHUB_SECRET: "ANOTHER_REAL_SECURE_KEY_HERE"
|
||||
```
|
||||
```shell
|
||||
GITHUB_KEY: "SOME_REAL_SECURE_KEY_HERE"
|
||||
GITHUB_SECRET: "ANOTHER_REAL_SECURE_KEY_HERE"
|
||||
```
|
||||
|
||||
- If you are missing `ENV` variables on bootup, `envied` gem will alert you with messages similar to `'error_on_missing_variables!': The following environment variables should be set: A_MISSING_KEY.`.
|
||||
- If you are missing `ENV` variables on bootup, the [envied](https://rubygems.org/gems/envied) gem will alert you with messages similar to `'error_on_missing_variables!': The following environment variables should be set: A_MISSING_KEY.`.
|
||||
- You do not need "real" keys for basic development. Some features require certain keys, so you may be able to add them as you go.
|
||||
|
||||
1. Run `bin/setup`
|
||||
|
||||
#### Other Possible Error Messages
|
||||
### Possible error messages
|
||||
|
||||
1. There is a possibility that you might encounter a _statement timeout_ when seeding the database for the first time. Please comment out the variable `statement_timeout` from database.yml if it happens.
|
||||
1. There is a possibility that you might encounter a _statement timeout_ when seeding the database for the first time. Please comment out the variable `statement_timeout` from the file `config/database.yml` if it happens.
|
||||
|
||||
> If you encountered any errors that you subsequently resolved, **please consider updating this section** with your errors and their solutions.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
items:
|
||||
- technical-overview.md
|
||||
- installation
|
||||
- techincal-overview.md
|
||||
- getting-started
|
||||
- backend
|
||||
- frontend
|
||||
|
|
@ -12,3 +12,7 @@ items:
|
|||
- licensing.md
|
||||
- self-hosting.md
|
||||
---
|
||||
|
||||
# Welcome to DEV's developer documentation
|
||||
|
||||
Here you can find instructions on how to setup your own local copy of DEV, how to navigate the code, how to contribute and how to troubleshoot issues among other things.
|
||||
|
|
|
|||
|
|
@ -1,10 +1,12 @@
|
|||
---
|
||||
title: Self-hosting DEV.to
|
||||
title: Self hosting DEV
|
||||
---
|
||||
|
||||
## Hosting Your Own DEV Instance
|
||||
|
||||
We envision that the DEV codebase will eventually be generalized to the point where it can be used to power other communities and ecosystems. We’re excited for the project to mature to that point, but we’re not quite there yet. This page is designed to serve as an FAQ and checklist of considerations that are relevant to the goal of eventually hosting your own version of our community platform.
|
||||
We envision that the DEV codebase will eventually be generalized to the point where it can be used to power other communities and ecosystems. We're excited for the project to mature to that point, but we're not quite there yet.
|
||||
|
||||
This page is designed to serve as a FAQ and a checklist of considerations that are relevant to the goal of eventually hosting your own version of our community platform.
|
||||
|
||||
### Current Limitations
|
||||
|
||||
|
|
@ -16,4 +18,4 @@ We envision that the DEV codebase will eventually be generalized to the point wh
|
|||
- You can help us generalize the code, removing DEV-specific language and images and replacing them with environment variables or database tables as appropriate
|
||||
- You can commit to staying in very close coordination with us as we navigate the process together.
|
||||
|
||||
The long-term benefits of doing this the right way far outweigh the short-term gains of spinning something up without consulting us. If you are interested in getting started with this process, let us know in [this thread](https://dev.to/ben/so-you-want-to-stand-up-your-own-instance-of-dev-help-thread-1elo).
|
||||
The long-term benefits of doing this the right way far outweighs the short-term gains of spinning something up without consulting us. If you are interested in getting started with this process, let us know in [this thread](https://dev.to/ben/so-you-want-to-stand-up-your-own-instance-of-dev-help-thread-1elo).
|
||||
|
|
|
|||
|
|
@ -4,29 +4,29 @@ title: Technical Overview
|
|||
|
||||
## 🔑 Key App tech/services
|
||||
|
||||
- We use [_Puma_](https://github.com/puma/puma) for the server
|
||||
- We [rely heavily on edge caching](https://dev.to/ben/making-devto-insanely-fast) with _Fastly_
|
||||
- We use _Cloudinary_ for image manipulation/serving
|
||||
- We use _Airbrake_ for error monitoring
|
||||
- We use _Timber_ for logging
|
||||
- We use [_Delayed Job_](https://github.com/collectiveidea/delayed_job) for background workers
|
||||
- We use _Algolia_ for search
|
||||
- We use [_Redcarpet_](https://github.com/vmg/redcarpet) and [_Rouge_](https://github.com/jneen/rouge) for Markdown
|
||||
- We use _[Carrierwave](https://github.com/carrierwaveuploader/carrierwave)/Fog/AWS S3_ for image upload/storage
|
||||
- We use a modified version of [_InstantClick_](http://instantclick.io/) instead of _Turbolinks_
|
||||
- We are hosted on _Heroku_
|
||||
- We use _Heroku scheduler_ for scheduled jobs (default)
|
||||
- We use _Sendgrid_ for API-triggered mailing
|
||||
- We use _Mailchimp_ for marketing/outreach emails
|
||||
- We use [_Puma_](https://github.com/puma/puma) as the web server
|
||||
- We [rely heavily on edge caching](https://dev.to/ben/making-devto-insanely-fast) with [_Fastly_](https://www.fastly.com/)
|
||||
- We use [_Cloudinary_](https://cloudinary.com/) for image manipulation/serving
|
||||
- We use [_Airbrake_](https://airbrake.io/) for error monitoring
|
||||
- We use [_Timber_](https://timber.io/) for logging
|
||||
- We use [_Delayed Job_](https://github.com/collectiveidea/delayed_job) and [_Active Job_](https://guides.rubyonrails.org/active_job_basics.html) for background workers
|
||||
- We use [_Algolia_](https://www.algolia.com/) for search
|
||||
- We use [_Redcarpet_](https://github.com/vmg/redcarpet) and [_Rouge_](https://github.com/jneen/rouge) to parse Markdown
|
||||
- We use [_Carrierwave_](https://github.com/carrierwaveuploader/carrierwave), [_Fog_](https://github.com/fog/fog-aws) and [_AWS S3_](https://aws.amazon.com/s3/) for image upload/storage
|
||||
- We use a modified version of [_InstantClick_](http://instantclick.io/) instead of _Turbolinks_ to accelerate navigation
|
||||
- We are hosted on [_Heroku_](https://www.heroku.com)
|
||||
- We use [_Heroku scheduler_](https://devcenter.heroku.com/articles/scheduler) for scheduled jobs
|
||||
- We use [_Sendgrid_](https://sendgrid.com/) for transactional mailing
|
||||
- We use [_Mailchimp_](https://mailchimp.com/) for marketing/outreach emails
|
||||
- We use [_Figaro_](https://github.com/laserlemon/figaro) for app configuration.
|
||||
- We use [_CounterCulture_](https://github.com/magnusvk/counter_culture) to keep track of association counts (counter caches)
|
||||
- We use [_Rolify_](https://github.com/RolifyCommunity/rolify) for role management.
|
||||
- We use [_Pundit_](https://github.com/varvet/pundit) for authorization.
|
||||
- We use Service Workers to proxy traffic
|
||||
- We use Preact for some of the front end. See [Frontend](https://docs.dev.to/frontend/) for more info
|
||||
- We use [_Pusher_](https://pusher.com) for realtime communication between the application and users’ browsers.
|
||||
- We use [_Service Workers_](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers) to proxy traffic
|
||||
- We use [Preact](https://preactjs.com/) for some of the frontend. See [the Frontend Guide](/frontend) for more info
|
||||
- We use [_Pusher_](https://pusher.com) for realtime communication between the application and users' browsers.
|
||||
- We use [_GitDocs_](https://gitdocs.netlify.com) for beautiful and SEO-friendly documentation
|
||||
- We use [git](https://git-scm.com/) for version control.
|
||||
- We use [github](https://github.com/) for issue tracking.
|
||||
- We use [Git](https://git-scm.com/) for version control.
|
||||
- We use [GitHub](https://github.com/) for hosting the source code and issue tracking.
|
||||
|
||||
_This list is non-exhaustive. If you see something that belongs here, feel free to add it._
|
||||
|
|
|
|||
|
|
@ -4,8 +4,31 @@ title: Acceptance Tests
|
|||
|
||||
# Acceptance Tests
|
||||
|
||||
Acceptance tests are tests from the perceptive of the end-user. What the
|
||||
means that we are simulating what a user could do from their web-browser
|
||||
and testing the end expected result.
|
||||
Acceptance tests are tests from the perspective of the end user.
|
||||
|
||||
Acceptance tests can be found at: `spec/system`
|
||||
It means that we are simulating what a user could do from their web browser
|
||||
and testing the expected behavior of the app.
|
||||
|
||||
Acceptance tests can be found in the directory `spec/system` (in Rails terminology these are called "system tests").
|
||||
|
||||
You can run all acceptance tests with:
|
||||
|
||||
```shell
|
||||
bundle exec rspec spec/system
|
||||
```
|
||||
|
||||
To run an individual file you can use for example:
|
||||
|
||||
```shell
|
||||
bundle exec rspec spec/system/user_views_a_reading_list_spec.rb
|
||||
```
|
||||
|
||||
To run a specific test case you can use for example:
|
||||
|
||||
```shell
|
||||
bundle exec rspec spec/system/user_views_a_reading_list_spec.rb:10
|
||||
```
|
||||
|
||||
where `10` is the line number of the test case you want to execute.
|
||||
|
||||
You can read the official guide [Testing Rails Applications](https://guides.rubyonrails.org/testing.html#system-testing) to learn more.
|
||||
|
|
|
|||
53
docs/tests/code-coverage.md
Normal file
53
docs/tests/code-coverage.md
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
---
|
||||
title: Code Coverage
|
||||
---
|
||||
|
||||
# Code coverage
|
||||
|
||||
## Rails
|
||||
|
||||
Rails tests will generate the code coverage at the end of the tests execution.
|
||||
|
||||
To get the code coverage of the whole Rails code base you need to run all the tests with:
|
||||
|
||||
```shell
|
||||
bundle exec rspec
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```shell
|
||||
bin/rspec
|
||||
```
|
||||
|
||||
To get the code coverage of a single file you can run
|
||||
|
||||
```shell
|
||||
bundle exec rspec spec/models/user_spec.rb
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```shell
|
||||
bin/rspec spec/models/user_spec.rb
|
||||
```
|
||||
|
||||
After the test run is complete, open `coverage/index.html` with a browser so you can check the the code coverage.
|
||||
|
||||
## Preact
|
||||
|
||||
Preact tests will generate the code coverage at the end of the tests execution.
|
||||
|
||||
To get the code coverage of the Preact code base you need to run all the tests with:
|
||||
|
||||
```shell
|
||||
npm run test
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```shell
|
||||
yarn test
|
||||
```
|
||||
|
||||
After the test run is complete, you will see the coverage on the console.
|
||||
|
|
@ -1,9 +1,11 @@
|
|||
---
|
||||
title: CodeClimate
|
||||
title: Code Climate
|
||||
---
|
||||
|
||||
# CodeClimate
|
||||
# Code Climate
|
||||
|
||||
We are using CodeClimate to track code quality and code coverage. CodeClimate will grade the quality of the code of every PR but not the entirety of the project. If you feel that the current linting rule is unreasonable, feel free to submit a _separate_ PR to change it. Fix any errors that CodeClimate provides and strive to leave code better than you found it.
|
||||
We are using [Code Climate](https://codeclimate.com/github/thepracticaldev/dev.to) to track code quality and coverage.
|
||||
|
||||
Travis will upload Simplecov data to CodeClimate.
|
||||
Code Climate will grade the quality of the code of every PR but not the entirety of the project. If you want to make improvements to the current linting rule, feel free to submit a PR to change it.
|
||||
|
||||
Fix any errors that Code Climate raises in your PR's build and strive to leave the code better than you found it.
|
||||
|
|
|
|||
|
|
@ -4,14 +4,28 @@ title: Integration Tests
|
|||
|
||||
# Integration Tests
|
||||
|
||||
To understand integration tests lets understand the purpose of a unit
|
||||
test. A unit test is about testing in isolate a single function and all
|
||||
of its possible output.
|
||||
An integration test is when you need to test the interaction of multiple systems or parts of your application.
|
||||
|
||||
An integration test is when you need to test the result of multiple of
|
||||
functions or systems.
|
||||
An integration test may seem similar to an [acceptance test](/tests/acceptance-tests.md). The main difference is that an acceptance test is from the perspective of the end user while an integration test is from the perspective of the developer.
|
||||
|
||||
An integration test may seem similar to a user acceptance test. A user acceptance test is from the perceptive of the end-user where
|
||||
an integration test is from the perceptive of the developer.
|
||||
Integration tests can be found in the directory `spec/requests`.
|
||||
|
||||
Integration tests can be found in: `spec/requests/`
|
||||
You can run all integration tests with:
|
||||
|
||||
```shell
|
||||
bundle exec rspec spec/requests
|
||||
```
|
||||
|
||||
To run an individual file you can use for example:
|
||||
|
||||
```shell
|
||||
bundle exec rspec spec/requests/stories_show_spec.rb
|
||||
```
|
||||
|
||||
To run a specific test case you can use for example:
|
||||
|
||||
```shell
|
||||
bundle exec rspec spec/requests/stories_show_spec.rb:10
|
||||
```
|
||||
|
||||
where `10` is the line number of the test case you want to execute.
|
||||
|
|
|
|||
|
|
@ -2,15 +2,30 @@
|
|||
title: Preact Tests
|
||||
---
|
||||
|
||||
The test code is located within the same directory as the component
|
||||
called `__tests__` so for example
|
||||
# Preact Tests
|
||||
|
||||
```
|
||||
app/javascripts/articl-form/__tests__
|
||||
The test code is located within the same directory as each component,
|
||||
inside a `__tests__` directory.
|
||||
|
||||
```shell
|
||||
$ tree app/javascript/article-form -L 1
|
||||
app/javascript/article-form
|
||||
├── __tests__
|
||||
└── articleForm.jsx
|
||||
```
|
||||
|
||||
The testing library being used is `jest`. To run jest tests:
|
||||
The testing library being used is [Jest](https://jestjs.io/).
|
||||
|
||||
```
|
||||
You can run those tests with:
|
||||
|
||||
```shell
|
||||
npm run test
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```shell
|
||||
yarn test
|
||||
```
|
||||
|
||||
At the end of the tests execution you will see the code coverage for the Preact components tests.
|
||||
|
|
|
|||
|
|
@ -1,31 +1,36 @@
|
|||
---
|
||||
title: Test / Coverage / Q&A Guide
|
||||
title: Testing / Q&A Guide
|
||||
items:
|
||||
- acceptance-tests.md
|
||||
- integration-tests.md
|
||||
- unit-tests.md
|
||||
- unit-functional-tests.md
|
||||
- preact-tests.md
|
||||
- code-coverage.md
|
||||
- codeclimate.md
|
||||
- simplecov.md
|
||||
- skip-ci
|
||||
- skip-ci.md
|
||||
---
|
||||
|
||||
We use the following testing tools:
|
||||
|
||||
- [**RSpec**](http://rspec.info/) for testing the backend
|
||||
- [**Capybara**](https://github.com/teamcapybara/capybara) with [**selenium-webdriver**](https://github.com/SeleniumHQ/selenium/tree/master/javascript/node/selenium-webdriver) for view testing
|
||||
- [**webdrivers**](https://github.com/titusfortner/webdrivers) for standard JS testing
|
||||
- [**RSpec**](http://rspec.info/) for testing the Rails backend
|
||||
- [**Capybara**](https://github.com/teamcapybara/capybara) with [**webdrivers**](https://github.com/titusfortner/webdrivers) for acceptance testing
|
||||
- [**guard-rspec**](https://github.com/guard/guard-rspec) for automated testing
|
||||
- [**Jest**](https://facebook.github.io/jest) for testing in the front-end
|
||||
- [**preact-render-spy**](https://github.com/mzgoddard/preact-render-spy) for testing Preact components.
|
||||
- [**SimpleCov**](https://github.com/colszowka/simplecov) for tracking overall test coverage
|
||||
- [**Jest**](https://jestjs.io/) for testing the frontend
|
||||
- [**preact-render-spy**](https://github.com/mzgoddard/preact-render-spy) for testing Preact components
|
||||
- [**SimpleCov**](https://github.com/colszowka/simplecov) for tracking overall test coverage on the backend
|
||||
|
||||
Each pull request should come with tests related to the newly written feature or bug fix. Ideally, we should test both the front end and back end.
|
||||
Each pull request should come with tests related to the newly written feature or bug fix. Ideally, we should test both the frontend and backend.
|
||||
|
||||
If you'd like to help us improve our test coverage, we recommend checking out our total coverage and writing tests for selected files based on SimpleCov's (more below) test coverage results.
|
||||
If you'd like to help us improve our test coverage, we recommend checking out our total coverage and writing tests for selected files based on SimpleCov's test coverage results. You can also check out [Code Climate summary](https://codeclimate.com/github/thepracticaldev/dev.to) which includes the test coverage.
|
||||
|
||||
If you're new to writing tests in general or with Rails, we recommend reading about testing with Rails, RSpec, and Capybara first.
|
||||
If you're new to writing tests in general or with Rails, we recommend reading about [testing with Rails, RSpec, and Capybara first](https://guides.rubyonrails.org/testing.html).
|
||||
|
||||
## Continuous Integration & Continuous Deployment
|
||||
|
||||
We are using Travis for CI and CD. Travis will run a build (in isolated environment for testing) for every push to this repository. Keep in mind that a passing-build does not necessarily mean the project won't run into any issues. Strive to write good tests for any chunk of code you wish to contribute. Travis will deploy a pull request to production after CI passes. Our test suite is not perfect and sometimes a re-rerun is needed.
|
||||
We are using Travis for CI and CD. Travis will run a build (in an isolated environment for testing) for every push to this repository.
|
||||
|
||||
Keep in mind that a passing build does not necessarily mean the project won't run into any issues. Strive to write good tests for the code you wish to contribute.
|
||||
|
||||
Travis will deploy your pull request to production after CI passes and a member of the DEV team has approved it.
|
||||
|
||||
Our test suite is not perfect and sometimes a re-run is needed.
|
||||
|
|
|
|||
|
|
@ -1,10 +0,0 @@
|
|||
---
|
||||
title: SimpleCov
|
||||
---
|
||||
|
||||
# How to Use SimpleCov
|
||||
|
||||
1. Run `bundle exec rspec spec` or `bin/rspec spec`. You can run RSpec on the whole project or a single file.
|
||||
2. After rspec is complete, open `index.html` within the coverage folder to view code coverages.
|
||||
|
||||
You can also run `bin/rspecov` to run `bin/rspec spec`
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
---
|
||||
title: Skipping CI for minor changes
|
||||
---
|
||||
|
||||
# Skipping CI build (Not recommended)
|
||||
|
||||
If your changes are **minor** (i.e. updating README, fixing a typo), you can skip CI by adding `[ci skip]` to your commit message.
|
||||
7
docs/tests/skip-ci.md
Normal file
7
docs/tests/skip-ci.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
title: Skipping CI for minor changes
|
||||
---
|
||||
|
||||
# Skipping CI build (not recommended)
|
||||
|
||||
If your changes are **minor** (ie. updating the README or fixing a typo), you can skip CI by adding `[ci skip]` to your commit message.
|
||||
35
docs/tests/unit-functional-tests.md
Normal file
35
docs/tests/unit-functional-tests.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
---
|
||||
title: Unit and Functional Tests
|
||||
---
|
||||
|
||||
# Unit and Functional Tests
|
||||
|
||||
A unit test is about testing a single function/method in isolation with all of its possible outputs.
|
||||
|
||||
A functional test is about testing a single functionality, which can span multiple methods and a controller.
|
||||
|
||||
Other common terms in Rails are "model tests", "controller tests" and others.
|
||||
|
||||
You can find model tests in `spec/models`, controller tests in `spec/controllers` and additional functional tests in various directories within the `spec` directory.
|
||||
|
||||
You can run all models tests, for example, with:
|
||||
|
||||
```shell
|
||||
bundle exec rspec spec/models
|
||||
```
|
||||
|
||||
To run an individual file you can use for example:
|
||||
|
||||
```shell
|
||||
bundle exec rspec spec/models/user_spec.rb
|
||||
```
|
||||
|
||||
To run a specific test case you can use for example:
|
||||
|
||||
```shell
|
||||
bundle exec rspec spec/models/user_spec.rb:10
|
||||
```
|
||||
|
||||
where `10` is the line number of the test case you want to execute.
|
||||
|
||||
You can read the official guide [Testing Rails Applications](https://guides.rubyonrails.org/testing.html) to learn more.
|
||||
|
|
@ -1,16 +0,0 @@
|
|||
---
|
||||
title: Unit Tests
|
||||
---
|
||||
|
||||
# Unit Tests
|
||||
|
||||
A unit test is about testing in isolate a single function and all of its possible output.
|
||||
|
||||
Unit tests can be found in
|
||||
|
||||
`spec/models` and other various directories within the `spec`
|
||||
directory.
|
||||
|
||||
`spec/system` is for integration tests
|
||||
|
||||
`spec/requets` is for acceptance tests
|
||||
Loading…
Add table
Reference in a new issue