Improve the clarity of the docs and fix Prettier config (#4899)
* Improve format and clarity of the docs [ci skip] While this change produces a lot of git noise by enacting what seems like an arbitrary linewrap on most of the files in the documentation it will result in better version control and tracking of the changes in the documentation. For example, as it currently stands, if one was to make a PR to move a comma in a sentence because each paragraph in most of the files is on a single line, that small change would look in the git history like the author had modified the entire paragraph. In reality, this author just moved a comma. This change also includes a significant number of modifications to the more article-esque docs. Many of these docs were written in a sort of stream-of-conciousness and aren't as easy to read as they could be. Hopefully this is the first of several readability changes. If we could get these docs to a more accessible reading level, we would probably see an increase in contributions. :) * Delegate markdown wrapping to Prettier * Add linewrapping explanation in the docs [ci skip]
This commit is contained in:
Jacob Herrington
Ben Halpern
parent
4dabe265c6
commit
7d0aeeefe5
52 changed files with 980 additions and 374 deletions
|
|
@ -6,7 +6,8 @@ title: Admin Panel
|
|||
|
||||
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 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:
|
||||
|
||||
|
|
@ -25,4 +26,5 @@ Loading development environment (Rails 5.2.3)
|
|||
[3] pry(main)> user.save!
|
||||
```
|
||||
|
||||
Now you'll be able to access the [administration panel](http://localhost:3000/admin).
|
||||
Now you'll be able to access the [administration
|
||||
panel](http://localhost:3000/admin).
|
||||
|
|
|
|||
|
|
@ -4,11 +4,15 @@ title: Algolia
|
|||
|
||||
## Algolia for Search
|
||||
|
||||
Algolia is a third party service that powers the search. When working with the API, you will likely 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 that powers the search. When working with the
|
||||
API, you will likely 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.
|
||||
|
||||
## Sign up
|
||||
|
||||
1. Go to the Algolia sign up [page](https://www.algolia.com/apps/AJVD3Q9KL3/dashboard).
|
||||
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.
|
||||
|
||||
|
|
@ -36,13 +40,15 @@ Algolia is a third party service that powers the search. When working with the A
|
|||
|
||||
## Get API keys
|
||||
|
||||
1. [Sign up](#algolia-sign-up) or [Sign in](https://www.algolia.com/users/sign_in) to your Algolia account.
|
||||
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):
|
||||
3. Change your keys accordingly (name of Algolia key -> name of our `ENV`
|
||||
variable):
|
||||
|
||||
```text
|
||||
Application ID -> ALGOLIASEARCH_APPLICATION_ID
|
||||
|
|
|
|||
|
|
@ -4,15 +4,23 @@ title: GitHub Authentication
|
|||
|
||||
# GitHub App and Authentication
|
||||
|
||||
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.
|
||||
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. [Click this link to create a new OAuth application in your Github account](https://github.com/settings/applications/new) - you will be redirected to sign in to Github account if you have not already.
|
||||
1. [Click this link to create a new OAuth application in your Github
|
||||
account](https://github.com/settings/applications/new) - you will be
|
||||
redirected to sign in to Github account if you have not already.
|
||||
|
||||
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.
|
||||
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 to 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 to 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
|
||||
|
|
@ -21,13 +29,16 @@ DEV allows you to authenticate using GitHub. To use this authentication method i
|
|||
|
||||
|
||||
|
||||
4. You will need a personal token as well. From the same dashboard, navigate to **Personal access tokens** and generate a new token.
|
||||
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. You don't need to select any of the scopes.
|
||||
5. Fill in the token description and generate the token. You don't need to
|
||||
select any of the scopes.
|
||||
|
||||
6. Be sure that you copy the token right away because it is the only time you will see it. Change it accordingly.
|
||||
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
|
||||
|
|
|
|||
|
|
@ -4,25 +4,34 @@ title: Twitter Authentication
|
|||
|
||||
# Twitter App and Authentication
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## 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](https://developer.twitter.com/en/apply-for-access). Click the **Apply** button.
|
||||
|
||||
2. In order to get the API keys, you will have to
|
||||
[apply for a developer account](https://developer.twitter.com/en/apply-for-access). Click the **Apply** button.
|
||||
|
||||
|
||||
|
||||
3. Setup your Twitter account. Be sure you have your phone number and email address filled in.
|
||||
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**.
|
||||
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's 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 ;)
|
||||
|
||||
|
||||
|
||||
|
|
@ -36,7 +45,8 @@ DEV allows you to authenticate using Twitter. In order to use this authenticatio
|
|||
|
||||
## Get API keys
|
||||
|
||||
1. [Sign up](#twitter-sign-up) or [sign in](https://developer.twitter.com/apps) to your Twitter developer account.
|
||||
1. [Sign up](#twitter-sign-up) or [sign in](https://developer.twitter.com/apps)
|
||||
to your Twitter developer account.
|
||||
|
||||
2. From **Apps** dashboard, click on **Create and app**.
|
||||
|
||||
|
|
@ -45,11 +55,14 @@ DEV allows you to authenticate using Twitter. In order to use this authenticatio
|
|||
|
||||
|
||||
|
||||
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).
|
||||
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`.
|
||||
5. Fill in the DEV information, **Terms of Service** `http://dev.to/terms` and
|
||||
**Privacy policy** `http://dev.to/privacy`.
|
||||
|
||||
|
||||
|
||||
|
|
@ -57,17 +70,21 @@ DEV allows you to authenticate using Twitter. In order to use this authenticatio
|
|||
|
||||
|
||||
|
||||
7. Review the [Twitter Developer Terms](https://developer.twitter.com/en/developer-terms/agreement-and-policy.html) and agree to do nothing sketchy.
|
||||
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.
|
||||
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):
|
||||
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
|
||||
|
|
|
|||
|
|
@ -4,9 +4,11 @@ title: Authentication
|
|||
|
||||
# Authentication
|
||||
|
||||
Authentication 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 you can only authenticate through GitHub or Twitter. Please check out the respective guides on how to authenticate:
|
||||
On DEV you can only authenticate through GitHub or Twitter. Please check out the
|
||||
respective guides on how to authenticate:
|
||||
|
||||
- [Github authentication](/backend/auth-github)
|
||||
- [Twitter authentication](/backend/auth-twitter)
|
||||
|
|
|
|||
|
|
@ -4,7 +4,9 @@ title: Authorization
|
|||
|
||||
# Authorization
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
```ruby
|
||||
authorize @user
|
||||
|
|
|
|||
|
|
@ -4,9 +4,13 @@ title: Notifications
|
|||
|
||||
# Notifications
|
||||
|
||||
Since notifications are run asynchronously, we'll want to make sure jobs are running: `bin/rails jobs:work`. If that's not running, you won't receive any notifications. You might need to create another account to pass notifications back and forth if you're doing this all through the UI.
|
||||
Since notifications are run asynchronously, we'll want to make sure jobs are
|
||||
running: `bin/rails jobs:work`. If that's not running, you won't receive any
|
||||
notifications. You might need to create another account to pass notifications
|
||||
back and forth if you're doing this all through the UI.
|
||||
|
||||
Otherwise, you can generate notifications from the Rails console and run the class methods from `app/models/notification.rb`. For example:
|
||||
Otherwise, you can generate notifications from the Rails console and run the
|
||||
class methods from `app/models/notification.rb`. For example:
|
||||
|
||||
```ruby
|
||||
# follow notification
|
||||
|
|
@ -22,4 +26,5 @@ reactable: me.articles.last, # this assumes you have an article written
|
|||
Notification.send_reaction_notification_without_delay(rxn, me)
|
||||
```
|
||||
|
||||
Notice you have to run these methods `without_delay` since this is assuming jobs are not running.
|
||||
Notice you have to run these methods `without_delay` since this is assuming jobs
|
||||
are not running.
|
||||
|
|
|
|||
|
|
@ -4,13 +4,15 @@ title: Pusher
|
|||
|
||||
# Pusher for Realtime Notifications
|
||||
|
||||
Pusher is a third party service being used to power the [chat system](https://dev.to/connect).
|
||||
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 your development environment,
|
||||
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.
|
||||
In order to use the chat functionality within your development environment, 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.
|
||||
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.
|
||||
|
||||
|
|
@ -20,7 +22,8 @@ its keys. Then you'll need to provide those keys to the Rails application.
|
|||
|
||||
|
||||
|
||||
4. Change your keys accordingly (name of Pusher key -> name of our application key):
|
||||
4. Change your keys accordingly (name of Pusher key -> name of our application
|
||||
key):
|
||||
|
||||
```text
|
||||
app_id -> PUSHER_APP_ID
|
||||
|
|
|
|||
|
|
@ -6,17 +6,24 @@ title: Roles
|
|||
|
||||
## What is a role?
|
||||
|
||||
If authorization is about who has permission to be allowed to do what you want to do, then Roles are common patterns of authorization across users - reducing the administrative overhead.
|
||||
If authorization is about who has permission to be allowed to do what you want
|
||||
to do, then Roles are common patterns of authorization across users - reducing
|
||||
the administrative overhead.
|
||||
|
||||
## Why do I need to know about roles?
|
||||
|
||||
Some bugs can only be seen for users with specific roles. You will need to change the role to reproduce a problem.
|
||||
Some bugs can only be seen for users with specific roles. You will need to
|
||||
change the role to reproduce a problem.
|
||||
|
||||
## How do we implement roles in DEV.to?
|
||||
|
||||
Roles are implemented in this application using [Rolify][1]. The list of roles can be found in [app/models/role.rb][2] and you can search for [has_role in the codebase][3] to find which pages need which roles.
|
||||
Roles are implemented in this application using [Rolify][1]. The list of roles
|
||||
can be found in [app/models/role.rb][2] and you can search for [has_role in the
|
||||
codebase][3] to find which pages need which roles.
|
||||
|
||||
A new user starts without any roles, and there is no administrative way of adding roles to users yet. To assign a user a role you will have to run commands at the console.
|
||||
A new user starts without any roles, and there is no administrative way of
|
||||
adding roles to users yet. To assign a user a role you will have to run commands
|
||||
at the console.
|
||||
|
||||
## Example of adding permissions to a user
|
||||
|
||||
|
|
@ -26,7 +33,8 @@ A new user starts without any roles, and there is no administrative way of addin
|
|||
rails console
|
||||
```
|
||||
|
||||
- after verifying the user `test_user_name` is missing the `pro` role we proceed to add it and then verify the role has been added:
|
||||
- after verifying the user `test_user_name` is missing the `pro` role we proceed
|
||||
to add it and then verify the role has been added:
|
||||
|
||||
```ruby
|
||||
> user = User.find_by(username: "test_user_name")
|
||||
|
|
@ -43,7 +51,8 @@ name: "pro"
|
|||
=> true
|
||||
```
|
||||
|
||||
Another common requirement is changing to the administrative role, and an example of this is found [on the admin page][5].
|
||||
Another common requirement is changing to the administrative role, and an
|
||||
example of this is found [on the admin page][5].
|
||||
|
||||
## Verification
|
||||
|
||||
|
|
|
|||
|
|
@ -4,9 +4,13 @@ title: Scheduled Jobs
|
|||
|
||||
# Scheduled Jobs
|
||||
|
||||
As in the [Technical Overview](/technical-overview), We use [Heroku Scheduler](https://devcenter.heroku.com/articles/scheduler) for scheduled jobs. As the name suggests, this is for regularly recurring tasks that need to be run every day, week, month, year, decade, and century.
|
||||
As in the [Technical Overview](/technical-overview), We use [Heroku
|
||||
Scheduler](https://devcenter.heroku.com/articles/scheduler) for scheduled jobs.
|
||||
As the name suggests, this is for regularly recurring tasks that need to be run
|
||||
every day, week, month, year, decade, and century.
|
||||
|
||||
Tasks are implemented in `dev.to/lib/tasks/fetch.rake`, typically in the form of:
|
||||
Tasks are implemented in `dev.to/lib/tasks/fetch.rake`, typically in the form
|
||||
of:
|
||||
|
||||
```
|
||||
task some_unique_task_name:, [optional_arg] => :environment do |optional_arg|
|
||||
|
|
@ -14,6 +18,11 @@ task some_unique_task_name:, [optional_arg] => :environment do |optional_arg|
|
|||
end
|
||||
```
|
||||
|
||||
You can explore the [official Heroku documentation](https://devcenter.heroku.com/articles/scheduler#defining-tasks) for defining tasks and read through tasks we have implemented for busting cache, awarding badges, and more.
|
||||
You can explore the [official Heroku
|
||||
documentation](https://devcenter.heroku.com/articles/scheduler#defining-tasks)
|
||||
for defining tasks and read through tasks we have implemented for busting cache,
|
||||
awarding badges, and more.
|
||||
|
||||
In your Pull Request, communicate with a DEV Core Team Member to discuss at what frequency and ensure your task is scheduled on Heroku once your code is reviewed, approved, and merged.
|
||||
In your Pull Request, communicate with a DEV Core Team Member to discuss at what
|
||||
frequency and ensure your task is scheduled on Heroku once your code is
|
||||
reviewed, approved, and merged.
|
||||
|
|
|
|||
|
|
@ -1,42 +1,80 @@
|
|||
---
|
||||
title: Contributing to Docs
|
||||
title: Contributing to the Docs
|
||||
---
|
||||
|
||||
# Contributing to Docs
|
||||
# Contributing to DEV's developer documentation
|
||||
|
||||
The documentation you are reading is powered by [GitDocs](https://github.com/timberio/gitdocs).
|
||||
Contributions to the documentation are always appreciated! Thank you for making
|
||||
an effort to improve the developer experience of contributing to the DEV
|
||||
project.
|
||||
|
||||
## Where The Docs Are Located
|
||||
# Running the documentation locally
|
||||
|
||||
This documentation is located in the [DEV.to codebase](https://github.com/thepracticaldev/dev.to) within the `/docs` directory.
|
||||
Like DEV, this site is open source and the code is [hosted on GitHub][docs]. If
|
||||
you find any incorrect information, or a even a typo, we'd love to see a pull
|
||||
request. Follow these steps to get the documentation site running locally.
|
||||
|
||||
The docs are a collection of [Markdown files](https://en.wikipedia.org/wiki/Markdown) that also utilize [FrontMatter](https://jekyllrb.com/docs/front-matter/).
|
||||
DEV's documentation is built with [GitDocs NodeJS library][gitdocs].
|
||||
|
||||
For more information on how to use GitDocs read the [GitDocs guide](https://gitdocs.netlify.com)
|
||||
The first step to running the documentations locally is to install the `GitDocs`
|
||||
package globally.
|
||||
|
||||
## Running the Docs Locally
|
||||
|
||||
Install the [GitDocs NodeJS library](https://www.npmjs.com/package/gitdocs):
|
||||
With npm:
|
||||
|
||||
```shell
|
||||
npm install gitdocs -g
|
||||
```
|
||||
|
||||
Specifying `-g` will install the library globally, which is what you want to do.
|
||||
|
||||
If you use yarn you can instead issue:
|
||||
Alternatively, you can use Yarn:
|
||||
|
||||
```shell
|
||||
yarn global add gitdocs
|
||||
```
|
||||
|
||||
Once installed, you can run `gitdocs serve` from the root of the dev.to project or from the `/docs` directory.
|
||||
Once installed, you should run `gitdocs serve` from the root of the dev.to
|
||||
project or from the `/docs` directory.
|
||||
|
||||
```shell
|
||||
gitdocs serve
|
||||
```
|
||||
|
||||
This will start a server where you can browse the documentation: <http://localhost:8000/>
|
||||
This will start a server where you can browse the documentation:
|
||||
<http://localhost:8000/>
|
||||
|
||||
When you add new markdown pages or rename existing ones, you'll have to restart
|
||||
the server before you notice any changes.
|
||||
If you add new pages or rename existing pages, you'll need to restart the server
|
||||
for those changes to take effect.
|
||||
|
||||
# Useful links
|
||||
|
||||
The docs are a collection of [Markdown files][markdown] that also utilize
|
||||
[FrontMatter][frontmatter].
|
||||
|
||||
For more information on how to use GitDocs read the [GitDocs
|
||||
guide][gitdocs_guide].
|
||||
|
||||
# Regarding style
|
||||
|
||||
Generally speaking, the documentation hosted on this site is informal. There is
|
||||
no need to make things more complicated by writing these articles like a
|
||||
textbooks.
|
||||
|
||||
However, it's expected that contributions to these documents are reasonably
|
||||
structured and mostly free of spelling and grammar errors. For this reason, if
|
||||
you submit a PR you might be asked to make changes before your PR is merged.
|
||||
|
||||
Prettier is used to autowrap lines in these files to 80 characters. Using 80
|
||||
characters per line allows us to retain a more specific git history over time.
|
||||
If lines are not wrapped, changing a comma in a paragraph would attribute the
|
||||
entire paragraph to one commit. By line wrapping we are helping git to correctly
|
||||
attribute smaller changes to their commits. This keeps information from getting
|
||||
lost over time.
|
||||
|
||||
For more information on effective technical writing, check out
|
||||
[writethedocs.org][writethedocs].
|
||||
|
||||
[docs]: https://github.com/thepracticaldev/dev.to/tree/master/docs/
|
||||
[gitdocs]: https://www.npmjs.com/package/gitdocs/
|
||||
[markdown]: https://en.wikipedia.org/wiki/Markdown
|
||||
[frontmatter]: https://jekyllrb.com/docs/front-matter/
|
||||
[gitdocs_guide]: https://gitdocs.netlify.com/
|
||||
[writethedocs]: https://www.writethedocs.org/guide/
|
||||
|
|
|
|||
|
|
@ -1,21 +1,24 @@
|
|||
---
|
||||
title: Contributing to API spec docs
|
||||
title: Contributing to the API Specification Docs
|
||||
---
|
||||
|
||||
# Contributing to API spec docs
|
||||
|
||||
The API docs follow the [OpenAPI 3 specification](http://spec.openapis.org/oas/v3.0.2).
|
||||
The API docs follow the [OpenAPI 3
|
||||
specification](http://spec.openapis.org/oas/v3.0.2).
|
||||
|
||||
## Where The Docs Are Located
|
||||
## Where the docs are located
|
||||
|
||||
We auto-generate the documentation from `api_v0.yml` within the `/docs` directory.
|
||||
We use [ReDoc](https://github.com/Redocly/redoc) to turn the OpenAPI 3 format into a readable and searchable HTML documentation.
|
||||
We auto-generate the documentation from `api_v0.yml` within the `/docs`
|
||||
directory. We use [ReDoc](https://github.com/Redocly/redoc) to turn the OpenAPI
|
||||
3 format into a readable and searchable HTML documentation.
|
||||
|
||||
## Updating API docs
|
||||
|
||||
Whenever you make changes to the API docs, make sure to bump the version in `api_v0.yml`.
|
||||
Whenever you make changes to the API docs, make sure to bump the version in
|
||||
`api_v0.yml`.
|
||||
|
||||
## Running and editing the Docs Locally
|
||||
## Running and editing the docs locally
|
||||
|
||||
If you want to browse the documentation locally you can use:
|
||||
|
||||
|
|
@ -23,11 +26,13 @@ If you want to browse the documentation locally you can use:
|
|||
yarn api-docs:serve
|
||||
```
|
||||
|
||||
This will let you browse the auto-generated version of the doc locally, and it will reload the doc after every modification
|
||||
of the spec file.
|
||||
This will let you browse the auto-generated version of the doc locally, and it
|
||||
will reload the doc after every modification of the spec file.
|
||||
|
||||
If you have Visual Studio Code, we suggest you install the following extensions that enable validation and navigation within
|
||||
the spec file:
|
||||
If you have Visual Studio Code, we suggest you install the following extensions
|
||||
that enable validation and navigation within the spec file:
|
||||
|
||||
- [OpenAPI (Swagger) editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi)
|
||||
- [openapi-designer live preview](https://marketplace.visualstudio.com/items?itemName=philosowaffle.openapi-designer)
|
||||
- [OpenAPI (Swagger)
|
||||
editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi)
|
||||
- [openapi-designer live
|
||||
preview](https://marketplace.visualstudio.com/items?itemName=philosowaffle.openapi-designer)
|
||||
|
|
|
|||
|
|
@ -6,15 +6,23 @@ title: Deployment and CI/CD Process
|
|||
|
||||
## Overview
|
||||
|
||||
DEV relies on GitHub and Travis to deploy continuously to Heroku. If a Pull Request is merged with a `[deploy]` in its title, it will be automatically deployed to production once the build steps complete successfully. The process currently takes about 20 minutes to complete and will need a few additional minutes before the change goes live.
|
||||
DEV relies on GitHub and Travis to deploy continuously to Heroku. If a Pull
|
||||
Request is merged with a `[deploy]` in its title, it will be automatically
|
||||
deployed to production once the build steps complete successfully. The process
|
||||
currently takes about 20 minutes to complete and will need a few additional
|
||||
minutes before the change goes live.
|
||||
|
||||
## Travis steps
|
||||
|
||||
The following steps can be explored in our [.travis.yml](https://github.com/thepracticaldev/dev.to/blob/master/.travis.yml) and [Procfile](https://github.com/thepracticaldev/dev.to/blob/master/Procfile). Some of the steps will be parallelized in the future:
|
||||
The following steps can be explored in our
|
||||
[.travis.yml](https://github.com/thepracticaldev/dev.to/blob/master/.travis.yml)
|
||||
and [Procfile](https://github.com/thepracticaldev/dev.to/blob/master/Procfile).
|
||||
Some of the steps will be parallelized in the future:
|
||||
|
||||
1. Travis runs the test portion of Rails code.
|
||||
1. Travis runs the test portion of Preact code.
|
||||
1. CodeClimate-test-reporter combines the test result and coverage from Ruby and JavaScript code then uploads it to our CodeClimate dashboard.
|
||||
1. CodeClimate-test-reporter combines the test result and coverage from Ruby and
|
||||
JavaScript code then uploads it to our CodeClimate dashboard.
|
||||
1. `bundle-audit` checks for any known vulnerability.
|
||||
1. Travis builds Storybook to ensure its integrity.
|
||||
1. Travis deploys code to Heroku.
|
||||
|
|
@ -25,6 +33,16 @@ The following steps can be explored in our [.travis.yml](https://github.com/thep
|
|||
|
||||
## Deploying to Heroku
|
||||
|
||||
We use Heroku's [Release Phase](https://devcenter.heroku.com/articles/release-phase) feature. Upon deploy, the app installs dependencies, bundles assets, and gets the app ready for launch. However, before it launches and releases the app Heroku runs a release script on a one-off dyno. If that release script/step succeeds the new app is released on all of the dynos. If that release script/step fails then the deploy is halted and we are notified. During this release step, we have chosen to run migrations. This ensures that a migration finishes successfully before the code that uses it goes live. We deploy asynchronously, so the website is running the new code a few minutes after deploy. A new instance of Heroku Rails console will immediately run a new code.
|
||||
We use Heroku's [Release
|
||||
Phase](https://devcenter.heroku.com/articles/release-phase) feature. Upon
|
||||
deploy, the app installs dependencies, bundles assets, and gets the app ready
|
||||
for launch. However, before it launches and releases the app Heroku runs a
|
||||
release script on a one-off dyno. If that release script/step succeeds the new
|
||||
app is released on all of the dynos. If that release script/step fails then the
|
||||
deploy is halted and we are notified. During this release step, we have chosen
|
||||
to run migrations. This ensures that a migration finishes successfully before
|
||||
the code that uses it goes live. We deploy asynchronously, so the website is
|
||||
running the new code a few minutes after deploy. A new instance of Heroku Rails
|
||||
console will immediately run a new code.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -6,22 +6,35 @@ title: Branding Guidelines
|
|||
|
||||
## 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).
|
||||
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.
|
||||
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 have been "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
|
||||
|
||||
- [Joystick](http://www.pixelsagas.com/?download=joystick) should be used for logos, not for headlines/phrases.
|
||||
- [Joystick](http://www.pixelsagas.com/?download=joystick) should be used for
|
||||
logos, not for headlines/phrases.
|
||||
- Black and white is our default logo, but the logo can be drawn in any color.
|
||||
- DEV is "old school cool."
|
||||
- We use bold shadows (no gradient) for boxes.
|
||||
- We have a minimal approach to importing dependencies, so few if any custom fonts on-site for that reason.
|
||||
- Refer to the `variables.css` [file in our main repo](https://github.com/thepracticaldev/dev.to/blob/master/app/assets/stylesheets/variables.scss) to reference commonly-used colors and fonts.
|
||||
- We have a minimal approach to importing dependencies, so few if any custom
|
||||
fonts on-site for that reason.
|
||||
- Refer to the `variables.css` [file in our main
|
||||
repo](https://github.com/thepracticaldev/dev.to/blob/master/app/assets/stylesheets/variables.scss)
|
||||
to reference commonly-used colors and fonts.
|
||||
|
||||
## Design License Info
|
||||
|
||||
- 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.
|
||||
- We use [EmojiOne](https://www.emojione.com/) icons from JoyPixels. We have a commercial license.
|
||||
- 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.
|
||||
- We use [EmojiOne](https://www.emojione.com/) icons from JoyPixels. We have a
|
||||
commercial license.
|
||||
|
|
|
|||
|
|
@ -6,9 +6,12 @@ title: Theming Guidelines
|
|||
|
||||
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.
|
||||
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`.
|
||||
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:
|
||||
|
||||
|
|
@ -43,7 +46,10 @@ An example of how it works:
|
|||
--theme-social-icon-invert: invert(100)</style>'
|
||||
```
|
||||
|
||||
Within SCSS files located at `app/assets/stylesheets` you can use `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 can be a SCSS variable defined in `app/assets/stylesheets/variables.scss`.
|
||||
Within SCSS files located at `app/assets/stylesheets` you can use `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 can be a SCSS variable defined in `app/assets/stylesheets/variables.scss`.
|
||||
|
||||
An example of how to use `var()`:
|
||||
|
||||
|
|
@ -53,7 +59,9 @@ div {
|
|||
}
|
||||
```
|
||||
|
||||
Note that fallback values aren't used to fix the browser compatibility. If the browser doesn't support CSS custom Properties, the fallback value won't help. To prevent this issue on older browsers, we need to write our styles like this:
|
||||
Note that fallback values aren't used to fix the browser compatibility. If the
|
||||
browser doesn't support CSS custom Properties, the fallback value won't help. To
|
||||
prevent this issue on older browsers, we need to write our styles like this:
|
||||
|
||||
```scss
|
||||
div {
|
||||
|
|
@ -62,7 +70,13 @@ div {
|
|||
}
|
||||
```
|
||||
|
||||
This can be too much work and browser fallback can be forgotten. For a better developer experience, you should use the two mixins defined in `app/assets/stylesheets/_mixins.scss` called `themeable` and `themeable-important`. They take three arguments. The first argument is the CSS property like `color` or `background`, the second argument is the CSS custom property name (without `--`) like `theme-color`, and the third argument is the CSS value, i.e., `$black` or `white`.
|
||||
This can be too much work and browser fallback can be forgotten. For a better
|
||||
developer experience, you should use the two mixins defined in
|
||||
`app/assets/stylesheets/_mixins.scss` called `themeable` and
|
||||
`themeable-important`. They take three arguments. The first argument is the CSS
|
||||
property like `color` or `background`, the second argument is the CSS custom
|
||||
property name (without `--`) like `theme-color`, and the third argument is the
|
||||
CSS value, i.e., `$black` or `white`.
|
||||
|
||||
Make sure to import the mixin in your SCSS file and use it like this:
|
||||
|
||||
|
|
@ -72,8 +86,12 @@ div {
|
|||
}
|
||||
```
|
||||
|
||||
`themeable-important` is used when a CSS variable requires `!important` as a postfix of the CSS property's value where the CSS variable is being used. You can use it the same way you would use `themeable` mixin, but you should avoid `!important` if possible.
|
||||
`themeable-important` is used when a CSS variable requires `!important` as a
|
||||
postfix of the CSS property's value where the CSS variable is being used. You
|
||||
can use it the same way you would use `themeable` mixin, but you should avoid
|
||||
`!important` if possible.
|
||||
|
||||
# Other user config
|
||||
|
||||
In addition to themes, users can also directly configure their preferred fonts and their nav bar preferences. The implementation of these is similar to themes.
|
||||
In addition to themes, users can also directly configure their preferred fonts
|
||||
and their nav bar preferences. The implementation of these is similar to themes.
|
||||
|
|
|
|||
14
docs/faqs.md
14
docs/faqs.md
|
|
@ -11,18 +11,22 @@ cd docs
|
|||
make ruby-doc
|
||||
```
|
||||
|
||||
Then open `.static/ruby-doc/index.html` in the `docs` directory and browse the Ruby documentation
|
||||
Then open `.static/ruby-doc/index.html` in the `docs` directory and browse the
|
||||
Ruby documentation
|
||||
|
||||
## How do I fix the Error `role "ec2-user" does not exist` on an AWS instance?
|
||||
|
||||
After installing and configuring PostgreSQL on an AWS EC2 (or AWS Cloud9) instance and running `bin/setup`, this error could occur.
|
||||
After installing and configuring PostgreSQL on an AWS EC2 (or AWS Cloud9)
|
||||
instance and running `bin/setup`, this error could occur.
|
||||
|
||||
To fix it, run the following two commands in a terminal (assuming your PostgreSQL user is named **postgres**):
|
||||
To fix it, run the following two commands in a terminal (assuming your
|
||||
PostgreSQL user is named **postgres**):
|
||||
|
||||
```
|
||||
sudo -u postgres createuser -s ec2-user
|
||||
sudo -u postgres createdb ec2-user
|
||||
```
|
||||
|
||||
The first command creates the user **ec2-user** and the second one creates the database for this user because every user needs its database.
|
||||
Even if the first command fails, run the second command to create the missing database.
|
||||
The first command creates the user **ec2-user** and the second one creates the
|
||||
database for this user because every user needs its database. Even if the first
|
||||
command fails, run the second command to create the missing database.
|
||||
|
|
|
|||
|
|
@ -6,25 +6,42 @@ title: Debugging
|
|||
|
||||
## In Browser
|
||||
|
||||
Browsers ship with their own developer tools. These are amazing tools to help you debug your web application. Consider learning how to use them.
|
||||
Browsers ship with their own developer tools. These are amazing tools to help
|
||||
you debug your web application. Consider learning how to use them.
|
||||
|
||||
- [Chrome Developer Tools](https://developers.google.com/web/tools/chrome-devtools)
|
||||
- [Chrome Developer
|
||||
Tools](https://developers.google.com/web/tools/chrome-devtools)
|
||||
- [Firefox Developer Tools](https://developer.mozilla.org/en-US/docs/Tools)
|
||||
- [Safari Developer Tools](https://support.apple.com/en-ca/guide/safari/sfri20948/mac)
|
||||
- [Safari Developer
|
||||
Tools](https://support.apple.com/en-ca/guide/safari/sfri20948/mac)
|
||||
|
||||
## Visual Studio Code
|
||||
|
||||
[Visual Studio Code](https://code.visualstudio.com) (VS Code) is a popular editor that allows you to debug many languages including JavaScript. Thanks to remote debugging technologies, we can debug our frontend code in VS Code. When you clone the DEV repository and open the project in VS Code, you will be prompted to install recommended extensions which include the [Chrome Debugger](https://code.visualstudio.com/blogs/2016/02/23/introducing-chrome-debugger-for-vs-code) and the [Edge Debugger](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-edge).
|
||||
[Visual Studio Code](https://code.visualstudio.com) (VS Code) is a popular
|
||||
editor that allows you to debug many languages including JavaScript. Thanks to
|
||||
remote debugging technologies, we can debug our frontend code in VS Code. When
|
||||
you clone the DEV repository and open the project in VS Code, you will be
|
||||
prompted to install recommended extensions which include the [Chrome
|
||||
Debugger](https://code.visualstudio.com/blogs/2016/02/23/introducing-chrome-debugger-for-vs-code)
|
||||
and the [Edge
|
||||
Debugger](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-edge).
|
||||
|
||||
Setup:
|
||||
|
||||
- Refer to the respective debugger extension documentation above to ensure that your browser is running with remote debugging enabled.
|
||||
- Once you have your local installation of DEV running, you can attach to either the Chrome or Edge Debugger.
|
||||
- Refer to the respective debugger extension documentation above to ensure that
|
||||
your browser is running with remote debugging enabled.
|
||||
- Once you have your local installation of DEV running, you can attach to either
|
||||
the Chrome or Edge Debugger.
|
||||
|
||||
|
||||
|
||||
|
||||
- From there you can do all the usual stuff that you would do while debugging JavaScript in the browser: setting breakpoints, setting [logpoints](https://code.visualstudio.com/docs/editor/debugging#_logpoints), watches etc.
|
||||
- From there you can do all the usual stuff that you would do while debugging
|
||||
JavaScript in the browser: setting breakpoints, setting
|
||||
[logpoints](https://code.visualstudio.com/docs/editor/debugging#_logpoints),
|
||||
watches etc.
|
||||
|
||||
## Where is My Editor Debug Configuration?
|
||||
|
||||
If you do not see your editor here, consider contributing to the documentation. 😉
|
||||
If you do not see your editor here, consider contributing to the documentation.
|
||||
😉
|
||||
|
|
|
|||
|
|
@ -4,17 +4,28 @@ title: Liquid Tags
|
|||
|
||||
# Liquid Tags
|
||||
|
||||
Liquid tags are special elements of the [DEV Markdown editor](https://dev.to/new).
|
||||
Liquid tags are special elements of the [DEV Markdown
|
||||
editor](https://dev.to/new).
|
||||
|
||||
They are custom embeds that are added via a `{% %}` 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.
|
||||
Liquid embeds are for tweets, like `{% tweet 765282762081329153 %}` or a DEV
|
||||
user profile preview, like `{% user jess %}` etc.
|
||||
|
||||
They make for good community contributions because they can be extended and improved consistently. It is truly how we extend the functionality of the editor. At the moment, there could be a lot of work refactoring and improving existing liquid tags, in addition to adding new ones.
|
||||
They make for good community contributions because they can be extended and
|
||||
improved consistently. It is truly how we extend the functionality of the
|
||||
editor. At the moment, there could be a lot of work refactoring and improving
|
||||
existing liquid tags, in addition to adding new ones.
|
||||
|
||||
Liquid tags are sort of like functions, which have a name and take arguments. Develop them with that mindset in terms of naming things. They should be documented but also intuitive. They should also be fairly flexible in the arguments they take. Currently, this could use improvements.
|
||||
Liquid tags are sort of like functions, which have a name and take arguments.
|
||||
Develop them with that mindset in terms of naming things. They should be
|
||||
documented but also intuitive. They should also be fairly flexible in the
|
||||
arguments they take. Currently, this could use improvements.
|
||||
|
||||
Liquid tags are "compiled" when an article is saved. So you will need to re-save articles to see HTML changes.
|
||||
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:
|
||||
|
||||
|
|
@ -45,15 +56,18 @@ Here is a bunch of liquid tags supported on DEV:
|
|||
|
||||
## How liquid tags are developed
|
||||
|
||||
Liquid tags are a matter of parsing the "arguments" and serving relevant JavaScript.
|
||||
Liquid tags are a matter of parsing the "arguments" and serving relevant
|
||||
JavaScript.
|
||||
|
||||
Liquid tags go in the `app/liquid_tags` folder. All liquid tags inherit from the base, like so...
|
||||
Liquid tags go in the `app/liquid_tags` folder. All liquid tags inherit from the
|
||||
base, like so...
|
||||
|
||||
```ruby
|
||||
class KotlinTag < LiquidTagBase
|
||||
```
|
||||
|
||||
Each liquid tag contains an `initialize` method which takes arguments and a `render` method which calls the appropriate view.
|
||||
Each liquid tag contains an `initialize` method which takes arguments and a
|
||||
`render` method which calls the appropriate view.
|
||||
|
||||
```ruby
|
||||
def initialize(tag_name, link, tokens)
|
||||
|
|
@ -75,12 +89,18 @@ Each liquid tag contains an `initialize` method which takes arguments and a `ren
|
|||
|
||||
View files can be found in `app/views/liquids`.
|
||||
|
||||
Each new liquid tag should be accompanied by instructions in `app/views/pages/_editor_guide_text.html.erb`.
|
||||
Each new liquid tag should be accompanied by instructions in
|
||||
`app/views/pages/_editor_guide_text.html.erb`.
|
||||
|
||||
Liquid Tags should also be accompanied by tests in `spec/liquid_tags` which confirm expected behavior.
|
||||
Liquid Tags should also be accompanied by tests in `spec/liquid_tags` which
|
||||
confirm expected behavior.
|
||||
|
||||
Some Liquid Tags are constructed using HTML and CSS within the app, and some are constructed by displaying an iframe of an external site.
|
||||
Some Liquid Tags are constructed using HTML and CSS within the app, and some are
|
||||
constructed by displaying an iframe of an external site.
|
||||
|
||||
CSS for Liquid Tags are found in `app/assets/stylesheets/ltags`. Liquid tag classes should generally be prepended by `ltag__`. e.g. `ltag__tag__content` etc.
|
||||
CSS for Liquid Tags are found in `app/assets/stylesheets/ltags`. Liquid tag
|
||||
classes should generally be prepended by `ltag__`. e.g. `ltag__tag__content`
|
||||
etc.
|
||||
|
||||
Here is an example of a good Liquid Tag pull request... https://github.com/thepracticaldev/dev.to/pull/3801
|
||||
Here is an example of a good Liquid Tag pull request...
|
||||
https://github.com/thepracticaldev/dev.to/pull/3801
|
||||
|
|
|
|||
|
|
@ -6,15 +6,20 @@ title: 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.
|
||||
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.
|
||||
|
||||
Webpacker manages the other one, and you can read more about [in its own guide](/frontend/webpacker).
|
||||
Webpacker manages the other one, 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 the user's web browser.
|
||||
This source code is not transpiled, only packaged and minified, and will be
|
||||
limited to whatever flavour of Javascript can run on the 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`.
|
||||
which is included globally in the primary template,
|
||||
`app/views/layouts/application.html.erb`.
|
||||
|
||||
`application.js` automatically includes all JS files via the statement:
|
||||
|
||||
|
|
@ -22,7 +27,9 @@ which is included globally in the primary template, `app/views/layouts/applicati
|
|||
//= 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:
|
||||
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();
|
||||
|
|
|
|||
|
|
@ -4,8 +4,11 @@ title: Preact
|
|||
|
||||
# Preact
|
||||
|
||||
[Preact](https://preactjs.com/) is an alternative to React with the same modern API.
|
||||
[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`.
|
||||
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`.
|
||||
The components are mounted when needed, look for `javascript_pack_tag` in the
|
||||
view pages inside `app/views`.
|
||||
|
|
|
|||
|
|
@ -4,8 +4,8 @@ title: Creating a Feature Branch
|
|||
|
||||
# Creating a feature/bug branch
|
||||
|
||||
When you are working on a bug, feature, or improvement, you will need to
|
||||
create a branch.
|
||||
When you are working on a bug, feature, or improvement, you will need to create
|
||||
a branch.
|
||||
|
||||
Generally, it can be helpful to prefix a branch name with `feature` or `bug` to
|
||||
denote what kind of code a reviewer can expect to find on the branch.
|
||||
|
|
@ -21,3 +21,9 @@ For a bug branch, you should do as follows:
|
|||
```
|
||||
git checkout -b bug/fixing-that-bug
|
||||
```
|
||||
|
||||
When working on the docs, you can do this:
|
||||
|
||||
```
|
||||
git checkout -b docs/adding-those-docs
|
||||
```
|
||||
|
|
|
|||
|
|
@ -6,12 +6,29 @@ title: Committing
|
|||
|
||||
## Style guide
|
||||
|
||||
This project follows [thoughtbot's Ruby Style Guide](https://github.com/thoughtbot/guides/blob/master/style/ruby/.rubocop.yml), using [Rubocop](https://github.com/bbatsov/rubocop) along with [Rubocop-Rspec](https://github.com/backus/rubocop-rspec) as the code analyzer. If you have Rubocop installed with your text editor of choice, you should be up and running.
|
||||
This project follows [thoughtbot's Ruby Style
|
||||
Guide](https://github.com/thoughtbot/guides/blob/master/style/ruby/.rubocop.yml),
|
||||
using [Rubocop](https://github.com/bbatsov/rubocop) along with
|
||||
[Rubocop-Rspec](https://github.com/backus/rubocop-rspec) as the code analyzer.
|
||||
If you have Rubocop installed with your text editor of choice, you should be up
|
||||
and running.
|
||||
|
||||
For Javascript, we follow [Airbnb's JS Style Guide](https://github.com/airbnb/javascript), using [ESLint](https://eslint.org) and [prettier](https://github.com/prettier/prettier). If you have ESLint installed with your text editor of choice, you should be up and running.
|
||||
For Javascript, we follow [Airbnb's JS Style
|
||||
Guide](https://github.com/airbnb/javascript), using [ESLint](https://eslint.org)
|
||||
and [prettier](https://github.com/prettier/prettier). If you have ESLint
|
||||
installed with your text editor of choice, you should be up and running.
|
||||
|
||||
## Husky hooks
|
||||
|
||||
When commits are made, a git precommit hook runs via [husky](https://github.com/typicode/husky) and [lint-staged](https://github.com/okonet/lint-staged). ESLint, prettier, and Rubocop will run on your code before it's committed. If there are linting errors that can't be automatically fixed, the commit will not happen. You will need to fix the issue manually then attempt to commit again.
|
||||
When commits are made, a git precommit hook runs via
|
||||
[husky](https://github.com/typicode/husky) and
|
||||
[lint-staged](https://github.com/okonet/lint-staged). ESLint, prettier, and
|
||||
Rubocop will run on your code before it's committed. If there are linting errors
|
||||
that can't be automatically fixed, the commit will not happen. You will need to
|
||||
fix the issue manually then attempt to commit again.
|
||||
|
||||
Note: if you've already installed the [husky](https://github.com/typicode/husky) package at least once (used for precommit npm script), you will need to run `yarn --force` or `npm install --no-cache`. For some reason, the post-install script of husky does not run when the package is pulled from yarn or npm's cache. This is not husky specific, but rather a cached package issue.
|
||||
Note: if you've already installed the [husky](https://github.com/typicode/husky)
|
||||
package at least once (used for precommit npm script), you will need to run
|
||||
`yarn --force` or `npm install --no-cache`. For some reason, the post-install
|
||||
script of husky does not run when the package is pulled from yarn or npm's
|
||||
cache. This is not husky specific, but rather a cached package issue.
|
||||
|
|
|
|||
|
|
@ -4,17 +4,23 @@ title: Configuring Environment Variables
|
|||
|
||||
# Configuring environment variables and secret keys
|
||||
|
||||
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][algolia] to get your development environment running.
|
||||
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][algolia] to get your development environment running.
|
||||
|
||||
The [backend guide][backend_guide] will show you how to get free API keys for additional services that may be required to run certain parts of the app.
|
||||
The [backend guide][backend_guide] will show you how to get free API keys for
|
||||
additional services that may be required to run certain parts of the app.
|
||||
|
||||
To set up keys for your local instance of DEV, you'll need to create an `application.yml` file. You can do this by copying the file called `sample_application.yml` in the `config` directory:
|
||||
To set up keys for your local instance of DEV, you'll need to create an
|
||||
`application.yml` file. You can do this by copying the file called
|
||||
`sample_application.yml` in the `config` directory:
|
||||
|
||||
```shell
|
||||
cp config/sample_application.yml config/application.yml
|
||||
```
|
||||
|
||||
Then, add each key you need to the `application.yml` file. For example, if you're setting up GitHub authentication:
|
||||
Then, add each key you need to the `application.yml` file. For example, if
|
||||
you're setting up GitHub authentication:
|
||||
|
||||
```shell
|
||||
GITHUB_KEY: "SOME_REAL_SECURE_KEY_HERE"
|
||||
|
|
@ -23,9 +29,11 @@ GITHUB_SECRET: "ANOTHER_REAL_SECURE_KEY_HERE"
|
|||
|
||||
(Don't worry, your `application.yml` file is ignored by git)
|
||||
|
||||
If you are missing `ENV` variables on bootup, the [envied][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][envied] gem will
|
||||
alert you with messages similar to `'error_on_missing_variables!': The following environment variables should be set: A_MISSING_KEY.`.
|
||||
|
||||
Only certain features require "real" keys, so you may be able to add them as you work on different areas of the application.
|
||||
Only certain features require "real" keys, so you may be able to add them as you
|
||||
work on different areas of the application.
|
||||
|
||||
[algolia]: /backend/algolia
|
||||
[backend_guide]: /backend
|
||||
|
|
|
|||
|
|
@ -4,8 +4,8 @@ title: Preparing the Database
|
|||
|
||||
# Preparing the database
|
||||
|
||||
The next step is to create and prepare the database. Because DEV is a
|
||||
Rails application, we have built-in tools to help us.
|
||||
The next step is to create and prepare the database. Because DEV is a Rails
|
||||
application, we have built-in tools to help us.
|
||||
|
||||
We can use Rails to create our database, load the schema, and add some seed
|
||||
data:
|
||||
|
|
@ -14,10 +14,11 @@ data:
|
|||
rails db:setup
|
||||
```
|
||||
|
||||
Note: If you've already run `bin/setup`, this will have already been done for you.
|
||||
Note: If you've already run `bin/setup`, this will have already been done for
|
||||
you.
|
||||
|
||||
`db:setup` actually runs the following rake commands in order so
|
||||
alternatively, you could run each of these to produce the same result:
|
||||
`db:setup` actually runs the following rake commands in order so alternatively,
|
||||
you could run each of these to produce the same result:
|
||||
|
||||
```shell
|
||||
rails db:create
|
||||
|
|
|
|||
|
|
@ -5,9 +5,9 @@ title: Forking the Repo
|
|||
# Forking the repository
|
||||
|
||||
The first step in contributing to any Open Source project on GitHub is
|
||||
[forking][forking] so that you can create
|
||||
[Pull Requests][pull_requests]. If you're not familiar with the idea of forking
|
||||
a repository, [GitHub has a super simple tutorial][forking_tutorial]!
|
||||
[forking][forking] so that you can create [Pull Requests][pull_requests]. If
|
||||
you're not familiar with the idea of forking a repository, [GitHub has a super
|
||||
simple tutorial][forking_tutorial]!
|
||||
|
||||
If you're ready to get started, [fork DEV's repository][fork_dev]!
|
||||
|
||||
|
|
|
|||
|
|
@ -4,13 +4,23 @@ title: 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. Check out the [testing guide](/tests).
|
||||
- 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 you are making changes to the API, make sure to update the version in the docs. Check out [the guide here](/contributing_api).
|
||||
- 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).
|
||||
- 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.
|
||||
Check out the [testing guide](/tests).
|
||||
- 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 you are making changes to the API, make sure to update the version in the
|
||||
docs. Check out [the guide here](/contributing_api).
|
||||
- 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!_
|
||||
_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!_
|
||||
|
||||
If the pull request affects the public API in any way, a post on DEV from the DEV Team account should accompany it. This is the duty of the core team to carry out.
|
||||
If the pull request affects the public API in any way, a post on DEV from the
|
||||
DEV Team account should accompany it. This is the duty of the core team to carry
|
||||
out.
|
||||
|
|
|
|||
|
|
@ -4,11 +4,11 @@ title: Starting the Application
|
|||
|
||||
# Starting the application
|
||||
|
||||
We're a Rails app, and we use [Webpacker][webpacker] to manage some of
|
||||
our JavaScript.
|
||||
We're a Rails app, and we use [Webpacker][webpacker] to manage some of our
|
||||
JavaScript.
|
||||
|
||||
Start the application, Webpack, and our job runner [delayed_job][delayed_job]
|
||||
by running:
|
||||
Start the application, Webpack, and our job runner [delayed_job][delayed_job] by
|
||||
running:
|
||||
|
||||
```shell
|
||||
bin/startup
|
||||
|
|
@ -21,8 +21,8 @@ Then point your browser to http://localhost:3000/ to view the site.
|
|||
If you're working on DEV regularly, you can use `alias start="bin/startup"` to
|
||||
make this even easier. 😊
|
||||
|
||||
If you're using **`pry`** for debugging in Rails, note that using `foreman`
|
||||
and `pry` together works, but it's not as clean as `bin/rails server`.
|
||||
If you're using **`pry`** for debugging in Rails, note that using `foreman` and
|
||||
`pry` together works, but it's not as clean as `bin/rails server`.
|
||||
|
||||
Here are some singleton commands you may need, usually in a separate
|
||||
instance/tab of your shell.
|
||||
|
|
|
|||
|
|
@ -4,7 +4,8 @@ title: Keeping Your Fork In Sync
|
|||
|
||||
# Keeping your fork in sync
|
||||
|
||||
Now that you have a fork of DEV's source code, there is work you will need to do to keep it updated.
|
||||
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
|
||||
|
||||
|
|
@ -38,7 +39,8 @@ Do a pull with rebase against `upstream`:
|
|||
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.
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -4,10 +4,14 @@ title: Suggested Workflow
|
|||
|
||||
# Suggested workflow
|
||||
|
||||
We use [Spring](https://github.com/rails/spring), and it is already included in the project.
|
||||
We use [Spring](https://github.com/rails/spring), and it is already included in
|
||||
the project.
|
||||
|
||||
1. Use the provided bin stubs to automatically start Spring, i.e. `bin/rails server`, `bin/rspec spec/models/`, `bin/rails db:migrate`.
|
||||
1. If Spring isn't picking up on new changes, use `spring stop`. For example, Spring should always be restarted if there's a change in the environment keys.
|
||||
1. If Spring isn't picking up on new changes, use `spring stop`. For example,
|
||||
Spring should always be restarted if there's a change in the environment
|
||||
keys.
|
||||
1. Check Spring's status whenever with `spring status`.
|
||||
|
||||
Caveat: `bin/rspec` is not equipped with Spring because it affects Simplecov's result. Instead, use `bin/spring rspec`.
|
||||
Caveat: `bin/rspec` is not equipped with Spring because it affects Simplecov's
|
||||
result. Instead, use `bin/spring rspec`.
|
||||
|
|
|
|||
|
|
@ -1,16 +1,27 @@
|
|||
---
|
||||
title: Docker
|
||||
---
|
||||
|
||||
# Installing DEV with Docker [Beta]
|
||||
|
||||
Our docker implementation is incomplete and may not work smoothly. Please, kindly [report any issues](https://github.com/thepracticaldev/dev.to/issues/new/choose)!
|
||||
Our docker implementation is incomplete and may not work smoothly. Please,
|
||||
kindly [report any
|
||||
issues](https://github.com/thepracticaldev/dev.to/issues/new/choose)!
|
||||
|
||||
## Installing prerequisites
|
||||
|
||||
_These prerequisites assume you're working on an operating system supported by Docker._
|
||||
_These prerequisites assume you're working on an operating system supported by
|
||||
Docker._
|
||||
|
||||
### Docker and Docker Compose
|
||||
|
||||
Docker is available for many different operating systems. We recommend you follow the [Docker CE install guide](https://docs.docker.com/install/), which illustrates multiple installation options for each OS.
|
||||
Docker is available for many different operating systems. We recommend you
|
||||
follow the [Docker CE install guide](https://docs.docker.com/install/), which
|
||||
illustrates multiple installation options for each OS.
|
||||
|
||||
You're also going to need Docker Compose, to start multiple containers. We recommend you follow the [Docker Compose install guide](https://docs.docker.com/compose/install/) as well.
|
||||
You're also going to need Docker Compose, to start multiple containers. We
|
||||
recommend you follow the [Docker Compose install
|
||||
guide](https://docs.docker.com/compose/install/) as well.
|
||||
|
||||
## Installing DEV
|
||||
|
||||
|
|
@ -18,23 +29,33 @@ You're also going to need Docker Compose, to start multiple containers. We recom
|
|||
1. Clone your forked repository, eg. `git clone https://github.com/<your-username>/dev.to.git`
|
||||
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](/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.
|
||||
- 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 (i.e. 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. i.e.:
|
||||
1. Create `config/application.yml` by copying from the provided template
|
||||
(i.e. 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. i.e.:
|
||||
|
||||
```shell
|
||||
GITHUB_KEY: "SOME_REAL_SECURE_KEY_HERE"
|
||||
GITHUB_SECRET: "ANOTHER_REAL_SECURE_KEY_HERE"
|
||||
```
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
## Running the Docker app (basic)
|
||||
|
||||
_Docker compose will by default use postgres:9.6 as the database version, should you want to update that set the `POSTGRES_VERSION` variable in your environment and start the container again_
|
||||
_Docker compose will by default use postgres:9.6 as the database version, should
|
||||
you want to update that set the `POSTGRES_VERSION` variable in your environment
|
||||
and start the container again_
|
||||
|
||||
1. run `docker-compose build`
|
||||
1. run `docker-compose run web rails db:setup`
|
||||
|
|
@ -44,7 +65,8 @@ _Docker compose will by default use postgres:9.6 as the database version, should
|
|||
|
||||
## Running the Docker app (advanced)
|
||||
|
||||
DEV provides a `docker-run.sh` script which can be used to run the Docker app with custom options.
|
||||
DEV provides a `docker-run.sh` script which can be used to run the Docker app
|
||||
with custom options.
|
||||
|
||||
Please execute the script itself to view all additional options:
|
||||
|
||||
|
|
|
|||
|
|
@ -4,8 +4,12 @@ title: GitPod
|
|||
|
||||
# GitPod
|
||||
|
||||
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).
|
||||
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).
|
||||
|
||||
[](https://gitpod.io/#https://github.com/thepracticaldev/dev.to)
|
||||
[](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).
|
||||
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,41 +1,66 @@
|
|||
---
|
||||
title: Linux
|
||||
---
|
||||
|
||||
# Installing DEV on Linux
|
||||
|
||||
## Installing prerequisites
|
||||
|
||||
_These prerequisites assume you're working on a Linux-based operating system, but they have only 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
|
||||
|
||||
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).
|
||||
1. With the Ruby version manager, install the Ruby version listed on our badge. (ie with rbenv: `rbenv install 2.6.5`)
|
||||
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).
|
||||
1. With the Ruby version manager, install the Ruby version listed on our badge.
|
||||
(ie with rbenv: `rbenv install 2.6.5`)
|
||||
|
||||
For very detailed rbenv installation directions on several distros, please visit [DigitalOcean's guide](https://www.digitalocean.com/community/tutorials/how-to-install-ruby-on-rails-with-rbenv-on-ubuntu-18-04).
|
||||
For very detailed rbenv installation directions on several distros, please visit
|
||||
[DigitalOcean's
|
||||
guide](https://www.digitalocean.com/community/tutorials/how-to-install-ruby-on-rails-with-rbenv-on-ubuntu-18-04).
|
||||
|
||||
### Yarn
|
||||
|
||||
There are two ways to install Yarn.
|
||||
|
||||
- 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.
|
||||
- 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. 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 ways to setup PostgreSQL. For additional configuration, check out our [PostgreSQL setup guide](/installation/postgresql) or the official [PostgreSQL](https://www.postgresql.org/) site for further information.
|
||||
There are more than one ways to setup PostgreSQL. For additional configuration,
|
||||
check out our [PostgreSQL setup guide](/installation/postgresql) or the official
|
||||
[PostgreSQL](https://www.postgresql.org/) site for further information.
|
||||
|
||||
### ImageMagick
|
||||
|
||||
DEV uses [ImageMagick](https://imagemagick.org/) to manipulate images on upload.
|
||||
|
||||
Please refer to ImageMagick's [instructions](https://imagemagick.org/script/download.php) on how to install it.
|
||||
Please refer to ImageMagick's
|
||||
[instructions](https://imagemagick.org/script/download.php) on how to install
|
||||
it.
|
||||
|
||||
### Redis
|
||||
|
||||
DEV requires Redis version 4.0 or higher.
|
||||
|
||||
We recommend following Digital Ocean's extensive [How To Install and Configure Redis on Ubuntu 16.04](https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-redis-on-ubuntu-16-04)
|
||||
We recommend following Digital Ocean's extensive [How To Install and Configure
|
||||
Redis on Ubuntu
|
||||
16.04](https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-redis-on-ubuntu-16-04)
|
||||
(available for other Linux distributions as well) to setup Redis.
|
||||
|
||||
## Installing DEV
|
||||
|
|
@ -45,27 +70,43 @@ We recommend following Digital Ocean's extensive [How To Install and Configure R
|
|||
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](/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.
|
||||
- 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 (i.e. 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. i.e.:
|
||||
1. Create `config/application.yml` by copying from the provided template
|
||||
(i.e. 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. i.e.:
|
||||
|
||||
```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.
|
||||
- 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
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
While installing, you might run into an error due to the `sass-rails` gem requiring `sassc`, which requires the `g++` compiler. If so, please run `sudo apt-get install g++` before retrying.
|
||||
While installing, you might run into an error due to the `sass-rails` gem
|
||||
requiring `sassc`, which requires the `g++` compiler. If so, please run `sudo apt-get install g++` before retrying.
|
||||
|
||||
While installing, if you didn't install `node` or `nvm` manually, you might run into an error due to an older system node version being present, which can cause issues while `yarn` is installing packages. If so, you'll need to [install `nvm`](https://github.com/nvm-sh/nvm#installation-and-update) and then run `nvm install node` to get the most recent node version before retrying.
|
||||
While installing, if you didn't install `node` or `nvm` manually, you might run
|
||||
into an error due to an older system node version being present, which can cause
|
||||
issues while `yarn` is installing packages. If so, you'll need to [install
|
||||
`nvm`](https://github.com/nvm-sh/nvm#installation-and-update) and then run `nvm install node` to get the most recent node version before retrying.
|
||||
|
|
|
|||
|
|
@ -8,8 +8,11 @@ title: macOS
|
|||
|
||||
### 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. (i.e. with rbenv: `rbenv install 2.6.5`)
|
||||
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.
|
||||
(i.e. with rbenv: `rbenv install 2.6.5`)
|
||||
|
||||
### Yarn
|
||||
|
||||
|
|
@ -17,9 +20,13 @@ Please refer to their [installation guide](https://yarnpkg.com/en/docs/install).
|
|||
|
||||
### PostgreSQL
|
||||
|
||||
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.
|
||||
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 options, check our [PostgreSQL setup guide](/installation/postgresql).
|
||||
For additional configuration options, check our [PostgreSQL setup
|
||||
guide](/installation/postgresql).
|
||||
|
||||
### ImageMagick
|
||||
|
||||
|
|
@ -56,20 +63,30 @@ redis-cli ping
|
|||
1. Install bundler with `gem install bundler`
|
||||
1. Set up your environment variables/secrets
|
||||
|
||||
- Take a look at `Envfile` to see all the `ENV` variables we use and the fake default provided for any missing keys.
|
||||
- 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, follow the steps below. At a minimum, you'll need to get your own free [Algolia credentials](/backend/algolia) to get your development environment running.
|
||||
- Take a look at `Envfile` to see all the `ENV` variables we use and the fake
|
||||
default provided for any missing keys.
|
||||
- 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, follow the steps below. At a
|
||||
minimum, you'll need to get your own free [Algolia
|
||||
credentials](/backend/algolia) to get your development environment running.
|
||||
|
||||
1. Create `config/application.yml` by copying from the provided template (i.e. 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. i.e.:
|
||||
1. Create `config/application.yml` by copying from the provided template
|
||||
(i.e. 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. i.e.:
|
||||
|
||||
```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.
|
||||
- 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`
|
||||
|
||||
|
|
@ -77,13 +94,15 @@ redis-cli ping
|
|||
|
||||
**Error:** `__NSPlaceholderDate initialize] may have been in progress in another thread when fork() was called`
|
||||
|
||||
**_Solution:_** Run the command `export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` (or `set -x OBJC_DISABLE_INITIALIZE_FORK_SAFETY YES` in fish shell)
|
||||
**_Solution:_** Run the command `export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES`
|
||||
(or `set -x OBJC_DISABLE_INITIALIZE_FORK_SAFETY YES` in fish shell)
|
||||
|
||||
---
|
||||
|
||||
**Error:** `User does not have CONNECT privilege.`
|
||||
|
||||
**_Solution:_** Complete the steps outlined in the [PostgreSQL setup guide](/installation/postgresql).
|
||||
**_Solution:_** Complete the steps outlined in the [PostgreSQL setup
|
||||
guide](/installation/postgresql).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -93,7 +112,8 @@ redis-cli ping
|
|||
|
||||
---
|
||||
|
||||
**Error:** `ruby-build: definition not found: <version number>` when `rbenv` was installed via `brew`.
|
||||
**Error:** `ruby-build: definition not found: <version number>` when `rbenv` was
|
||||
installed via `brew`.
|
||||
|
||||
```shell
|
||||
ruby-build: definition not found: <version number>
|
||||
|
|
@ -102,8 +122,8 @@ See all available versions with `rbenv install --list`.
|
|||
If the version you need is missing, try upgrading ruby-build:
|
||||
```
|
||||
|
||||
**_Solution:_**
|
||||
Run the following to update `ruby-build`, `brew update && brew upgrade ruby-build`. After that, rerun `rbenv install <version number>` and that version will get installed.
|
||||
**_Solution:_** Run the following to update `ruby-build`, `brew update && brew upgrade ruby-build`. After that, rerun `rbenv install <version number>` and that
|
||||
version will get installed.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -118,7 +138,9 @@ rails aborted!
|
|||
LoadError: dlopen(/Users/<username>/.rbenv/versions/2.6.5/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 of libreadline, so replace `<some version number>` with the version that errored.
|
||||
**_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 of
|
||||
libreadline, so replace `<some version number>` with the version that errored.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -129,7 +151,8 @@ PG::Error: ERROR: invalid value for parameter "TimeZone": "UTC"
|
|||
: SET time zone 'UTC'
|
||||
```
|
||||
|
||||
**_Solution:_** Restart your Postgres.app, or, if you installed PostgreSQL with Homebrew, restart with:
|
||||
**_Solution:_** Restart your Postgres.app, or, if you installed PostgreSQL with
|
||||
Homebrew, restart with:
|
||||
|
||||
```shell
|
||||
brew services restart postgresql
|
||||
|
|
@ -143,14 +166,17 @@ If that doesn't work, reboot your Mac.
|
|||
|
||||
```shell
|
||||
ERROR: Error installing pg:
|
||||
ERROR: Failed to build gem native extension.
|
||||
ERROR: Failed to build gem native extension.
|
||||
[...]
|
||||
Can't find the 'libpq-fe.h header
|
||||
*** extconf.rb failed ***
|
||||
```
|
||||
|
||||
**_Solution:_** You may encounter this when installing PostgreSQL with the Postgres.app. Try restarting the app and reinitializing the database. If that doesn't work, install PostgreSQL with Homebrew instead: `brew install postgresql`
|
||||
**_Solution:_** You may encounter this when installing PostgreSQL with the
|
||||
Postgres.app. Try restarting the app and reinitializing the database. If that
|
||||
doesn't work, install PostgreSQL with Homebrew instead: `brew install postgresql`
|
||||
|
||||
---
|
||||
|
||||
> If you encountered any errors that you subsequently resolved, **please consider updating this section** with your errors and their solutions.
|
||||
> If you encountered any errors that you subsequently resolved, **please
|
||||
> consider updating this section** with your errors and their solutions.
|
||||
|
|
|
|||
|
|
@ -4,23 +4,34 @@ title: PostgreSQL
|
|||
|
||||
# Setup your application with PostgreSQL
|
||||
|
||||
Follow the instructions in the installation guide below that corresponds to your operating system:
|
||||
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`
|
||||
- [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
|
||||
`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/)_.
|
||||
_You can find all installation options for a variety of operating systems [on
|
||||
the official PostgreSQL download page](https://www.postgresql.org/download/)_.
|
||||
|
||||
## Configuration
|
||||
|
||||
By default, the application is configured to connect to a local database named `PracticalDeveloper_development`. If you need to specify a username and a password, you can go about it by using the environment variable `DATABASE_URL` with a connection string.
|
||||
By default, the application is configured to connect to a local database named
|
||||
`PracticalDeveloper_development`. If you need to specify a username and a
|
||||
password, you can go about it by using the environment variable `DATABASE_URL`
|
||||
with a connection string.
|
||||
|
||||
The [official Rails guides](https://guides.rubyonrails.org/configuring.html#connection-preference) go into depth on how Rails merges the existing `database.yml` with the connection string.
|
||||
The [official Rails
|
||||
guides](https://guides.rubyonrails.org/configuring.html#connection-preference)
|
||||
go into depth on how Rails merges the existing `database.yml` with the
|
||||
connection string.
|
||||
|
||||
### Setup `DATABASE_URL` in application.yml
|
||||
|
||||
|
|
@ -32,15 +43,21 @@ The [official Rails guides](https://guides.rubyonrails.org/configuring.html#conn
|
|||
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).
|
||||
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).
|
||||
|
||||
NOTE: due to how Rails merges `database.yml` and `DATABASE_URL` it's recommended not to add the database name in the connection string. This will default to your development database name also during tests, which will effectively empty the development DB each time tests are run.
|
||||
NOTE: due to how Rails merges `database.yml` and `DATABASE_URL` it's recommended
|
||||
not to add the database name in the connection string. This will default to your
|
||||
development database name also during tests, which will effectively empty the
|
||||
development DB each time tests are run.
|
||||
|
||||
## Troubleshooting tests
|
||||
|
||||
- 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:
|
||||
- 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:
|
||||
|
||||
```shell
|
||||
STATEMENT_TIMEOUT=10000 bundle exec rspec
|
||||
|
|
|
|||
|
|
@ -10,20 +10,32 @@ items:
|
|||
|
||||
# Installation Guide
|
||||
|
||||
There are many different ways you can install the **development environment** so you can help contribute code to DEV.
|
||||
There are many different ways you can install the **development environment** so
|
||||
you can help contribute code to DEV.
|
||||
|
||||
## Installing locally
|
||||
|
||||
You can install DEV to your local machine and we have instructions for [Mac](/installation/mac), [Windows](/installation/windows) and [Linux](/installation/linux).
|
||||
You can install DEV to your local machine and we have instructions for
|
||||
[Mac](/installation/mac), [Windows](/installation/windows) and
|
||||
[Linux](/installation/linux).
|
||||
|
||||
## Running Docker
|
||||
|
||||
Installing to your local machine can be troublesome for many reasons such as a conflicting database and runtime versions.
|
||||
Installing to your local machine can be troublesome for many reasons such as a
|
||||
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 container, and you need not concern about the details. 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 _- beginner friendly!_
|
||||
|
||||
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.
|
||||
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.
|
||||
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,20 +1,32 @@
|
|||
---
|
||||
title: 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'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.
|
||||
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`. Look 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, [install Ubuntu 18.04 on Windows](https://www.microsoft.com/store/productId/9N9TNGVNDL3Q).
|
||||
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.
|
||||
On your first run, the system will ask for username and password. Take note of
|
||||
both since it will be used for `sudo` commands.
|
||||
|
||||
### Ruby on WSL
|
||||
|
||||
|
|
@ -45,7 +57,10 @@ 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:
|
||||
|
||||
|
|
@ -56,7 +71,8 @@ node -v
|
|||
npm -v
|
||||
```
|
||||
|
||||
If `npm -v` gives `Syntax error: word unexpected (expecting "in")`, restart the terminal and try again.
|
||||
If `npm -v` gives `Syntax error: word unexpected (expecting "in")`, restart the
|
||||
terminal and try again.
|
||||
|
||||
And now, for rails itself:
|
||||
|
||||
|
|
@ -64,7 +80,8 @@ And now, for rails itself:
|
|||
gem install rails -v 5.2.3
|
||||
```
|
||||
|
||||
Then run `rbenv rehash` to make the 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
|
||||
|
|
@ -74,7 +91,8 @@ rails -v
|
|||
|
||||
### Yarn
|
||||
|
||||
The fastest way to install Yarn for WSL would be from Debian package repository. Configure the repository with the following commands:
|
||||
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 -
|
||||
|
|
@ -91,25 +109,34 @@ 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 right now. WSL is able to connect to a PostgreSQL instance on your Windows machine. DEV requires PostgreSQL version 9.4 or higher.
|
||||
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.postgresql.org/download/windows/) and install it.
|
||||
Download [PostgreSQL for Windows](https://www.postgresql.org/download/windows/)
|
||||
and install it.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
For additional configuration options, check our [PostgreSQL setup guide](/installation/postgresql).
|
||||
For additional configuration options, check our [PostgreSQL setup
|
||||
guide](/installation/postgresql).
|
||||
|
||||
### ImageMagick
|
||||
|
||||
DEV uses [ImageMagick](https://imagemagick.org/) to manipulate images on upload.
|
||||
|
||||
Please refer to ImageMagick's [instructions](https://imagemagick.org/script/download.php) on how to install it.
|
||||
Please refer to ImageMagick's
|
||||
[instructions](https://imagemagick.org/script/download.php) on how to install
|
||||
it.
|
||||
|
||||
### Redis
|
||||
|
||||
DEV requires Redis version 4.0 or higher.
|
||||
|
||||
We recommend to follow [this guide](https://redislabs.com/blog/redis-on-windows-10/) to run Redis under WSL.
|
||||
We recommend to follow [this
|
||||
guide](https://redislabs.com/blog/redis-on-windows-10/) to run Redis under WSL.
|
||||
|
||||
## Installing DEV
|
||||
|
||||
|
|
@ -118,34 +145,48 @@ We recommend to follow [this guide](https://redislabs.com/blog/redis-on-windows-
|
|||
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](/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.
|
||||
- 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:
|
||||
|
||||
```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.
|
||||
- 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
|
||||
|
||||
1. There is a possibility that you might encounter a _statement timeout_ when seeding the database for the first time. Please increase the value of `statement_timeout` to `9999999` in `config/database.yml`.
|
||||
1. There is a possibility that you might encounter a _statement timeout_ when
|
||||
seeding the database for the first time. Please increase the value of
|
||||
`statement_timeout` to `9999999` in `config/database.yml`.
|
||||
|
||||
2. If the installation process failed with the following error `ERROR: Error installing pg`. Please consider installing the following package `libpq-dev` :
|
||||
2. If the installation process failed with the following error `ERROR: Error installing pg`. Please consider installing the following package `libpq-dev`
|
||||
:
|
||||
|
||||
```bash
|
||||
sudo apt-get install libpq-dev
|
||||
```
|
||||
|
||||
3. If the command `bin/setup` fails at installing `cld-0.8.0` with the warnings `'aclocal-1.10' is missing on your system` and `'automake-1.10' is missing on your system`. Please install `automake-1.10` using the commands below.
|
||||
3. If the command `bin/setup` fails at installing `cld-0.8.0` with the warnings
|
||||
`'aclocal-1.10' is missing on your system` and `'automake-1.10' is missing on your system`. Please install `automake-1.10` using the commands below.
|
||||
|
||||
```shell
|
||||
cd
|
||||
|
|
@ -158,4 +199,5 @@ cd automake-1.10/
|
|||
make
|
||||
```
|
||||
|
||||
> If you encountered any errors that you subsequently resolved, **please consider updating this section** with your errors and their solutions.
|
||||
> If you encountered any errors that you subsequently resolved, **please
|
||||
> consider updating this section** with your errors and their solutions.
|
||||
|
|
|
|||
|
|
@ -4,26 +4,44 @@ title: Licensing
|
|||
|
||||
# Licensing
|
||||
|
||||
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. Please see the [LICENSE](https://github.com/thepracticaldev/dev.to/blob/master/LICENSE.md) file in our repository for the full text.
|
||||
This program is free software: you can redistribute it and/or modify it under
|
||||
the terms of the GNU Affero General Public License as published by the Free
|
||||
Software Foundation, either version 3 of the License, or (at your option) any
|
||||
later version. Please see the
|
||||
[LICENSE](https://github.com/thepracticaldev/dev.to/blob/master/LICENSE.md) file
|
||||
in our repository for the full text.
|
||||
|
||||
Like many open source projects, we require that contributors provide us with a Contributor License Agreement (CLA). By submitting code to the DEV project, you are granting us a right to use that code under the terms of the CLA.
|
||||
Like many open source projects, we require that contributors provide us with a
|
||||
Contributor License Agreement (CLA). By submitting code to the DEV project, you
|
||||
are granting us a right to use that code under the terms of the CLA.
|
||||
|
||||
Our version of the CLA was adapted from the Microsoft Contributor License Agreement, which they generously made available to the public domain under Creative Commons CC0 1.0 Universal.
|
||||
Our version of the CLA was adapted from the Microsoft Contributor License
|
||||
Agreement, which they generously made available to the public domain under
|
||||
Creative Commons CC0 1.0 Universal.
|
||||
|
||||
## Where can I learn more about the AGPL-3 license?
|
||||
|
||||
Please refer to the official “[Why the Affero GPL](https://www.gnu.org/licenses/why-affero-gpl.html)” and the [FAQ page](https://www.gnu.org/licenses/gpl-faq.html) on [GNU.org](https://www.gnu.org) for full details regarding this license.
|
||||
Please refer to the official “[Why the Affero
|
||||
GPL](https://www.gnu.org/licenses/why-affero-gpl.html)” and the [FAQ
|
||||
page](https://www.gnu.org/licenses/gpl-faq.html) on
|
||||
[GNU.org](https://www.gnu.org) for full details regarding this license.
|
||||
|
||||
## Why does DEV have a CLA?
|
||||
|
||||
The Contributor License Agreement (CLA) is a legal document in which you state that you are entitled to contribute your code to the DEV codebase, and are willing to have it used in distributions and derivative work.
|
||||
The Contributor License Agreement (CLA) is a legal document in which you state
|
||||
that you are entitled to contribute your code to the DEV codebase, and are
|
||||
willing to have it used in distributions and derivative work.
|
||||
|
||||
The CLA helps provide confidence to future users that they will be allowed to use the DEV codebase without fear that a contributor will try to withdraw permissions at a later date.
|
||||
The CLA helps provide confidence to future users that they will be allowed to
|
||||
use the DEV codebase without fear that a contributor will try to withdraw
|
||||
permissions at a later date.
|
||||
|
||||
## Am I giving away the copyright of my contributions?
|
||||
|
||||
No. You are granting DEV a license to use and distribute your contribution without further restriction, not assigning the copyright.
|
||||
No. You are granting DEV a license to use and distribute your contribution
|
||||
without further restriction, not assigning the copyright.
|
||||
|
||||
## What if I have other questions?
|
||||
|
||||
Please check out our main repository or send an email to [yo@dev.to](mailto:yo@dev.to).
|
||||
Please check out our main repository or send an email to
|
||||
[yo@dev.to](mailto:yo@dev.to).
|
||||
|
|
|
|||
|
|
@ -17,13 +17,24 @@ items:
|
|||
|
||||
# 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.
|
||||
On this site you'll find instructions to setup a [local instance of DEV][installation],
|
||||
documentation on the [architecture of DEV][architecture],
|
||||
[how to contribute][contributing], and many other useful documents.
|
||||
|
||||
This documentation site is the product of a number of volunteer contributors
|
||||
working alongside the DEV Core Team, special thanks to all those who have
|
||||
contributed to the documentation.
|
||||
|
||||
# Running the documentation locally
|
||||
|
||||
DEV's documentation is built with [GitDocs NodeJS library](https://www.npmjs.com/package/gitdocs).
|
||||
Like DEV, this site is open source and the code is [hosted on GitHub][docs]. If
|
||||
you find any incorrect information, or a even a typo, we'd love to see a pull
|
||||
request. Follow these steps to get the documentation site running locally.
|
||||
|
||||
The first step to running the documentations locally is to install the `GitDocs` package globally.
|
||||
DEV's documentation is built with [GitDocs NodeJS library][gitdocs].
|
||||
|
||||
The first step to running the documentations locally is to install the `GitDocs`
|
||||
package globally.
|
||||
|
||||
With npm:
|
||||
|
||||
|
|
@ -37,17 +48,26 @@ Alternatively, you can use Yarn:
|
|||
yarn global add gitdocs
|
||||
```
|
||||
|
||||
Once installed, you can run `gitdocs serve` from the root of the dev.to project or from the `/docs` directory.
|
||||
Once installed, you should run `gitdocs serve` from the root of the dev.to
|
||||
project or from the `/docs` directory.
|
||||
|
||||
```shell
|
||||
gitdocs serve
|
||||
```
|
||||
|
||||
This will start a server where you can browse the documentation: <http://localhost:8000/>
|
||||
This will start a server where you can browse the documentation:
|
||||
<http://localhost:8000/>
|
||||
|
||||
When you add new markdown pages or rename existing ones, you'll have to restart
|
||||
the server before you notice any changes.
|
||||
If you add new pages or rename existing pages, you'll need to restart the server
|
||||
for those changes to take effect.
|
||||
|
||||
# Contributing to the docs
|
||||
|
||||
If you're looking for more information on contributing, check out the [Contributing article](https://docs.dev.to/contributing/).
|
||||
If you're looking for more information on contributing, check out the
|
||||
[Contributing article][contributing].
|
||||
|
||||
[installation]: /installation/
|
||||
[architecture]: /technical-overview/architecture/
|
||||
[contributing]: /contributing/
|
||||
[docs]: https://github.com/thepracticaldev/dev.to/tree/master/docs/
|
||||
[gitdocs]: https://www.npmjs.com/package/gitdocs/
|
||||
|
|
|
|||
|
|
@ -1,25 +1,42 @@
|
|||
---
|
||||
title: Self hosting DEV
|
||||
title: Self Hosting DEV
|
||||
---
|
||||
|
||||
## Hosting Your Own DEV Instance
|
||||
## 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.
|
||||
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 a checklist of considerations that are relevant to the goal of eventually hosting your own version of our community platform.
|
||||
This page is designed to serve as an FAQ and a checklist of considerations that
|
||||
are relevant to the goal of eventually hosting your own version of our community
|
||||
platform.
|
||||
|
||||
### Current Limitations
|
||||
### Current limitations
|
||||
|
||||
- We do not currently have a versioning system that will allow us to share fixes and improvements with modified versions of the code.
|
||||
- We do not currently have a versioning system that will allow us to share fixes
|
||||
and improvements with modified versions of the code.
|
||||
|
||||
### License Restrictions
|
||||
### License restrictions
|
||||
|
||||
- Certain aspects of the app are currently hardcoded. For instance: logos, certain elements of content, etc. If you were to host the current version of the app, you would be inadvertently impersonating the core dev.to project.
|
||||
- DEV has commercial licenses for certain design components as described in our [Design License Info](https://docs.dev.to/design/branding/#design-license-info) section. These licenses are specific to the dev.to project, and may not extend to self-hosted versions.
|
||||
- Certain aspects of the app are currently hardcoded. For instance: logos,
|
||||
certain elements of content, etc. If you were to host the current version of
|
||||
the app, you would be inadvertently impersonating the core dev.to project.
|
||||
- DEV has commercial licenses for certain design components as described in our
|
||||
[Design License
|
||||
Info](https://docs.dev.to/design/branding/#design-license-info) section. These
|
||||
licenses are specific to the dev.to project, and may not extend to self-hosted
|
||||
versions.
|
||||
|
||||
### I want to stand up my own entity using the DEV codebase, how can I help?
|
||||
|
||||
- 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.
|
||||
- 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 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).
|
||||
|
|
|
|||
|
|
@ -1,94 +1,153 @@
|
|||
---
|
||||
title: Architecture and Concepts
|
||||
---
|
||||
|
||||
# A few high-level things to know
|
||||
|
||||
## We are a Ruby on Rails app
|
||||
|
||||
Ruby on Rails is a web framework heavy on conventions over configuration. All else equal we should try to follow Rails convention. We are currently on version 5.2.3, due for an upgrade to 6.x.x.
|
||||
Ruby on Rails is a web framework heavy on conventions over configuration. All
|
||||
else equal, we should try to follow Rails convention. We are currently on
|
||||
version 5.2.3, due for an upgrade to 6.x.x.
|
||||
|
||||
## We cache many content pages on the edge
|
||||
|
||||
- We use edge caching to serve many pages, meaning we do not go all the way to the server, meaning that on those pages we don't get access within the document to helper methods like `current_user`. A page is edge-cached through our CDN Fastly if the controller contains this line for the relevant action...
|
||||
To decrease loading time, we use edge-caching extensively. Taking advantage of
|
||||
edge-caching means that we do not go all the way to the server to render every
|
||||
page. Therefore, on pages that are cached we don't have access to helper methods
|
||||
like `current_user`. A page is edge-cached through our CDN ([Fastly][fastly]) if
|
||||
the controller contains this line for the relevant action:
|
||||
|
||||
```
|
||||
before_action :set_cache_control_headers
|
||||
```
|
||||
|
||||
We also use server-side caching [Rails caching](https://guides.rubyonrails.org/caching_with_rails.html). Any time you see `Rails.cache` or `<%= cache ... %>`, this is code affected in production by caching.
|
||||
We also use server-side caching: [Rails caching][rails_caching]. If you see
|
||||
`Rails.cache` or `<%= cache ... %>`, this is code affected in production by
|
||||
caching.
|
||||
|
||||
## We use inline CSS and deferred scripts for usage performance improvements
|
||||
|
||||
To avoid blocking initial render, we put critical path CSS inline in the HTML and we user `defer` so the user is not waiting on extra assets. This means we have some constraints about how we can use JavaScript to affect the layout. In many cases, we should not attempt to do this.
|
||||
To avoid blocking the initial render, we frequently write critical CSS inline,
|
||||
and we use the `defer` attribute to accelerate page loads. This practice results
|
||||
in a faster page load, and doesn't leave users waiting on heavy assets. However,
|
||||
this practice limits our ability to manipulate layout with JavaScript. As a
|
||||
rule, you should avoid relying on JavaScript for layout when working on DEV.
|
||||
|
||||
## We attempt to reduce our bundle size
|
||||
|
||||
We use [PreactJs](https://preactjs.com/), a lightweight alternative to ReactJs, and generally, we try to reduce our bundle size with approaches such as [dynamic imports](https://dev.to/goenning/how-we-reduced-our-initial-jscss-size-by-67-3ac0).
|
||||
We use [PreactJS][preact], a lightweight alternative to ReactJS, and we try to
|
||||
reduce our bundle size with [dynamic imports][dynamic_imports].
|
||||
|
||||
## Worst technical debt
|
||||
|
||||
The biggest element of technical debt in our app are mostly on the frontend. We use both "old" (in the assets folder) and "new" (in the `app/javascript` folder) JavaScript, and could use some help migrating to the new parts.
|
||||
The most widespread elements of technical debt in this application reside on the
|
||||
frontend. We use both the "old" approach (files in the `/assets` folder) and
|
||||
"new" approach (files in the `app/javascript` folder) for loading JavaScript
|
||||
into our Rails app.
|
||||
|
||||
We also have a sprawling CSS structure with few consistent rules.
|
||||
We also have overgrown and inconsistent CSS. This is an area we'd love to see
|
||||
contributions from the community.
|
||||
|
||||
We also have inconsistencies and issues with how we bust caching on the edge. We could ideally be doing resource-based purging as described in [the Fastly Rails](https://github.com/fastly/fastly-rails) docs, but we instead rely on explicit busting of specific URLs, (via `CacheBuster`).
|
||||
We also have inconsistencies and issues with how we bust caching on the edge.
|
||||
Ideally, we could practice resource-based purging as described in the [Fastly
|
||||
Rails][fastly_rails] docs, but we bust specific URLs via `CacheBuster`.
|
||||
|
||||
## The algorithm behind the feed
|
||||
|
||||
The home feed is based on a combination of collective recent posts that are cached and delivered the same to everyone in the HTML, and additional articles fetched from an Algolia index after page load. To determine which posts a user sees, they are ranked based on the user's followed tags, followed users, and relative weights for each tag. Additional fetched articles also follow this general pattern.
|
||||
The home feed is based on a combination of recent collective posts that are
|
||||
cached and delivered the same to everyone in the HTML, and additional articles
|
||||
fetched from an Algolia index after page load. To determine which posts a user
|
||||
sees, they are ranked based on the user's followed tags, followed users, and
|
||||
relative weights for each tag. Additional fetched articles also follow this
|
||||
general pattern.
|
||||
|
||||
Currently, the top post on the home feed, which must have a cover image, is shared among all users.
|
||||
Currently, the top post on the home feed, which must have a cover image, is
|
||||
shared among all users.
|
||||
|
||||
## Inter-page navigation
|
||||
|
||||
DEV uses a variation of "instant click" which swaps out content instead of full page requests. It is similar to the Rails gem Turbolinks, but more lightweight. The library is modified to work specifically with the Rails app, and does not swap the nav bar or footer when a page is changed. The code for this functionality can be found in `app/assets/javascripts/base.js.erb`.
|
||||
DEV uses a variation of "instant click," which swaps out page content instead
|
||||
of making full-page requests. This approach is similar to the one used by the
|
||||
Rails gem `Turbolinks`, but our approach is more lightweight. The library is
|
||||
modified to work specifically with this Rails app and does not swap out reused
|
||||
elements like the navigation bar or the footer. The code for this functionality
|
||||
is viewable in `app/assets/javascripb/base.js.erb`.
|
||||
|
||||
There are gotchas in terms of JavaScript not loading from a fully blank slate. This means that a lot of functionality needs to be loaded on page change, as well as `window.InstantClick.on('change', someFunction)`. This means lines like this exist in the app...
|
||||
There are a few caveats regarding this approach. Using our approach means a
|
||||
non-trivial amount of functionality is reloaded on page change. A similar
|
||||
amount of reloading occurs when using `window.InstantClick.on('change', someFunction)`.
|
||||
This results in code that looks something like this:
|
||||
|
||||
```javascript
|
||||
initPreview();
|
||||
window.InstantClick.on('change', initPreview);
|
||||
```
|
||||
|
||||
This can change how variables need to be defined in certain contexts and orders, differently than if they were loaded freshly, or within the context of a truly integrated single page app.
|
||||
In some circumstances, this practice means the developer should pay special
|
||||
attention to the declaration of variables and functions. JavaScript may behave
|
||||
differently than expected.
|
||||
|
||||
Of course, it would be possible to abstract away some of these gotchas in the future.
|
||||
Abstracting and removing these caveats is a long term goal, and contribution on
|
||||
that front is welcome!
|
||||
|
||||
# General app concepts
|
||||
|
||||
## Articles (or posts)
|
||||
|
||||
This is the main high level content a user creates. An Article has many comments, taggings through acts-as-taggable gem, belongs to a user (and possibly an organization), and is generally the central core unit.
|
||||
Articles are the primary form of user generated content in the application. An
|
||||
Article has many comments and taggings through the acts-as-taggable gem,
|
||||
belongs to a single user (and possibly an organization), and is the core unit
|
||||
of content.
|
||||
|
||||
## Comments
|
||||
|
||||
Comments belong to articles (or podcasts, generally polymorphic). They belong first and foremost to the user in our architecture, which is reflected by the URL (`/username/tag-slug`) but they also fit in communal areas below other content. They are threaded but flatten out so that there is not infinite threading (e.g. once a discussion branch gets going, no more branching after a few).
|
||||
Comments belong to articles or other content (they are generally polymorphic).
|
||||
They belong first and foremost to the user in our design, which is reflected by
|
||||
the URL (`/username/tag-slug`), but they are present in communal areas of the
|
||||
application. They are threaded, but they flatten out gradually to avoid
|
||||
infinitely branching threads.
|
||||
|
||||
## Tags
|
||||
|
||||
Tags help organize content, with rules for each tag. A tag is a de facto community with one or more moderators with privileges to determine what is appropriate for the tag. Some tags act as "flare" for posts so they show up more pronounced in the article when viewed from the index. Tags that belong as "flare" are currently defined in the `FlareTag` object. In cases of multiple flare tags, the flare displayed is determined by its hierarchy.
|
||||
Tags are used to organize user generated content. Each tag has a set of rules
|
||||
which are used for moderation. Each tag is a de facto community complete with
|
||||
community moderators.
|
||||
|
||||
Some tags behave as "flare," highlighting certain articles when viewed from the
|
||||
index page. Tags that act as "flare" are defined in the `FlareTag` object. In
|
||||
cases of multiple flare tags, the tag displayed is determined by its hierarchy.
|
||||
|
||||
## ClassifiedListings (or listings)
|
||||
|
||||
Classified listings are similar to posts in some ways, but with more limitations. They are designed to be categorized into market areas. They also make use of tags.
|
||||
Classified listings are similar to posts in some ways, but with more
|
||||
limitations. They are designed to be categorized into market areas. They also
|
||||
make use of tags.
|
||||
|
||||
## Credits
|
||||
|
||||
Credits are the currency of the platform which users can use to buy classifieds, or potentially future behavior.
|
||||
Credits are the currency of the platform which users can use to buy listings.
|
||||
The functionality of credits may be expanded in the future.
|
||||
|
||||
## Organizations
|
||||
|
||||
Users can belong to organizations, which have their own profile pages where posts can be published etc. This can be any group endeavor such as a company, an open source project, or any standalone publication on DEV
|
||||
Users can belong to organizations, which have their own profile pages where
|
||||
posts can be published etc. This can be any group endeavor such as a company, an
|
||||
open source project, or any standalone publication on DEV.
|
||||
|
||||
## Reactions
|
||||
|
||||
Hearts, unicorns, bookmarks. How a user shows appreciation for a post. Bookmarks have the special functionality of being stored in one's reading list.
|
||||
Hearts, unicorns, and bookmarks. Reactions are the medium for displaying
|
||||
appreciation for content. Bookmarks have the unique functionality of saving an
|
||||
article in the user's reading list.
|
||||
|
||||
## Follows
|
||||
|
||||
How a user keeps track of the tags, users or articles they care about. Follows impact a user's home feed and notifications.
|
||||
How a user keeps track of the tags, users, or articles they care about. Follows
|
||||
impact a user's home feed and notifications.
|
||||
|
||||
---
|
||||
|
||||
This is far from a complete view of the app, but it covers a few core concepts.
|
||||
|
||||
[fastly]: https://www.fastly.com/
|
||||
[rails_caching]: https://guides.rubyonrails.org/caching_with_rails.html
|
||||
[preact]: https://preactjs.com/
|
||||
[dynamic_imports]: https://dev.to/goenning/how-we-reduced-our-initial-jscss-size-by-67-3ac0
|
||||
[fastly_rails]: https://github.com/fastly/fastly-rails
|
||||
|
|
|
|||
|
|
@ -10,4 +10,5 @@ We are a [Ruby on Rails](https://rubyonrails.org) web application.
|
|||
|
||||
Our [stack](stack.md) is composed of many tools and services.
|
||||
|
||||
You can read more about our architecture and app's concepts here: [A few high-level things to know](architecture).
|
||||
You can read more about our architecture and app's concepts here: [A few
|
||||
high-level things to know](/architecture).
|
||||
|
|
|
|||
|
|
@ -8,30 +8,46 @@ For the Dev.to tech stack we use:
|
|||
|
||||
- [_Puma_](https://github.com/puma/puma) as the web server
|
||||
- [_PostgreSQL_](https://www.postgresql.org/) as the primary database
|
||||
- [_Redis_](https://redis.io/) to store additional data and eventually replace memcache
|
||||
- [_Fastly_](https://www.fastly.com/) for [edge caching](https://dev.to/ben/making-devto-insanely-fast)
|
||||
- [_Redis_](https://redis.io/) to store additional data and eventually replace
|
||||
memcache
|
||||
- [_Fastly_](https://www.fastly.com/) for [edge
|
||||
caching](https://dev.to/ben/making-devto-insanely-fast)
|
||||
- [_Cloudinary_](https://cloudinary.com/) for image manipulation/serving
|
||||
- [_Airbrake_](https://airbrake.io/) for error monitoring
|
||||
- [_Timber_](https://timber.io/) for logging
|
||||
- [_Delayed Job_](https://github.com/collectiveidea/delayed_job) and [_Active Job_](https://guides.rubyonrails.org/active_job_basics.html) for background workers
|
||||
- [_Delayed Job_](https://github.com/collectiveidea/delayed_job) and [_Active
|
||||
Job_](https://guides.rubyonrails.org/active_job_basics.html) for background
|
||||
workers
|
||||
- [_Algolia_](https://www.algolia.com/) for search
|
||||
- [_Redcarpet_](https://github.com/vmg/redcarpet) and [_Rouge_](https://github.com/jneen/rouge) to parse Markdown
|
||||
- [_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
|
||||
- [_InstantClick_](http://instantclick.io/) (a modified version) instead of _Turbolinks_ to accelerate navigation
|
||||
- [_Redcarpet_](https://github.com/vmg/redcarpet) and
|
||||
[_Rouge_](https://github.com/jneen/rouge) to parse Markdown
|
||||
- [_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
|
||||
- [_InstantClick_](http://instantclick.io/) (a modified version) instead of
|
||||
_Turbolinks_ to accelerate navigation
|
||||
- [_ImageMagick_](https://imagemagick.org/) to manipulate images on upload
|
||||
- [_Heroku_](https://www.heroku.com) for hosting
|
||||
- [_Heroku scheduler_](https://devcenter.heroku.com/articles/scheduler) for scheduled jobs
|
||||
- [_Heroku scheduler_](https://devcenter.heroku.com/articles/scheduler) for
|
||||
scheduled jobs
|
||||
- [_Sendgrid_](https://sendgrid.com/) for transactional mailing
|
||||
- [_Mailchimp_](https://mailchimp.com/) for marketing/outreach emails
|
||||
- [_Figaro_](https://github.com/laserlemon/figaro) for app configuration
|
||||
- [_CounterCulture_](https://github.com/magnusvk/counter_culture) to keep track of association counts (counter caches)
|
||||
- [_CounterCulture_](https://github.com/magnusvk/counter_culture) to keep track
|
||||
of association counts (counter caches)
|
||||
- [_Rolify_](https://github.com/RolifyCommunity/rolify) for role management
|
||||
- [_Pundit_](https://github.com/varvet/pundit) for authorization
|
||||
- [_Service Workers_](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers) to proxy traffic
|
||||
- [Preact](https://preactjs.com/) for some of the frontend. See [the Frontend Guide](/frontend) for more info
|
||||
- [_Pusher_](https://pusher.com) for realtime communication between the application and users' browsers
|
||||
- [_GitDocs_](https://gitdocs.netlify.com) for beautiful and SEO-friendly documentation
|
||||
- [_Service
|
||||
Workers_](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers)
|
||||
to proxy traffic
|
||||
- [Preact](https://preactjs.com/) for some of the frontend. See [the Frontend
|
||||
Guide](/frontend) for more info
|
||||
- [_Pusher_](https://pusher.com) for realtime communication between the
|
||||
application and users' browsers
|
||||
- [_GitDocs_](https://gitdocs.netlify.com) for beautiful and SEO-friendly
|
||||
documentation
|
||||
- [Git](https://git-scm.com/) for version control
|
||||
- [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._
|
||||
_This list is non-exhaustive. If you see something that belongs here, feel free
|
||||
to add it._
|
||||
|
|
|
|||
|
|
@ -6,10 +6,11 @@ title: Acceptance Tests
|
|||
|
||||
Acceptance tests are tests from the perspective of the end-user.
|
||||
|
||||
It means that we are simulating what a user could do from their web browser
|
||||
and testing the expected behavior of the app.
|
||||
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").
|
||||
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:
|
||||
|
||||
|
|
@ -17,13 +18,13 @@ You can run all acceptance tests with:
|
|||
bundle exec rspec spec/system
|
||||
```
|
||||
|
||||
To run an individual file you can use for example:
|
||||
To run an individual file you can use:
|
||||
|
||||
```shell
|
||||
bundle exec rspec spec/system/user_views_a_reading_list_spec.rb
|
||||
```
|
||||
|
||||
To run a specific test case you can use for example:
|
||||
To run a specific test case you can use:
|
||||
|
||||
```shell
|
||||
bundle exec rspec spec/system/user_views_a_reading_list_spec.rb:10
|
||||
|
|
@ -31,4 +32,6 @@ bundle exec rspec spec/system/user_views_a_reading_list_spec.rb:10
|
|||
|
||||
where `10` is the line number of the test case that you want to execute.
|
||||
|
||||
You can read the official guide [Testing Rails Applications](https://guides.rubyonrails.org/testing.html#system-testing) to learn more.
|
||||
You can read the official guide [Testing Rails
|
||||
Applications](https://guides.rubyonrails.org/testing.html#system-testing) to
|
||||
learn more.
|
||||
|
|
|
|||
|
|
@ -31,5 +31,5 @@ testing as well.
|
|||
When you're writing Preact components, you can include some basic a11y testing
|
||||
in your unit tests with [jest-axe](https://github.com/nickcolley/jest-axe).
|
||||
|
||||
If you're still curious
|
||||
[there are some great talks on accessibility for developers](https://www.youtube.com/watch?v=8E9AEZjglqI).
|
||||
If you're still curious [there are some great talks on accessibility for
|
||||
developers](https://www.youtube.com/watch?v=8E9AEZjglqI).
|
||||
|
|
|
|||
|
|
@ -6,9 +6,10 @@ title: Code Coverage
|
|||
|
||||
## Rails
|
||||
|
||||
Rails tests will generate code coverage at the end of the tests.
|
||||
Rspec will generate code coverage at the end of the tests.
|
||||
|
||||
To get the code coverage of the whole Rails codebase, you need to run all the tests with:
|
||||
To get the code coverage of the entire Rails codebase, you must run the full
|
||||
Ruby test suite. You can run the full test suite with the `rspec` command:
|
||||
|
||||
```shell
|
||||
bundle exec rspec
|
||||
|
|
@ -32,15 +33,19 @@ or
|
|||
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 code coverage.
|
||||
Once your tests have completed, the `coverage/index.html` will be regenerated
|
||||
with some stats concerning the overall health of our test suite including a code
|
||||
coverage metric.
|
||||
|
||||
To turn off coverage report generation please set environment variable `COVERAGE` value to `false`.
|
||||
To turn off coverage report generation please set environment variable
|
||||
`COVERAGE` value to `false`.
|
||||
|
||||
## Preact
|
||||
|
||||
Preact tests will generate code coverage at the end of the tests.
|
||||
|
||||
To get the code coverage of the Preact codebase, you need to run all the tests with:
|
||||
To get the code coverage of the Preact codebase, you must run the full JS test
|
||||
suite. You can run the full test suite with the npm task `test`:
|
||||
|
||||
```shell
|
||||
npm run test
|
||||
|
|
@ -52,4 +57,5 @@ or
|
|||
yarn test
|
||||
```
|
||||
|
||||
After the test run is complete, you will see the coverage on the console.
|
||||
Once the tests have completed, the test coverage metric will be visible in the
|
||||
terminal window.
|
||||
|
|
|
|||
|
|
@ -4,8 +4,25 @@ title: Code Climate
|
|||
|
||||
# Code Climate
|
||||
|
||||
We are using [Code Climate](https://codeclimate.com/github/thepracticaldev/dev.to) to track code quality and coverage.
|
||||
We are using [Code
|
||||
Climate](https://codeclimate.com/github/thepracticaldev/dev.to) to track code
|
||||
quality and coverage.
|
||||
|
||||
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.
|
||||
Code Climate offers metrics regarding code quality for each individual PR,
|
||||
however, it does not calculate these metrics for the entirety of the project. If
|
||||
you'd like update 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.
|
||||
Before merging a PR to DEV, we expected Code Climate to pass on that PR. If you
|
||||
find Code Climate raising errors on your PR, please fix those issues. Do your
|
||||
best to leave code in a better state than you found it!
|
||||
|
||||
We don't want to make a habit of pandering to Code Climate and its metrics
|
||||
blindly, so if you're in doubt regarding a suggestion on your PR please start a
|
||||
conversation in the PR comments.
|
||||
|
||||
Generally speaking, if you're looking for opportunities to contribute to the
|
||||
project, but you don't have an issue you're interested in solving. Improving the
|
||||
Code Climate metrics is a good place to start. We're happy to see PRs that
|
||||
refactor existing code to reduce duplication and increase readability, given
|
||||
that those refactors are well tested.
|
||||
|
|
|
|||
|
|
@ -4,9 +4,13 @@ title: Integration Tests
|
|||
|
||||
# Integration Tests
|
||||
|
||||
An integration test is when you need to test the interaction of multiple systems or parts of your application.
|
||||
An integration test is a test that measures the interaction of multiple systems
|
||||
or parts of your application.
|
||||
|
||||
An integration test may seem similar to an [acceptance test](/tests/acceptance-tests). 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 an [acceptance
|
||||
test](/tests/acceptance-tests). 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.
|
||||
|
||||
Integration tests can be found in the directory `spec/requests`.
|
||||
|
||||
|
|
@ -16,13 +20,13 @@ You can run all integration tests with:
|
|||
bundle exec rspec spec/requests
|
||||
```
|
||||
|
||||
To run an individual file you can use, for example:
|
||||
To run an individual file you can use:
|
||||
|
||||
```shell
|
||||
bundle exec rspec spec/requests/stories_show_spec.rb
|
||||
```
|
||||
|
||||
To run a specific test case you can use for example:
|
||||
To run a specific test case you can use:
|
||||
|
||||
```shell
|
||||
bundle exec rspec spec/requests/stories_show_spec.rb:10
|
||||
|
|
|
|||
|
|
@ -4,8 +4,8 @@ title: Preact Tests
|
|||
|
||||
# Preact Tests
|
||||
|
||||
The test code is located within the same directory as each component,
|
||||
inside a `__tests__` directory.
|
||||
The test code is located within the same directory as each component, inside a
|
||||
`__tests__` directory.
|
||||
|
||||
```shell
|
||||
$ tree app/javascript/article-form -L 1
|
||||
|
|
@ -28,4 +28,5 @@ or
|
|||
yarn test
|
||||
```
|
||||
|
||||
At the end of the tests execution, you will see the code coverage for the Preact components tests.
|
||||
At the end of the test's execution, you will see the code coverage for the Preact
|
||||
components in our codebase.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: Testing / Q&A Guide
|
||||
title: Testing/QA Guide
|
||||
items:
|
||||
- acceptance-tests.md
|
||||
- integration-tests.md
|
||||
|
|
@ -14,24 +14,41 @@ items:
|
|||
We use the following testing tools:
|
||||
|
||||
- [**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
|
||||
- [**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://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
|
||||
- [**jest-axe**](https://github.com/nickcolley/jest-axe) for detecting basic
|
||||
a11y regressions
|
||||
- [**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 frontend and backend.
|
||||
We strive to provide tests for each pull request that adds new features or fixes
|
||||
a bug. Ideally, we test the functionality of the frontend and the backed.
|
||||
|
||||
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'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](https://guides.rubyonrails.org/testing.html).
|
||||
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 an isolated environment for testing) for every push to this repository.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -4,4 +4,5 @@ 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.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -4,13 +4,17 @@ 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 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.
|
||||
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 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:
|
||||
|
||||
|
|
@ -32,4 +36,5 @@ bundle exec rspec spec/models/user_spec.rb:10
|
|||
|
||||
where `10` is the line number of the test case that you want to execute.
|
||||
|
||||
You can read the official guide [Testing Rails Applications](https://guides.rubyonrails.org/testing.html) to learn more.
|
||||
You can read the official guide [Testing Rails
|
||||
Applications](https://guides.rubyonrails.org/testing.html) to learn more.
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@
|
|||
"git add"
|
||||
],
|
||||
"*.md": [
|
||||
"prettier --write",
|
||||
"prettier --write --prose-wrap always",
|
||||
"git add"
|
||||
]
|
||||
},
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue