* #2507 - refactor GitDocs documentation * #2507 - fix grammar and spelling errors
This commit is contained in:
Andrew Brown
Ben Halpern
parent
d8333fa708
commit
30dcb23169
51 changed files with 753 additions and 327 deletions
7
docs/backend/admin.md
Normal file
7
docs/backend/admin.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
title: Admin Panel
|
||||
---
|
||||
|
||||
# Acessing the Admin Panel
|
||||
|
||||
There is an admin panel located at `/admin`. To access this admin panel, you must use `pudit` to give a user the `admin` role.
|
||||
49
docs/backend/algolia.md
Normal file
49
docs/backend/algolia.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
title: Algolia
|
||||
---
|
||||
|
||||
# Algolia for Search and Caching
|
||||
|
||||
Algolia is a third party service which powers the search and is a caching layer for various endpoints. When working with the API is very likely would need to utilize Algolia. You will need to sign up for a free-tier account, retrieve the keys and provide those keys to the Rails application.
|
||||
|
||||
## Algolia: Sign up
|
||||
|
||||
1. Go to the Algolia sign up [page](https://www.algolia.com/apps/AJVD3Q9KL3/dashboard).
|
||||
|
||||
2. Choose one of the three methods of signing up. (email, github or google)
|
||||
|
||||
3. Fill in your information.
|
||||
|
||||
|
||||
4. Select the datacenter's region.
|
||||
|
||||
|
||||
5. Fill in or skip the project information.
|
||||
|
||||
|
||||
6. You are all set up now! You can go to your dashboard.
|
||||
|
||||
|
||||
7. You can skip the tutorial, we will guide you through the process. Accept the [Terms and Conditions](https://www.algolia.com/policies/terms).
|
||||
|
||||
|
||||
8. All good! You can get your API keys now.
|
||||
|
||||
## Algolia: Get API keys
|
||||
|
||||
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):
|
||||
|
||||
```
|
||||
Application ID -> ALGOLIASEARCH_APPLICATION_ID
|
||||
Search-Only API Key -> ALGOLIASEARCH_SEARCH_ONLY_KEY
|
||||
Admin API KEY -> ALGOLIASEARCH_API_KEY
|
||||
```
|
||||
|
||||
|
||||
|
||||
4. Done.
|
||||
35
docs/backend/auth-github.md
Normal file
35
docs/backend/auth-github.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
---
|
||||
title: GitHub Authentication
|
||||
---
|
||||
|
||||
# GitHub App and Authentication
|
||||
|
||||
Dev.to allows you to authenticate using Github. To use this authentication method in local development, you will need to set up a GitHub App and retrieves keys. Then you'll need to provide theses keys to the Rails application.
|
||||
|
||||
1. [Sign in](https://github.com/settings/applications/new) in your GitHub account.
|
||||
|
||||
2. Fill in the form with an application name, descriptions and URLs `http://localhost:3000/`. Replace the `3000` port if you run DEV on other port.
|
||||
|
||||
|
||||
3. You will be redirected in the app's **Developer settings**. Here you will find the keys. Change them accordingly (name of Github key -> name of our `ENV` variable):
|
||||
|
||||
```
|
||||
Client ID -> GITHUB_KEY
|
||||
Client Secret -> GITHUB_SECRET
|
||||
```
|
||||
|
||||
|
||||
|
||||
4. You will need a personal token as well. From the same dashboard, navigate to **Personal access tokens** and generate a new token.
|
||||
|
||||
5. Fill in the token description and generate the token.
|
||||
|
||||
6. Be sure that you copy the token right away, because it is the only time you will see it. Change it accordingly.
|
||||
|
||||
```
|
||||
Personal access tokens -> GITHUB_TOKEN
|
||||
```
|
||||
|
||||
|
||||
|
||||
7. Done.
|
||||
67
docs/backend/auth-twitter.md
Normal file
67
docs/backend/auth-twitter.md
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
---
|
||||
title: Twitter Authenication
|
||||
---
|
||||
|
||||
# Twitter App and Authentication
|
||||
|
||||
Dev.to allows you to authenicate using Twitter. In order to use this authenication method in local development you will need to setup a Twitter App and retrieves keys. Then you'll need to provide theses keys to the Rails application.
|
||||
|
||||
## Twitter: Sign up
|
||||
|
||||
1. [Sign in](https://developer.twitter.com/apps) to your Twitter account.
|
||||
|
||||
2. In order to get the API keys, you will have to apply for a developer account. Click the **Apply** button.
|
||||
|
||||
|
||||
3. Setup your Twitter account. Be sure you have your phone number and email address filled in.
|
||||
|
||||
|
||||
4. Fill in your account information and give a name to your **developer account**.
|
||||
|
||||
|
||||
5. Write down the reasons that you want to use Twitter API. Mention DEV community and describe the issues and tests and things that you want to work on. Copy it, you might use it later ;)
|
||||
|
||||
|
||||
6. Read :) and accept the Terms and Conditions.
|
||||
|
||||
|
||||
7. Verify your email address once more and you will be done.
|
||||
|
||||
8. You are done.
|
||||
|
||||
## Twitter: Get API keys
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
3. Fill in the app name, description and URL `https://dev.to`.
|
||||
|
||||
|
||||
4. Check the **Enable Sign in with Twitter** option and fill in the Callback URL `http://localhost:3000/users/auth/twitter/callback` (or whatever port you run DEV on).
|
||||
|
||||
5. Fill in the DEV information, **Terms of Service** `http://dev.to/terms` and **Privacy policy** `http://dev.to/privacy`.
|
||||
|
||||
|
||||
6. Write down (or paste) the things that you will work on. Press **Create**.
|
||||
|
||||
|
||||
7. Review the [Twitter Developer Terms](https://developer.twitter.com/en/developer-terms/agreement-and-policy.html) and agree to do nothing sketchy.
|
||||
|
||||
|
||||
8. The app is all set!
|
||||
|
||||
9. One more change... From the app dashboard go to **Permissions** and check **Request email addresses from users** option.
|
||||
|
||||
|
||||
10. From the same dashboard access the **Keys and tokens** and change them accordingly (name of Twitter key -> name of our `ENV` variable):
|
||||
|
||||
```
|
||||
API key -> TWITTER_KEY
|
||||
API secret key -> TWITTER_SECRET
|
||||
Access Token -> TWITTER_ACCESS_TOKEN
|
||||
Access Token Secret -> TWITTER_ACCESS_TOKEN_SECRET
|
||||
```
|
||||
|
||||
|
||||
12
docs/backend/authentication.md
Normal file
12
docs/backend/authentication.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
title: Authentication
|
||||
---
|
||||
|
||||
# Authentication
|
||||
|
||||
Authenication is handled by [Devise](https://github.com/plataformatec/devise) and [OmniAuth](https://github.com/omniauth/omniauth)
|
||||
|
||||
On DEV.to you can only authenicate through Github or Twitter. Please check out the respective guides on how to authenicate:
|
||||
|
||||
- [Twitter App and Authenication](/installation/auth-github)
|
||||
- [Github App and Authenication](/installation/auth-twitter)
|
||||
15
docs/backend/authorization.md
Normal file
15
docs/backend/authorization.md
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
---
|
||||
title: Authorization
|
||||
---
|
||||
|
||||
# Authorization
|
||||
|
||||
Authorization is handled by the third party gem [pundit](https://github.com/varvet/pundit).
|
||||
|
||||
The policies can be found in `/app/policies`
|
||||
|
||||
Authorization is handled by the `authorize` method which you will find in various controllers
|
||||
|
||||
```rb
|
||||
authorize @user
|
||||
```
|
||||
8
docs/backend/previewing-emails.md
Normal file
8
docs/backend/previewing-emails.md
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
---
|
||||
title: Previewing Emails
|
||||
---
|
||||
|
||||
# Previewing emails in development
|
||||
|
||||
You can modify the test in `/test/mailers/previews`
|
||||
You can view the previews at (for example) `http://localhost:3000/rails/mailers/notify_mailer/new_reply_email`
|
||||
32
docs/backend/pusher.md
Normal file
32
docs/backend/pusher.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
title: Pusher
|
||||
---
|
||||
|
||||
# Pusher - Real-Time Notification
|
||||
|
||||
Pusher is third party service being used to power the chat system. When both DEV.to members follow each other they have the ability to use chat and converse with each other.
|
||||
|
||||
In order to use the chat functionality within you development enviroment
|
||||
you will need to sign up for a free-tier Pusher account and retrieves
|
||||
keys. Then you'll need to provide those keys to the Rails application.
|
||||
|
||||
1. [Sign up](https://dashboard.pusher.com/accounts/sign_up) or [sign in](https://dashboard.pusher.com/) to your Pusher account.
|
||||
|
||||
2. Once signed in, fill in the prompt to create a new Pusher Channels app.
|
||||
|
||||
|
||||
3. In your new Pusher Channels app, click the "App Keys" tab.
|
||||
|
||||
|
||||
4. Change your keys accordingly (name of Pusher key -> name of our application key):
|
||||
|
||||
```
|
||||
app_id -> PUSHER_APP_ID
|
||||
key -> PUSHER_KEY
|
||||
secret -> PUSHER_SECRET
|
||||
cluster -> PUSHER_CLUSTER
|
||||
```
|
||||
|
||||
|
||||
|
||||
5. Done.
|
||||
14
docs/backend/readme.md
Normal file
14
docs/backend/readme.md
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
---
|
||||
title: Backend Guide
|
||||
items:
|
||||
- authentication.md
|
||||
- auth-twitter.md
|
||||
- auth-github.md
|
||||
- authorization.md
|
||||
- aloglia.md
|
||||
- pusher.md
|
||||
- admin.md
|
||||
- previewing-emails.md
|
||||
---
|
||||
|
||||
# Backend Guide
|
||||
37
docs/contributing.md
Normal file
37
docs/contributing.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
title: Contributing to Docs
|
||||
---
|
||||
|
||||
# Contributing to Docs
|
||||
|
||||
The documentation you are reading is powered by [GitDocs](https://github.com/timberio/gitdocs).
|
||||
|
||||
## Where The Docs Are Located
|
||||
|
||||
This documentation is located in the [DEV.to codebase](https://github.com/thepracticaldev/dev.to) within the `/docs` directory.
|
||||
|
||||
The docs are a collection of [Markdown files](https://en.wikipedia.org/wiki/Markdown) that also utilize [FrontMatter](https://jekyllrb.com/docs/front-matter/).
|
||||
|
||||
For more information on how to use GitDocs read the [GitDocs guide](https://gitdocs.netlify.com)
|
||||
|
||||
## Running the Docs Locally
|
||||
|
||||
Install the [GitDocs NodeJs library](https://www.npmjs.com/package/gitdocs)
|
||||
|
||||
Specifying `-g` will install the library globally which is what you want to do.
|
||||
|
||||
```
|
||||
npm install gitdocs -g
|
||||
```
|
||||
|
||||
Once installed, to run gitdocs you need to navigate to the root
|
||||
directory of the DEV.to codebase and run
|
||||
|
||||
```
|
||||
gitdocs serve
|
||||
```
|
||||
|
||||
This will start a server on port `8000`
|
||||
|
||||
When you add new markdown pages you'll have to stop and start the
|
||||
websever before you see them.
|
||||
|
|
@ -1,12 +1,18 @@
|
|||
## High Level Design/Brand
|
||||
---
|
||||
title: Branding Guideline
|
||||
---
|
||||
|
||||
# Branding Guideline
|
||||
|
||||
## Themeing
|
||||
|
||||
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 be DEV MAGAZINE, with the exact same branding.
|
||||
|
||||
## Misc Notes
|
||||
## Branding Rules
|
||||
|
||||
- [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
|
||||
|
|
@ -16,8 +22,6 @@ Imagine a developer’s face with the DEV heading above them. If we existed in t
|
|||
- 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.
|
||||
|
||||
## Acknowledgments
|
||||
- We use the [Joystick](http://www.pixelsagas.com/?download=joystick) font by Neale Davidson and [Pixel Sagas](http://www.pixelsagas.com/) for the DEV Logo. We have a commercial license.
|
||||
- Thank you to [EmojiOne](https://www.emojione.com/) for providing free emoji icons
|
||||
|
||||
## TODO
|
||||
We do not currently have a specific design guideline, but we will put this together over time. It may be easier to contribute new features once we develop a stricter guide.
|
||||
- We use the [Joystick](http://www.pixelsagas.com/?download=joystick) font by Neale Davidson and [Pixel Sagas](http://www.pixelsagas.com/) for the DEV Logo. We have a commercial license.
|
||||
- Thank you to [EmojiOne](https://www.emojione.com/) for providing free emoji icons
|
||||
8
docs/design/readme.md
Normal file
8
docs/design/readme.md
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
---
|
||||
title: Designer Guide
|
||||
items:
|
||||
- brand.md
|
||||
- theming-model.md
|
||||
---
|
||||
|
||||
# Designer Guide
|
||||
44
docs/design/theming-model.md
Normal file
44
docs/design/theming-model.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
title: Theming Model
|
||||
---
|
||||
|
||||
# Theming Model
|
||||
|
||||
DEV.to supports different themes such as Normal, Dark, Pink. These themes are powered by [css custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) which are loaded at runtime by javascript via `layouts/_user_config.html.erb`.
|
||||
|
||||
```
|
||||
<script>
|
||||
try {
|
||||
var bodyClass = localStorage.getItem('config_body_class');
|
||||
document.body.className = bodyClass;
|
||||
if (bodyClass.includes('night-theme')) {
|
||||
document.getElementById('body-styles').innerHTML = '<style>\
|
||||
:root {\
|
||||
--theme-background: #0d1219;\
|
||||
--theme-color: #fff;\
|
||||
--theme-logo-background: #0a0a0a;\
|
||||
--theme-logo-color: #fff;\
|
||||
--theme-anchor-color: #17a1f6;\
|
||||
--theme-secondary-color: #cedae2;\
|
||||
--theme-top-bar-background: #1c2938;\
|
||||
--theme-top-bar-background-hover: #27384c;\
|
||||
--theme-top-bar-color: #fff;\
|
||||
--theme-top-bar-search-background: #424a54;\
|
||||
--theme-top-bar-search-color: #fff;\
|
||||
--theme-top-bar-write-background: #00af81;\
|
||||
--theme-top-bar-write-color: #fff;\
|
||||
--theme-container-background: #141f2d;\
|
||||
--theme-container-accent-background: #202c3d;\
|
||||
--theme-container-background-hover: #37475c;\
|
||||
--theme-gradient-background: linear-gradient(to right, #293d56 8%, #282833 18%, #293d56 33%);\
|
||||
--theme-container-color: #fff;\
|
||||
--theme-container-box-shadow: none;\
|
||||
--theme-container-border: 1px solid #141d26;\
|
||||
--theme-social-icon-invert: invert(100)</style>'
|
||||
```
|
||||
|
||||
Within scss files located at `/app/assets/stylesheets` you will see `var` which will call these css custom properties. If a css custom property is not defined `var` will fall back on the second parameter provided which are css variables defined in `app/assets/stylesheets/variables.scss`
|
||||
|
||||
```
|
||||
color: var(--theme-color, $black);
|
||||
```
|
||||
11
docs/faq.md
11
docs/faq.md
|
|
@ -1,11 +0,0 @@
|
|||
## How do I contribute?
|
||||
|
||||
Get started with our [`README`](https://github.com/thepracticaldev/dev.to). You can visit this set of docs for more details when you're up and running.
|
||||
|
||||
## Actually, I meant how to contribute to these cool docs!
|
||||
|
||||
All documentation lives in the [docs folder](https://github.com/thepracticaldev/dev.to/tree/master/docs). Any guides and clarifications are very much welcome.
|
||||
|
||||
## I'm getting an error [SOME-ERROR]. Where do I report it?
|
||||
|
||||
You can [write a new issue](https://github.com/thepracticaldev/dev.to/issues/new) and let us know what exactly what went wrong. We'll be able to help you debug if we have specific information, the context of how the error happened, and any other information you think would help.
|
||||
5
docs/faqs.md
Normal file
5
docs/faqs.md
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
---
|
||||
title: FAQs
|
||||
---
|
||||
|
||||
# Frequently Asked Questions
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
## ⚛ Front-End Development
|
||||
|
||||
Before doing any development in the front-end, ensure that [Node.js](https://nodejs.org) is installed. To install Node.js, you can do one of the following:
|
||||
|
||||
* [Download and install the LTS version](https://nodejs.org/en/download), or
|
||||
* [Download and install nvm](https://github.com/creationix/nvm) ([win](https://github.com/coreybutler/nvm-windows)) and follow their instructions to install the Node.js LTS version (recommended), or
|
||||
* [Download and install n](https://github.com/tj/n) and follow their instructions to install the Node.js LTS version, or
|
||||
* Install Node.js via Homebrew (macOS only) `brew install node`
|
||||
|
||||
For bundling, we use Webpack via the [webpacker](https://github.com/rails/webpacker) since the backend is Ruby on Rails.
|
||||
|
||||
There is some legacy code which is old school JS, but for all things new, [Preact](https://preactjs.com) is where it's at. If you're new to Preact, check out their [documentation](https://preactjs.com/guide/getting-started). Also, consider following the [#preact](https://dev.to/t/preact) tag on [dev.to](https://dev.to).
|
||||
|
||||
### 👷 Building components
|
||||
|
||||
We use [Storybook](https://storybook.js.org) to develop components. It allows you to focus on building components without the burden of the whole application running. If you're new to Storybook, check out their [documentation](https://storybook.js.org/basics/guide-react). Also, consider following the [#storybook](https://dev.to/t/storybook) tag on [dev.to](https://dev.to).
|
||||
|
||||
To get Storybook running on your local:
|
||||
|
||||
* 📦 Run `npm install` or `yarn` to ensure all your dependencies are installed.
|
||||
* 🏁 Run `npm run storybook` or `yarn storybook` to start Storybook.
|
||||
* 🏗️ Start working on your component and see the changes in Storybook as you save.
|
||||
|
||||
### Browser Support
|
||||
|
||||
#### Chrome >= 59
|
||||
#### Firefox >= 52
|
||||
#### Safari >= 10
|
||||
#### Opera >= 50
|
||||
#### Edge >= 16
|
||||
|
||||
We do not officially support any version of IE or any browser not listed here, but don't go out of your way to not support it! And if there is anything we should change about this, open an issue.
|
||||
38
docs/frontend/js-initializers.md
Normal file
38
docs/frontend/js-initializers.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
title: Plain Javascript and Intializers
|
||||
---
|
||||
|
||||
# Plain Javascript and JS Intializers
|
||||
|
||||
DEV.to has two javascript codebases. One is located at
|
||||
`/app/javascripts` and this is plain javascript being served using [spockets](https://github.com/rails/sprockets-rails)
|
||||
|
||||
The plain javascript codebase is not transpiled and will be limited to
|
||||
whatever flavour of javascript provided by the end-user's
|
||||
web-browser
|
||||
|
||||
`app/javascripts/application.js` is primary packaged javascript file
|
||||
which should be included in the primary template located within
|
||||
`app/layouts`. `application.js` automatically includes all javascript
|
||||
files via:
|
||||
|
||||
```
|
||||
//= require_tree .
|
||||
```
|
||||
|
||||
One javascript file it loads is `initializePage.js.erb` which boostraps
|
||||
the majority of functionality. You will see wtihin this file it manually
|
||||
loads multiple files:
|
||||
|
||||
```
|
||||
initializeBaseTracking();
|
||||
initializeTouchDevice();
|
||||
initializeCommentsPage();
|
||||
initEditorResize();
|
||||
initLeaveEditorWarning();
|
||||
initializeArticleReactions();
|
||||
initNotifications();
|
||||
initializeSplitTestTracking();
|
||||
```
|
||||
|
||||
Theses files are located at `/app/assets/javascripts/intializers`
|
||||
|
|
@ -1,3 +1,9 @@
|
|||
---
|
||||
title: Liquid Tags
|
||||
---
|
||||
|
||||
# Liquid Tags
|
||||
|
||||
Liquid tags are a special element of the [dev.to](/) markdown editor.
|
||||
|
||||
They are custom embeds that are added via `{% %}` syntax. [Liquid](https://shopify.github.io/liquid/) is a templating language developed by Shopify.
|
||||
|
|
@ -9,3 +15,29 @@ They make for good community contributions because they can be extended and impr
|
|||
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.
|
||||
|
||||
Here is a bunch of liquid tags supported on DEV.to
|
||||
|
||||
```
|
||||
{% link https://dev.to/kazz/boost-your-productivity-using-markdown-1be %}
|
||||
{% user jess %}
|
||||
{% tag git %}
|
||||
{% devcomment 2d1a %}
|
||||
{% podcast https://dev.to/basecspodcast/s2e2--queues-irl %}
|
||||
{% twitter 834439977220112384 %}
|
||||
{% glitch earthy-course %}
|
||||
{% github thepracticaldev/dev.to %}
|
||||
{% youtube dQw4w9WgXcQ %}
|
||||
{% vimeo 193110695 %}
|
||||
{% slideshare rdOzN9kr1yK5eE %}
|
||||
{% codepen https://codepen.io/twhite96/pen/XKqrJX %}
|
||||
{% stackblitz ball-demo %}
|
||||
{% codesandbox ppxnl191zx %}
|
||||
{% jsfiddle https://jsfiddle.net/link2twenty/v2kx9jcd %}
|
||||
{% replit @WigWog/PositiveFineOpensource %}
|
||||
{% instagram BXgGcAUjM39 %}
|
||||
{% speakerdeck 7e9f8c0fa0c949bd8025457181913fd0 %}
|
||||
{% soundcloud https://soundcloud.com/user-261265215/dev-to-review-episode-1 %}
|
||||
% spotify spotify:episode:5V4XZWqZQJvbddd31n56mf %}
|
||||
{% blogcast 1234 %}
|
||||
```
|
||||
7
docs/frontend/preact.md
Normal file
7
docs/frontend/preact.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
title: Preact Tests
|
||||
---
|
||||
|
||||
# Writing Preact Tests
|
||||
|
||||
Preact is an alternative to React with the same modern API. Preact components are packaged using webpacker and the preact code is located in `app/javascript`
|
||||
10
docs/frontend/readme.md
Normal file
10
docs/frontend/readme.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
---
|
||||
title: Frontend Guide
|
||||
items:
|
||||
- js-initializers.md
|
||||
- webpacker.md
|
||||
- preact.md
|
||||
- liquid-tags.md
|
||||
---
|
||||
|
||||
# Frontend Guide
|
||||
29
docs/frontend/webpacker.md
Normal file
29
docs/frontend/webpacker.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
---
|
||||
title: Webpacker
|
||||
---
|
||||
|
||||
# Webpacker
|
||||
|
||||
DEV.to has two javascript codebases. One is located at
|
||||
`/app/javascripts` and this is plain javascript being served using `spockets`
|
||||
|
||||
The other codebase is located at `/app/javascript` which is for preact
|
||||
components and is served via `webpack` which is integrated into the
|
||||
Rails app using `Webpacker`
|
||||
|
||||
There is a packs directory `/app/javascript/packs` where you can create
|
||||
new pack files.
|
||||
|
||||
Since DEV.to is not an SPA (Single Page Application)
|
||||
preact apps are mounted as needed by including the pack file in the erb
|
||||
files. eg
|
||||
|
||||
```
|
||||
<%= javascript_pack_tag "webShare", defer: true %>
|
||||
```
|
||||
|
||||
This pack would correspond with
|
||||
|
||||
```
|
||||
app/javascripts/packs/webShare.js
|
||||
```
|
||||
|
|
@ -1,162 +0,0 @@
|
|||
There are a few services you'll need **_(all free)_** in order to run the development server and access the app locally. Here are the instructions for getting them.
|
||||
|
||||
# GitHub
|
||||
|
||||
1. [Sign in](https://github.com/settings/applications/new) in your Github account.
|
||||
|
||||
2. Fill in the form with an application name, descriptions and URLs `http://localhost:3000/`. Replace the `3000` port if you run DEV on other port.
|
||||
|
||||
|
||||
3. You will be redirected in the app's **Developer settings**. Here you will find the keys. Change them accordingly (name of Github key -> name of our `ENV` variable):
|
||||
|
||||
```
|
||||
Client ID -> GITHUB_KEY
|
||||
Client Secret -> GITHUB_SECRET
|
||||
```
|
||||
|
||||
|
||||
|
||||
4. You will need a personal token as well. From the same dashboard, navigate to **Personal access tokens** and generate a new token.
|
||||
|
||||
5. Fill in the token description and generate the token.
|
||||
|
||||
6. Be sure that you copy the token right away, because it is the only time you will see it. Change it accordingly.
|
||||
|
||||
```
|
||||
Personal access tokens -> GITHUB_TOKEN
|
||||
```
|
||||
|
||||
|
||||
|
||||
7. Done.
|
||||
|
||||
# Twitter App
|
||||
|
||||
## Twitter: Sign up
|
||||
|
||||
1. [Sign in](https://developer.twitter.com/apps) to your Twitter account.
|
||||
|
||||
2. In order to get the API keys, you will have to apply for a developer account. Click the **Apply** button.
|
||||
|
||||
|
||||
3. Setup your Twitter account. Be sure you have your phone number and email address filled in.
|
||||
|
||||
|
||||
4. Fill in your account information and give a name to your **developer account**.
|
||||
|
||||
|
||||
5. Write down the reasons that you want to use Twitter API. Mention DEV community and describe the issues and tests and things that you want to work on. Copy it, you might use it later ;)
|
||||
|
||||
|
||||
6. Read :) and accept the Terms and Conditions.
|
||||
|
||||
|
||||
7. Verify your email address once more and you will be done.
|
||||
|
||||
8. You are done.
|
||||
|
||||
## Twitter: Get API keys
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
3. Fill in the app name, description and URL `https://dev.to`.
|
||||
|
||||
|
||||
4. Check the **Enable Sign in with Twitter** option and fill in the Callback URL `http://localhost:3000/users/auth/twitter/callback` (or whatever port you run DEV on).
|
||||
|
||||
5. Fill in the DEV information, **Terms of Service** `http://dev.to/terms` and **Privacy policy** `http://dev.to/privacy`.
|
||||
|
||||
|
||||
6. Write down (or paste) the things that you will work on. Press **Create**.
|
||||
|
||||
|
||||
7. Review the [Twitter Developer Terms](https://developer.twitter.com/en/developer-terms/agreement-and-policy.html) and agree to do nothing sketchy.
|
||||
|
||||
|
||||
8. The app is all set!
|
||||
|
||||
9. One more change... From the app dashboard go to **Permissions** and check **Request email addresses from users** option.
|
||||
|
||||
|
||||
10. From the same dashboard access the **Keys and tokens** and change them accordingly (name of Twitter key -> name of our `ENV` variable):
|
||||
|
||||
```
|
||||
API key -> TWITTER_KEY
|
||||
API secret key -> TWITTER_SECRET
|
||||
Access Token -> TWITTER_ACCESS_TOKEN
|
||||
Access Token Secret -> TWITTER_ACCESS_TOKEN_SECRET
|
||||
```
|
||||
|
||||
|
||||
|
||||
11. Done.
|
||||
|
||||
# Algolia
|
||||
|
||||
## Algolia: Sign up
|
||||
|
||||
1. Go to the Algolia sign up [page](https://www.algolia.com/apps/AJVD3Q9KL3/dashboard).
|
||||
|
||||
2. Choose one of the three methods of signing up. (email, github or google)
|
||||
|
||||
3. Fill in your information.
|
||||
|
||||
|
||||
4. Select the datacenter's region.
|
||||
|
||||
|
||||
5. Fill in or skip the project information.
|
||||
|
||||
|
||||
6. You are all set up now! You can go to your dashboard.
|
||||
|
||||
|
||||
7. You can skip the tutorial, we will guide you through the process. Accept the [Terms and Conditions](https://www.algolia.com/policies/terms).
|
||||
|
||||
|
||||
8. All good! You can get your API keys now.
|
||||
|
||||
## Algolia: Get API keys
|
||||
|
||||
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):
|
||||
|
||||
```
|
||||
Application ID -> ALGOLIASEARCH_APPLICATION_ID
|
||||
Search-Only API Key -> ALGOLIASEARCH_SEARCH_ONLY_KEY
|
||||
Admin API KEY -> ALGOLIASEARCH_API_KEY
|
||||
```
|
||||
|
||||
|
||||
|
||||
4. Done.
|
||||
|
||||
# Pusher
|
||||
|
||||
1. [Sign up](https://dashboard.pusher.com/accounts/sign_up) or [sign in](https://dashboard.pusher.com/) to your Pusher account.
|
||||
|
||||
2. Once signed in, fill in the prompt to create a new Pusher Channels app.
|
||||
|
||||
|
||||
3. In your new Pusher Channels app, click the "App Keys" tab.
|
||||
|
||||
|
||||
4. Change your keys accordingly (name of Pusher key -> name of our application key):
|
||||
|
||||
```
|
||||
app_id -> PUSHER_APP_ID
|
||||
key -> PUSHER_KEY
|
||||
secret -> PUSHER_SECRET
|
||||
cluster -> PUSHER_CLUSTER
|
||||
```
|
||||
|
||||
|
||||
|
||||
5. Done.
|
||||
17
docs/getting-started/branching.md
Normal file
17
docs/getting-started/branching.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
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. For features or improvement you will create a branch as follows:
|
||||
|
||||
```
|
||||
git checkout -b feature/that-new-feature`
|
||||
```
|
||||
|
||||
For a bug branch you will do as follows:
|
||||
|
||||
```
|
||||
bug/fixing-that-bug
|
||||
```
|
||||
9
docs/getting-started/committing.md
Normal file
9
docs/getting-started/committing.md
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
---
|
||||
title: Committing
|
||||
---
|
||||
|
||||
# Committing and Pre-Commit 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.
|
||||
|
||||
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.
|
||||
17
docs/getting-started/config-env.md
Normal file
17
docs/getting-started/config-env.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
title: Configure Enviroment Variables
|
||||
---
|
||||
|
||||
# Set up your environment variables/secrets
|
||||
|
||||
- Take a look at `Envfile`. This file lists all the `ENV` variables we use and provides a fake default for any missing keys. You'll need to get your own free [Algolia credentials](http://docs.dev.to/get-api-keys-dev-env/#algolia) to get your development environment running.
|
||||
- This [guide](http://docs.dev.to/get-api-keys-dev-env/) will show you how to get free API keys for additional services that may be required to run certain parts of the app.
|
||||
- For any key that you wish to enter/replace:
|
||||
1. Create `config/application.yml` by copying from the provided template (ie. with bash: `cp config/sample_application.yml config/application.yml`). This is a personal file that is ignored in git.
|
||||
2. Obtain the development variable and apply the key you wish to enter/replace. ie:
|
||||
```
|
||||
GITHUB_KEY: "SOME_REAL_SECURE_KEY_HERE"
|
||||
GITHUB_SECRET: "ANOTHER_REAL_SECURE_KEY_HERE"
|
||||
```
|
||||
- If you are missing `ENV` variables on bootup, `envied` gem will alert you with messages similar to `'error_on_missing_variables!': The following environment variables should be set: A_MISSING_KEY.`.
|
||||
- You do not need "real" keys for basic development. Some features require certain keys, so you may be able to add them as you go.
|
||||
19
docs/getting-started/db.md
Normal file
19
docs/getting-started/db.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
title: Preparing the Database
|
||||
---
|
||||
|
||||
# Preparing the Database
|
||||
|
||||
We need to create our database, load the database schema, and load seed
|
||||
data. This can be accomplished with:
|
||||
|
||||
`rake db:setup`
|
||||
|
||||
`db:setup` actually runs the following rake commands in order so
|
||||
you could alternatively run each of these to produce the same result.
|
||||
|
||||
```
|
||||
rake db:create
|
||||
rake db:schema:load
|
||||
rake db:seed
|
||||
```
|
||||
13
docs/getting-started/forking.md
Normal file
13
docs/getting-started/forking.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
title: Forking The Repo
|
||||
---
|
||||
|
||||
# Forking The Repo
|
||||
|
||||
Fork dev.to repository, ie. `https://github.com/thepracticaldev/dev.to/fork`
|
||||
|
||||
Clone your forked repository,
|
||||
|
||||
```
|
||||
git clone https://github.com/<your-username>/dev.to.git
|
||||
```
|
||||
13
docs/getting-started/pull-request.md
Normal file
13
docs/getting-started/pull-request.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
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. [More info here](https://docs.dev.to/testing/)
|
||||
- Document your reasoning behind the changes. Explain why you wrote the code in the way you did. The code should explain what it does.
|
||||
- If there's an existing issue related to the pull request, reference to it by adding something like `References/Closes/Fixes/Resolves #305`, where 305 is the issue number. [More info here](https://github.com/blog/1506-closing-issues-via-pull-requests)
|
||||
- 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!_
|
||||
13
docs/getting-started/readme.md
Normal file
13
docs/getting-started/readme.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
title: Getting Started
|
||||
items:
|
||||
- forking.md
|
||||
- config-env.md
|
||||
- db.md
|
||||
- syncing.md
|
||||
- branching.md
|
||||
- committing.md
|
||||
- pull-request.md
|
||||
---
|
||||
|
||||
# Getting Started!
|
||||
|
|
@ -1,8 +1,12 @@
|
|||
### Maintaining Your Fork
|
||||
---
|
||||
title: Syncing Your Fork
|
||||
---
|
||||
|
||||
# Syncing Your Fork
|
||||
|
||||
Now that you have a copy of your fork, there is work you will need to do to keep it current.
|
||||
|
||||
#### Setup Your Upstream
|
||||
## Setup Your Upstream
|
||||
|
||||
Inside your dev.to directory, add a remote to the official dev.to repo:
|
||||
|
||||
|
|
@ -10,7 +14,7 @@ Inside your dev.to directory, add a remote to the official dev.to repo:
|
|||
$ git remote add upstream https://github.com/thepracticaldev/dev.to.git
|
||||
```
|
||||
|
||||
#### Rebasing from Upstream
|
||||
## Rebasing from Upstream
|
||||
|
||||
Do this prior to every time you create a branch for a PR:
|
||||
|
||||
|
|
@ -44,6 +48,6 @@ $ git push origin master --force
|
|||
|
||||
This will overwrite the `master` branch of your fork.
|
||||
|
||||
#### Also see
|
||||
## Also see
|
||||
|
||||
- [Syncing a fork](https://help.github.com/articles/syncing-a-fork/)
|
||||
|
|
@ -1,17 +0,0 @@
|
|||
This is random collection of development hints and gotchas that we've run into in the past.
|
||||
|
||||
## Previewing emails in development
|
||||
|
||||
You can modify the test in `/test/mailers/previews`
|
||||
You can view the previews at (for example) `http://localhost:3000/rails/mailers/notify_mailer/new_reply_email`
|
||||
|
||||
## Previewing these docs in development
|
||||
|
||||
0. Make sure you are at the base of the repository
|
||||
1. Install gitdocs `npm install -g gitdocs@next`
|
||||
1. Serve it `gitdocs serve`
|
||||
1. Visit `http://localhost:8000`
|
||||
|
||||
## Caching
|
||||
|
||||
- [DEV Notes: Don't Forget To Clear Cache!](https://dev.to/jess/dev-notes-don-t-forget-to-clear-cache-962)
|
||||
10
docs/installation/docker.md
Normal file
10
docs/installation/docker.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
# Docker [Beta]
|
||||
|
||||
1. Install `docker` and `docker-compose`
|
||||
1. `git clone git@github.com:thepracticaldev/dev.to.git`
|
||||
1. Set environment variables above as described in the "Basic Installation"
|
||||
1. run `docker-compose build`
|
||||
1. run `docker-compose run web rails db:setup`
|
||||
1. run `docker-compose run web yarn install`
|
||||
1. run `docker-compose up`
|
||||
1. That's it! Navigate to `localhost:3000`
|
||||
7
docs/installation/gitpod.md
Normal file
7
docs/installation/gitpod.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
title: GitPod
|
||||
---
|
||||
|
||||
# GitPod
|
||||
|
||||
You can also [spin up a "local" instance of DEV in the cloud with GitPod (It's incredibly simple)](https://dev.to/ben/spin-up-a-local-instance-of-dev-in-the-cloud-with-gitpod-it-s-incredibly-simple-pij): https://gitpod.io/#https://github.com/thepracticaldev/dev.to
|
||||
|
|
@ -1,3 +1,9 @@
|
|||
---
|
||||
title: Linux
|
||||
---
|
||||
|
||||
# Installing DEV.to on Linux
|
||||
|
||||
## Installing prerequisites
|
||||
|
||||
These prerequisites assume you're working on a Linux-based operating system but have been tested on Ubuntu 18.04.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,9 @@
|
|||
---
|
||||
title: Mac
|
||||
---
|
||||
|
||||
# Installing DEV.to on Mac
|
||||
|
||||
## Installing prerequisites
|
||||
|
||||
### Ruby
|
||||
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
title: Postgres
|
||||
---
|
||||
|
||||
# Setup your application with PostgreSQL
|
||||
|
||||
Follow the instructions in the installation guide below that corresponds to your operating system:
|
||||
|
|
@ -1,30 +1,28 @@
|
|||
---
|
||||
title: 'Installation'
|
||||
items:
|
||||
- linux.md
|
||||
- path: mac-os.md
|
||||
title: macOS
|
||||
- mac.md
|
||||
- windows.md
|
||||
- linux.md
|
||||
- docker.md
|
||||
- gitpod.md
|
||||
- postgres.md
|
||||
---
|
||||
|
||||
# Installation Guides For macOS, Linux, and Windows
|
||||
# Installation Guide
|
||||
|
||||
Below are the guides for installing the app on different operating systems.
|
||||
There are many different ways you can install the **development environment** so you can help contribute code to DEV.to.
|
||||
|
||||
These guides could be incorrect or outdated. If you come across anything that needs to be changed, make a PR! Thanks!
|
||||
## Installing Locally
|
||||
|
||||
# GitPod
|
||||
You can install DEV.to to your local machine and we have instructions for [Mac](/installation/mac-os), [Windows](/installation/windows) and [Linux](/installation/linux)
|
||||
|
||||
You can also [spin up a "local" instance of DEV in the cloud with GitPod (It's incredibly simple)](https://dev.to/ben/spin-up-a-local-instance-of-dev-in-the-cloud-with-gitpod-it-s-incredibly-simple-pij): https://gitpod.io/#https://github.com/thepracticaldev/dev.to
|
||||
## Running Docker
|
||||
|
||||
# Docker [Beta]
|
||||
Installing to your local machine can be troublesome for many reasons such as conflicting database and runtime versions. Another way you can get a development environment up and running is with Docker. Docker will install everything you need in an isolated , and you need not concern about the details.
|
||||
|
||||
Our docker implementation is incomplete and may not work smoothly. Please kindly report any issues and any contribution is welcomed!
|
||||
We have instructions for installing with [Docker](/installation/docker)
|
||||
|
||||
1. Install `docker` and `docker-compose`
|
||||
1. `git clone git@github.com:thepracticaldev/dev.to.git`
|
||||
1. Set environment variables above as described in the "Basic Installation"
|
||||
1. run `docker-compose build`
|
||||
1. run `docker-compose run web rails db:setup`
|
||||
1. run `docker-compose run web yarn install`
|
||||
1. run `docker-compose up`
|
||||
1. That's it! Navigate to `localhost:3000`
|
||||
## GitPod
|
||||
|
||||
If you are having trouble with local installation and Docker confuses you, then you can launch a **development environment** with the press of a button with GitPod. GitPod is an IDE in the cloud which is also attached to a web-server. It will install everything you need. If you are comfortable doing everything from a web-browser than we have instructions for installing with [GitPod](/installation/gitpod)
|
||||
|
|
|
|||
|
|
@ -1,3 +1,9 @@
|
|||
---
|
||||
title: Windows
|
||||
---
|
||||
|
||||
# Installing DEV.to on Windows
|
||||
|
||||
## Installing prerequisites
|
||||
|
||||
These prerequisites assume you're working on a 64bit Windows 10 operating system machine.
|
||||
|
|
|
|||
|
|
@ -1,23 +1,29 @@
|
|||
---
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
### Where can I learn more about the AGPL-3 license?
|
||||
## 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.
|
||||
|
||||
### Why does DEV have a CLA?
|
||||
## 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 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?
|
||||
## 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.
|
||||
|
||||
### What if I have other questions?
|
||||
## What if I have other questions?
|
||||
|
||||
Please check out our main repository or send an email to yo@dev.to.
|
||||
|
|
@ -1,41 +1,14 @@
|
|||
---
|
||||
items:
|
||||
- path: get-api-keys-dev-env.md
|
||||
title: Getting API Keys for Dev Environment
|
||||
- path: testing.md
|
||||
title: Testing
|
||||
- path: frontend.md
|
||||
title: Frontend
|
||||
- path: addl-tech.md
|
||||
title: Key App Tech & Services
|
||||
- path: additional-postgres-setup.md
|
||||
title: Additional PostgreSQL Setup (for non-macOS)
|
||||
- path: helpful-hints.md
|
||||
title: Random Helpful Things
|
||||
- path: faq.md
|
||||
title: FAQ
|
||||
- path: license-faq.md
|
||||
title: License FAQ
|
||||
- path: installation
|
||||
title: Installation Guide
|
||||
- path: liquid-tags.md
|
||||
title: Liquid Tags
|
||||
- path: design-guidelines.md
|
||||
title: Design Guidelines
|
||||
- path: vocabulary.md
|
||||
title: Vocabulary
|
||||
- path: dev-instance.md
|
||||
title: Hosting Your Own DEV Instance
|
||||
- path: maintaining-your-fork.md
|
||||
title: Maintaining Your Fork
|
||||
- installation
|
||||
- techincal-overview.md
|
||||
- getting-started
|
||||
- backend
|
||||
- frontend
|
||||
- design
|
||||
- tests
|
||||
- contributing.md
|
||||
- faqs.md
|
||||
- licensing.md
|
||||
- self-hosting.md
|
||||
---
|
||||
|
||||
# Welcome to the dev.to documentation!
|
||||
|
||||
_If you're viewing this on GitHub, we recommend viewing our docs on our static page: [docs.dev.to](https://docs.dev.to)_
|
||||
|
||||
This is the home of the nitty-gritty technical details for contributing to dev.to.
|
||||
|
||||
If you're looking to get started, check out our [`README` in the main repo.](https://github.com/thepracticaldev/dev.to)
|
||||
|
||||
Have any questions, comments, or concerns? Check out our [FAQ](https://docs.dev.to/faq/), or ask for help in our [help thread on dev.to](https://dev.to/devteam/devto-open-source-helpdiscussion-thread-v0-1l45)!
|
||||
|
|
|
|||
|
|
@ -1,10 +1,14 @@
|
|||
---
|
||||
title: Self-hosting DEV.to
|
||||
---
|
||||
|
||||
## Hosting Your Own DEV Instance
|
||||
|
||||
We envision that the DEV codebase will eventually be generalized to the point where it can be used to power other communities and ecosystems. We’re excited for the project to mature to that point, but we’re not quite there yet. This page is designed to serve as an FAQ and checklist of considerations that are relevant to the goal of eventually hosting your own version of our community platform.
|
||||
We envision that the DEV codebase will eventually be generalized to the point where it can be used to power other communities and ecosystems. We’re excited for the project to mature to that point, but we’re not quite there yet. This page is designed to serve as an FAQ and checklist of considerations that are relevant to the goal of eventually hosting your own version of our community platform.
|
||||
|
||||
### Current Limitations
|
||||
|
||||
- Many aspects of the app are 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 project.
|
||||
- Many aspects of the app are 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 project.
|
||||
- We do not currently have a versioning system that will allow us to share fixes and improvements with modified versions of the code.
|
||||
|
||||
### I want to stand up my own entity using the DEV codebase, how can I help?
|
||||
|
|
@ -12,4 +16,4 @@ We envision that the DEV codebase will eventually be generalized to the point wh
|
|||
- You can help us generalize the code, removing DEV-specific language and images and replacing them with environment variables or database tables as appropriate
|
||||
- You can commit to staying in very close coordination with us as we navigate the process together.
|
||||
|
||||
The long-term benefits of doing this the right way far outweigh the short-term gains of spinning something up without consulting us. If you are interested in getting started with this process, let us know in [this thread](https://dev.to/ben/so-you-want-to-stand-up-your-own-instance-of-dev-help-thread-1elo).
|
||||
The long-term benefits of doing this the right way far 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,3 +1,7 @@
|
|||
---
|
||||
title: Technical Overview
|
||||
---
|
||||
|
||||
## 🔑 Key App tech/services
|
||||
|
||||
- We use [_Puma_](https://github.com/puma/puma) for the server
|
||||
11
docs/tests/acceptance-tests.md
Normal file
11
docs/tests/acceptance-tests.md
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
---
|
||||
title: Acceptance Tests
|
||||
---
|
||||
|
||||
# Acceptance Tests
|
||||
|
||||
Acceptance tests are tests from the perceptive of the end-user. What the
|
||||
means that we are simulating what a user could do from their web-browser
|
||||
and testing the end expected result.
|
||||
|
||||
Acceptance tests can be found at: `spec/system`
|
||||
9
docs/tests/codeclimate.md
Normal file
9
docs/tests/codeclimate.md
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
---
|
||||
title: CodeClimate
|
||||
---
|
||||
|
||||
# CodeClimate
|
||||
|
||||
We are using CodeClimate to track code quality and code coverage. CodeClimate will grade the quality of the code of every PR but not the entirety of the project. If you feel that the current linting rule is unreasonable, feel free to submit a _separate_ PR to change it. Fix any errors that CodeClimate provides and strive to leave code better than you found it.
|
||||
|
||||
Travis will upload Simplecov data to CodeClimate.
|
||||
17
docs/tests/integration-tests.md
Normal file
17
docs/tests/integration-tests.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
title: Integration Tests
|
||||
---
|
||||
|
||||
# Integration Tests
|
||||
|
||||
To understand integration tests lets understand the purpose of a unit
|
||||
test. A unit test is about testing in isolate a single function and all
|
||||
of its possible output.
|
||||
|
||||
An integration test is when you need to test the result of multiple of
|
||||
functions or systems.
|
||||
|
||||
An integration test may seem similar to a user acceptance test. A user acceptance test is from the perceptive of the end-user where
|
||||
an integration test is from the perceptive of the developer.
|
||||
|
||||
Integration tests can be found in: `spec/requests/`
|
||||
16
docs/tests/preact-tests.md
Normal file
16
docs/tests/preact-tests.md
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
---
|
||||
title: Preact Tests
|
||||
---
|
||||
|
||||
The test code is located within the same directory as the component
|
||||
called `__tests__` so for example
|
||||
|
||||
```
|
||||
app/javascripts/articl-form/__tests__
|
||||
```
|
||||
|
||||
The testing library being used is `jest`. To run jest tests:
|
||||
|
||||
```
|
||||
npm run test
|
||||
```
|
||||
|
|
@ -1,4 +1,14 @@
|
|||
# Testing
|
||||
---
|
||||
title: Test / Coverage / Q&A Guide
|
||||
items:
|
||||
- acceptance-tests.md
|
||||
- integration-tests.md
|
||||
- unit-tests.md
|
||||
- preact-tests.md
|
||||
- codeclimate.md
|
||||
- simplecov.md
|
||||
- skip-ci
|
||||
---
|
||||
|
||||
We use the following testing tools:
|
||||
|
||||
|
|
@ -16,23 +26,6 @@ If you'd like to help us improve our test coverage, we recommend checking out ou
|
|||
|
||||
If you're new to writing tests in general or with Rails, we recommend reading about testing with Rails, RSpec, and Capybara first.
|
||||
|
||||
## How to Use SimpleCov
|
||||
|
||||
1. Run `bundle exec rspec spec` or `bin/rspec spec`. You can run RSpec on the whole project or a single file.
|
||||
2. After rspec is complete, open `index.html` within the coverage folder to view code coverages.
|
||||
|
||||
You can also run `bin/rspecov` to run `bin/rspec spec`
|
||||
|
||||
## CodeClimate
|
||||
|
||||
We are using CodeClimate to track code quality and code coverage. Codeclimate will grade the quality of the code of every PR but not the entirety of the project. If you feel that the current linting rule is unreasonable, feel free to submit a _separate_ PR to change it. Fix any errors that CodeClimate provides and strive to leave code better than you found it.
|
||||
|
||||
Travis will upload Simplecov data to CodeClimate. We are still in the early stage of using it so it may not provide an accurate measurement our of codebase.
|
||||
|
||||
#### Skipping CI build (Not recommended)
|
||||
|
||||
If your changes are **minor** (i.e. updating README, fixing a typo), you can skip CI by adding `[ci skip]` to your commit message.
|
||||
|
||||
## Continuous Integration & Continuous Deployment
|
||||
|
||||
We are using Travis for CI and CD. Travis will run a build (in isolated environment for testing) for every push to this repository. Keep in mind that a passing-build does not necessarily mean the project won't run into any issues. Strive to write good tests for any chunk of code you wish to contribute. Travis will deploy a pull request to production after CI passes. Our test suite is not perfect and sometimes a re-rerun is needed.
|
||||
10
docs/tests/simplecov.md
Normal file
10
docs/tests/simplecov.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
---
|
||||
title: SimpleCov
|
||||
---
|
||||
|
||||
# How to Use SimpleCov
|
||||
|
||||
1. Run `bundle exec rspec spec` or `bin/rspec spec`. You can run RSpec on the whole project or a single file.
|
||||
2. After rspec is complete, open `index.html` within the coverage folder to view code coverages.
|
||||
|
||||
You can also run `bin/rspecov` to run `bin/rspec spec`
|
||||
7
docs/tests/skip-ci
Normal file
7
docs/tests/skip-ci
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
title: Skipping CI for minor changes
|
||||
---
|
||||
|
||||
# Skipping CI build (Not recommended)
|
||||
|
||||
If your changes are **minor** (i.e. updating README, fixing a typo), you can skip CI by adding `[ci skip]` to your commit message.
|
||||
16
docs/tests/unit-tests.md
Normal file
16
docs/tests/unit-tests.md
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
---
|
||||
title: Unit Tests
|
||||
---
|
||||
|
||||
# Unit Tests
|
||||
|
||||
A unit test is about testing in isolate a single function and all of its possible output.
|
||||
|
||||
Unit tests can be found in
|
||||
|
||||
`spec/models` and other various directories within the `spec`
|
||||
directory.
|
||||
|
||||
`spec/system` is for integration tests
|
||||
|
||||
`spec/requets` is for acceptance tests
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
## Vocabulary / Team Jargon
|
||||
|
||||
### Issue Levels
|
||||
|
||||
- Level 5: Mission critical. Tends to impact all users. (i.e. production stuck in an infinite heroku deployment)
|
||||
|
||||
- Level 4: Not mission critical but needs to be taken care of as quickly as possible. Tends to impact a subset of users. (i.e. form submission broken on mentorship settings)
|
||||
|
||||
- Level 3: Issue that can wait until the next sprint planning, but definitely needs to be discussed. Often an edge case that sparks discussion -- is this a patch or do we need to re-architect something? (i.e. running out of memory where a few pages get 500 errors)
|
||||
|
||||
- Level 2: Issue is not affecting users. Likely an internal tool that needs to be fixed. (i.e. slack notifications not pinging)
|
||||
|
||||
- Level 1: Tech that stopped working but also isn't related to users/the site. (i.e. the gumball machine we use to generate random winners is broken)
|
||||
Loading…
Add table
Reference in a new issue