Update Docs [ci skip] (forem#656)

maestromac · benhalpern · commit 243c44e23d76 · 2018-08-08T10:36:32.000-04:00
* Move frontend doc [ci skip]

* Fix DEV styling [ci skip]

* Update table of contents [ci skip]

* Move stuffs around [ci skip]

* Move stuffs around [ci skip]

* Add gitdocs integration

* Mess with title again [ci-skip]

* Add root readme back in

* Update docs/readme as a new readme

* Messing with title again

* Add where to get help [ci skip]

* Fix dev connect link [ci skip]

* Move how to get help [ci skip]

* Add TODO to empty headers

* Add more TODOs and clean up a link

* Add sloan

* Update prereqs to specify we use macOS

* Add gitdocs build to test on Netlify

* Update README [ci skip]

* Add .gitdocs_build/ to .gitignore [ci skip]

* Create netlify.toml

* Update docs with logo and more docs

* Update gitdocs name

* Add redirects for netlify

* Remove extraneous redirects from netlify

* Add more README TODOs [ci skip]

* Update root directory of gitdocs

* Move ISSUE_TEMPLATE to .github/ [ci skip]

* Testing new base for netlify

* Update README [ci skip]

* Rename index.md to readme.md for GitHub

* Move gitdocs.json to docs folder

* Add GPL LICENSE [ci skip]

* tweak readme

* update license language

* Update FAQ with some Q and A

* Add some traffic control for docs readme

* add license faq and core team members

* Add new line to fix list

* Add AGPL-3

Adding the GNU AFFERO GENERAL PUBLIC LICENSE.

* Update GPL License

* Additional documentation for PostgreSQL setup
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
diff --git a/.gitignore b/.gitignore
@@ -32,6 +32,7 @@ node_modules/
 /app/assets/javascripts/generated/*
 latest.dump
 .byebug_history
+.gitdocs_build/
 
 # Ignore application configuration
 /config/application.yml
diff --git a/LICENSE.md b/LICENSE.md
diff --git a/README.md b/README.md
diff --git a/docs/.gitdocs.json b/docs/.gitdocs.json
@@ -0,0 +1,17 @@
+{
+  "name": "dev.to Docs",
+  "root": "./",
+  "logo": "devblacksquarelogo.svg",
+  "header_links": [
+    {
+      "title": "Repo",
+      "href": "https://github.com/thepracticaldev/dev.to",
+      "target": "_blank"
+    },
+    {
+      "title": "dev.to",
+      "href": "https://dev.to",
+      "target": "_blank"
+    }
+  ]
+}
diff --git a/docs/.static/devblacksquarelogo.svg b/docs/.static/devblacksquarelogo.svg
@@ -0,0 +1 @@
+<svg version="1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 293 180"><path d="M81 1782 c-19 -9 -44 -30 -55 -45 -21 -28 -21 -35 -21 -837 0 -802 0 -809 21 -837 11 -15 36 -36 55 -45 32 -17 118 -18 1384 -18 1266 0 1352 1 1384 18 19 9 44 30 55 45 21 28 21 35 21 837 0 802 0 809 -21 837 -11 15 -36 36 -55 45 -32 17 -118 18 -1384 18 -1266 0 -1352 -1 -1384 -18z m814 -409 c50 -26 118 -98 142 -150 16 -34 18 -71 18 -348 0 -294 -1 -312 -21 -356 -31 -66 -78 -114 -142 -146 -56 -27 -61 -28 -259 -31 l-203 -4 0 532 0 531 213 -3 c195 -3 215 -5 252 -25z m795 -83 l0 -110 -165 0 -165 0 0 -100 0 -100 100 0 100 0 0 -110 0 -110 -100 0 -100 0 0 -100 0 -100 165 0 165 0 0 -110 0 -110 -225 0 c-248 0 -260 2 -309 60 l-26 32 0 434 c0 480 -1 476 63 514 29 18 52 20 265 20 l232 0 0 -110z m381 -194 c43 -164 80 -303 81 -308 2 -5 39 129 83 297 43 169 84 309 90 311 6 3 63 3 126 2 l116 -3 -123 -462 c-67 -253 -128 -472 -134 -485 -47 -90 -145 -132 -219 -94 -35 19 -83 73 -99 112 -6 16 -64 227 -128 468 -64 242 -118 446 -121 453 -4 11 18 13 123 11 l128 -3 77 -299z" transform="matrix(.1 0 0 -.1 0 180)"/><path d="M660 870 l0 -310 45 0 c52 0 99 21 115 49 6 12 10 116 10 266 l0 247 -29 29 c-26 25 -37 29 -85 29 l-56 0 0 -310z" transform="matrix(.1 0 0 -.1 0 180)"/></svg>
diff --git a/docs/additional_postgres_setup.md b/docs/additional_postgres_setup.md
@@ -0,0 +1,28 @@
+# Setup your application with PostgreSQL -
+Follow these links for detailed the installation guide.
+1. Mac OS - [setup](https://postgresapp.com/)
+2. Linux / Ubuntu -
+   - Ubuntu `14.04` - [setup](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-14-04)
+   - Ubuntu `16.04 and higher` - [setup](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-16-04)
+3. Windows - [setup](https://www.postgresql.org/download/windows/)
+
+##### You can find all installation packages for different operating systems [here](https://www.postgresql.org/download/).
+
+##### After installation -
+1. If your Rails app is unable to connect to the PostgreSQL, then update your `database.yml` file with `username` and `password`.
+```ruby
+development:
+    <<: *default
+    username: POSTGRESSQL_USERNAME
+    password: POSTGRESSQL_PASSWORD
+test:
+    <<: *default
+    username: POSTGRESSQL_USERNAME
+    password: POSTGRESSQL_PASSWORD
+```
+2. While running test cases, if you get an error message `postgresql connection timeout`. Go to your `spec/support/database_cleaner.rb` file. And rename `:truncation` with `:deletion`.
+
+##### Note -
+1. Don't forget to set up your PostgreSQL with `username` and `password`.
+2. Don't commit your `database.yml` or `database_cleaner.rb` files. Or PostgreSQL `username` and `password` to any repository.
+3. You can use environment variables for storing `username` and `password`. You can define them inside the `application.yml` file.
diff --git a/docs/faq.md b/docs/faq.md
@@ -0,0 +1,18 @@
+## 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.
+
+## I'm getting an error [ERROR-SOMETHING-WENT-WRONG]. 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.
+
+## How do I setup the repo with Windows/Linux/Ubuntu/not macOS?
+
+Unfortunately, the core team develops only macOS right now. We don't have guidelines for other operating systems yet. If you want to get up and running on a different OS, you'll need to have the following installed:
+
+- Ruby
+- Ruby on Rails
+- [PostgreSQL](https://www.postgresql.org/download/)
+- [Yarn](https://yarnpkg.com/en/docs/install)
+
+You can use a guide like [GoRails](https://gorails.com/setup/), but since we have not tried it ourselves we can't fully endorse it. Let us know how it goes, or if you have tips or experience setting all this up! We're open to including guides for other operating systems.
diff --git a/docs/frontend.md b/docs/frontend.md
@@ -0,0 +1,13 @@
+## ⚛ Front-End Development
+
+There is some legacy code which is old school JS, but for all things new, [Preact](https://preactjs.com) is the 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.
diff --git a/docs/get-api-keys-dev-env.md b/docs/get-api-keys-dev-env.md
@@ -0,0 +1,123 @@
+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:
+
+# Algolia (Choose OAuth or Email Sign Up)
+## Algolia: OAuth Sign Up
+1. [Click this link and sign up for an account with either GitHub or Google.](https://www.algolia.com/users/sign_up)
+![screen shot 2018-05-02 at 3 06 05 pm](https://user-images.githubusercontent.com/17884966/39547183-c5d8b572-4e24-11e8-80e3-5b595e0c9999.png)
+2. Select your region, and then hit "Let's get started!"
+![screen shot 2018-05-01 at 2 30 52 pm](https://user-images.githubusercontent.com/17884966/39544263-80c7e39e-4e1b-11e8-802e-c9562bdf1b63.png)
+3. Skip the tutorial (or don't) and go to your dashboard.
+![screen shot 2018-05-01 at 12 59 06 pm](https://user-images.githubusercontent.com/17884966/39544344-c8cc4496-4e1b-11e8-8d81-d570a48a0668.png)
+4. Click "Go to your dashboard".
+
+![screen shot 2018-05-02 at 3 45 34 pm](https://user-images.githubusercontent.com/17884966/39547238-f4ddd1ae-4e24-11e8-942b-98a01e20c632.png)
+
+5. Agree to Terms and Conditions.
+![screen shot 2018-05-02 at 3 45 49 pm](https://user-images.githubusercontent.com/17884966/39547258-05d347fa-4e25-11e8-9335-b65c72b846af.png)
+
+6. Click "API Keys" on the left navbar.
+
+![screen shot 2018-05-02 at 4 24 30 pm](https://user-images.githubusercontent.com/17884966/39547400-7cdb854c-4e25-11e8-8442-7cfc1dc8bc1e.png)
+
+7. Change your keys accordingly (name of Algolia key -> name of our application key): 
+* `Application ID -> ALGOLIASEARCH_APPLICATION_ID`
+* `Search-Only API Key -> ALGOLIASEARCH_SEARCH_ONLY_KEY`
+* `Admin API KEY -> ALGOLIASEARCH_API_KEY`
+
+![screen shot 2018-05-02 at 4 26 27 pm](https://user-images.githubusercontent.com/17884966/39547471-b24f2e36-4e25-11e8-9a0e-b988d6a8253f.png)
+
+8. Done!
+
+***
+***
+***
+
+## Algolia Email Sign Up
+1. [Click this link and sign up for an account with your email address.](https://www.algolia.com/users/sign_up)
+![screen shot 2018-05-02 at 4 30 52 pm](https://user-images.githubusercontent.com/17884966/39547712-5ff9d338-4e26-11e8-98e9-83852021ba90.png)
+
+2. Fill out your name and what describes you the most.
+![screen shot 2018-05-01 at 12 57 03 pm](https://user-images.githubusercontent.com/17884966/39547792-9a436842-4e26-11e8-9199-c320d24476fe.png)
+
+3. Choose your datacenter/region closest to you.
+![screen shot 2018-05-01 at 12 58 36 pm](https://user-images.githubusercontent.com/17884966/39548002-3f7d2640-4e27-11e8-8701-21820d852379.png)
+
+4. Skip the step asking about your project.
+![screen shot 2018-05-01 at 12 58 12 pm](https://user-images.githubusercontent.com/17884966/39547930-09b2af08-4e27-11e8-8c1b-d6b67d75d141.png)
+
+5. Complete the onboarding flow and click "Go to dashboard".
+![screen shot 2018-05-01 at 12 58 48 pm](https://user-images.githubusercontent.com/17884966/39548519-dc0491dc-4e28-11e8-90e2-be014acd0a66.png)
+
+6. Click "API Keys" on the left navbar.
+
+![screen shot 2018-05-02 at 4 24 30 pm](https://user-images.githubusercontent.com/17884966/39547400-7cdb854c-4e25-11e8-8442-7cfc1dc8bc1e.png)
+
+7. Change your keys accordingly (name of Algolia key -> name of our application key): 
+* `Application ID -> ALGOLIASEARCH_APPLICATION_ID`
+* `Search-Only API Key -> ALGOLIASEARCH_SEARCH_ONLY_KEY`
+* `Admin API KEY -> ALGOLIASEARCH_API_KEY`
+
+![screen shot 2018-05-02 at 4 26 27 pm](https://user-images.githubusercontent.com/17884966/39547471-b24f2e36-4e25-11e8-9a0e-b988d6a8253f.png)
+
+8. Done!
+
+That's it! You should try logging in with development, it should work. If it doesn't, let us know via an issue or in the contributors channel!
+
+### _The following are optional, but are probably things you'll run into. That said, if you're working on tests and other things, you shouldn't need these._
+
+### For authentication, you can choose Twitter, GitHub, or both.
+
+# Twitter App
+1. [Click this link and sign in/sign up for a Twitter account.]((https://apps.twitter.com)) Note that your Twitter account will need a phone number linked to it in order to create an app.
+2. Create a new app, and fill out the form, like the following example image: ![](https://user-images.githubusercontent.com/17884966/41612665-952d4cae-73c1-11e8-8047-cf0bd03bffb6.png)
+
+The only important field is the "Callback URL" `http://localhost:3000/users/auth/twitter/callback`, which redirects you properly to `localhost:3000` when signing in.
+
+3. Once done, go to your app's settings, and fill in the terms of service `http://dev.to/terms` and privacy policy URL `http://dev.to/privacy`:
+
+![](https://user-images.githubusercontent.com/17884966/41617044-8155387a-73cd-11e8-9e1d-f14c4652bda2.png)
+
+4. Once done, go to your app's permissions, and check the "Request email addresses from users" box.
+![screen shot 2018-05-02 at 5 02 48 pm](https://user-images.githubusercontent.com/17884966/39549184-f2e19952-4e2a-11e8-81ad-10e06c4e8a61.png)
+
+5. Change your keys accordingly: (name of Twitter key -> name of our application key):
+- `Access Token -> TWITTER_KEY`
+- `Access Token Secret -> TWITTER_SECRET`
+6. Done! 
+
+# GitHub
+1. [Click this link and sign in/sign up for a GitHub account.](https://github.com/settings/applications/new)
+2. Once signed in, create a new OAuth app. Here's an example; the URLs must match the example:
+![screen shot 2018-04-26 at 4 08 01 pm](https://user-images.githubusercontent.com/17884966/39329488-77cbf554-496c-11e8-941e-dd257b5223ee.png)
+3. Change your keys accordingly; (name of GitHub key -> name of our application key):
+- `Client ID -> GITHUB_KEY`
+- `Client Secret -> GITHUB_SECRET`
+4. Done!
+
+# Stream
+1. [Sign up for an account with this link](https://getstream.io/accounts/signup/), using either your email or GitHub.
+
+![stream step 1](https://user-images.githubusercontent.com/17884966/39548654-47db0f08-4e29-11e8-9cc3-c17d1b7228eb.png)
+
+2. Click "View Dashboard" at the top right corner.
+
+![stream step 2](https://user-images.githubusercontent.com/17884966/39548718-6f1928ca-4e29-11e8-9034-52ef1c1cc9d6.png)
+
+3. **In the next page, click "Add New Feed Group".**
+
+![stream step 3](https://user-images.githubusercontent.com/17884966/39548743-85bd4e44-4e29-11e8-9b6e-43567c4f7c22.png)
+
+<hr>
+
+4. Add a new feed group with the type "Notification" and name it `notifications` (case sensitive).
+
+![stream step 4](https://user-images.githubusercontent.com/17884966/39548890-f0ad7742-4e29-11e8-84a3-ed823e720052.png)
+
+5. Make sure you have a feed group with the type "Flat" and named `user` (case sensitive). You probably do, but if you don't, create one like you did with the notifications feed group.
+
+6. Change your keys accordingly: (name of Stream key -> name of our application key):
+  - `Key -> STREAM_RAILS_KEY`
+  - `Secret -> STREAM_RAILS_SECRET`
+  - `"https://us-east-api.stream-io-api.com/api/v1.0/" -> STREAM_URL`
+
+7. Done!
diff --git a/docs/helpful-hints.md b/docs/helpful-hints.md
@@ -0,0 +1,7 @@
+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`
+
diff --git a/docs/license-faq.md b/docs/license-faq.md
@@ -0,0 +1,17 @@
+### Where can I learn more about the AGPL-3 license?
+
+Please refer to the official “Why the Affero GPL” and the FAQ page on 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 CLA helps provide confidence to future users that 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.
+
+### What if I have other questions?
+
+Please check out our main repository or send an email to yo@dev.to.
diff --git a/docs/readme.md b/docs/readme.md
@@ -0,0 +1,21 @@
+---
+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: helpful-hints.md
+    title: Random Helpful Things
+  - path: faq.md
+    title: FAQ
+---
+# 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](faq), or ask for help in our [help thread on dev.to](#todo)!
diff --git a/docs/testing.md b/docs/testing.md
@@ -0,0 +1,37 @@
+# Testing
+
+We use the following testing tools:
+
+  * **RSpec** for testing the backend
+  * **Capybara** with **selenium-webdriver** for view testing
+  * **chromedriver-helper** for standard JS testing
+  * **guard-rspec** for automated testing
+  * [Jest](https://facebook.github.io/jest) for testing in the front-end
+  * [SimpleCov](link-to-simplecov-repo) for tracking overall test coverage
+
+Each pull request should come  with tests related to the newly written feature or bug fix. Ideally, we should test both the front end and back end.
+
+If you'd like to help us improve our test coverage, we recommend checking out our total coverage and writing tests for selected files based on SimpleCov's (more below) test coverage results.
+
+If you're new to writing tests in general or with Rails, we recommend reading about testing with Rails, RSpec, and Capybara first. For Webpack and 
+
+## 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 `[skip ci]` 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.
diff --git a/netlify.toml b/netlify.toml
@@ -0,0 +1,12 @@
+# Global settings applied to the whole site.  
+# 
+# “publish” is the directory to publish (relative to root of your repo),
+# “command” is your build command,
+# “base” is directory to change to before starting build. if you set base:
+#    that is where we will look for package.json/.nvmrc/etc not repo root!
+
+[build]
+  base = "docs/"
+[[redirects]]
+  from = "http://devto.netlify.com/*"
+  to = "https://docs.dev.to"
