Add docs about architecture and testing

.gitignore

@@ -31,7 +31,4 @@ _backup
 package-lock.json
 
 # Webpack monitor files
-monitor/
-
-# WIP
-docs
+monitor/

docs/about/about.md

@@ -0,0 +1,77 @@
+[Best of JavaScript](https://bestof.js.org) is a web application that gathers the latest trends about the web development landscape:
+
+* JavaScript, on both front-end and back-end sides
+* HTML
+* CSS
+
+It tracks open-source projects related to the web technologies and provides detailed stats on their popularity.
+
+Find the best components, tools, frameworks to build amazing applications!
+
+## Why _Best of JavaScript_
+
+JavaScript is everywhere, we are going full speed on innovation but it's hard to keep track of the changes.
+
+[Best of JavaScript](https://bestof.js.org) was created to answer the following questions:
+
+* What are the trends over the last days, weeks, months...?
+* Which is the big thing coming next? GraphQL? Vue.JS?
+* What are the best tools to handle a given task?
+
+## Features
+
+### Today _hot_ projects
+
+Check everyday the 10 hottest projects of the day... data is updated every day!
+
+![image](https://user-images.githubusercontent.com/5546996/31574102-20eba92a-b103-11e7-96f3-0ff6ac02e1bc.png)
+
+### Tags
+
+Projects are classified under 130 _tags_ such as :
+
+* _UI Framework_: solutions to build apps in the browser (React, VueJS, Angular...)
+* _Testing_: tools for automated testing
+* _Chart_: libraries to visualize data
+* _Learning_: the best resources to learn web development, for beginner and advanced users
+* And many others!
+
+![image](https://user-images.githubusercontent.com/5546996/31999416-17c4711e-b9ce-11e7-9cfb-960711299cc9.png)
+
+## Trending
+
+For any tag, users can check the trends over a given period of time:
+
+* one day
+* one week
+* one month
+
+![image](https://user-images.githubusercontent.com/5546996/31573972-a2f372a2-b100-11e7-910e-8f9724cc8edf.png)
+
+### Search engine
+
+Enter any keyword and get instant results from a list of more than 1000 projects tracked by _Best of JavaScript_
+
+### The JavaScript Hall of Fame
+
+Visit the [JavaScript Hall of Fame](https://bestof.js.org/hall-of-fame) to meet the most important members of the JavaScript community:
+
+* Speakers
+* Authors
+* Developers (TJ, Sindre...)
+
+## How it works
+
+At its core [Best of JavaScript](https://bestof.js.org) is a **curated** list of more than 1000 projects related to the web technologies.
+
+The number of stars on GitHub is the main metrics used to assess project's popularity: the application tracks the evolution of stars over days, weeks and months.
+
+The application also gathers data about project's *activity* (commits, contributors) and Npm *dependencies*.
+
+
+## Community driven!
+
+* Users can request new projects to add by submitting issues to a GitHub repository.
+* Users can request people to add to the _Hall of Fame_
+* Users can contribute by adding _reviews_ and _links_ related to the projects tracked by the application.
+* It's open source, anyone can contribute!

docs/about/detailed-description-1000.md

@@ -0,0 +1,12 @@
+JavaScript is everywhere, we are going full speed on innovation but it's hard to keep track of the changes.
+
+_Best of JavaScript_ was created to answer the following questions:
+
+* What are the trends over the last days, weeks, months...?
+* What are the best tools to handle a given task?
+
+At its core the application [Best of JavaScript](https://bestof.js.org) a **curated** list of more than 1000 projects related to the web technologies: JavaScript (front-end and back-end), HTML, CSS.
+
+Projects are classified under _tags_ such as : _React_, _UI Framework_,  _Testing_, _Chart_, ...
+
+The number of stars on GitHub is the main metrics used to assess project's popularity but it also gathers data about project's *activity* (commits, contributors) and NPM *dependencies*.

docs/about/short-description-500.md

@@ -0,0 +1,10 @@
+[Best of JavaScript](https://bestof.js.org) is a web application that gathers the latest trends about:
+
+* JavaScript, on both front-end (React, Vue.JS...) and back-end sides (node.js)
+* HTML
+* CSS
+
+It tracks a curated list of more than 1000 open-source projects, providing detailed stats on their popularity, based on GitHub stars.
+
+It helps developers finding the best components, tools, frameworks to build amazing applications.
+Data is updated from GitHub every day.

docs/architecture.md

@@ -0,0 +1,64 @@
+# Architecture - Date Flow
+
+The application is made with `create-react-app` and uses `redux` to manage the state.
+
+## Flow
+
+- The app starts => dispatch `FETCH_PROJECTS` action and call `fetchProjectsFromAPI` to get data from the API
+- Ajax request https://bestofjs-api-v2.firebaseapp.com/projects.json => +150KB gzipped (527KB)
+- Dispatch `FETCH_PROJECTS_SUCCESS` action
+- The reducer updates `entities` object, creating the 2 objects `projects` and `tags`, that are indexed by id.
+
+## Shape of the Redux store
+
+```js
+{
+  entities: {
+    projects: {
+      react: {
+        full_name: 'facebook/react',
+        repository: 'https://github.com/facebook/react',
+        slug: 'react',
+        tags: ['framework', 'vdom', 'react'],
+        deltas: [93, 90, 121, 104, 99, 48, 48],
+        description:
+          'A declarative, efficient, and flexible JavaScript library for building user interfaces.',
+        name: 'React',
+        pushed_at: '2018-07-14T02:21:52.000Z',
+        stars: 106289,
+        url: 'https://reactjs.org',
+        npm: 'react',
+        version: '16.4.1',
+        dependency_count: 4,
+        contributor_count: 1198,
+        owner_id: 69631,
+        stats: {
+          total: 106289,
+          daily: 93,
+          weekly: 86.1,
+          monthly: 268,
+          quaterly: 143,
+          yearly: 97
+        },
+        monthly: [70891, 78351, 85584, 93417, 95613, 98250, 106289],
+        icon: 'react.svg'
+      }
+    },
+    tags: {
+      framework: {
+        name: 'UI Framework',
+        description: 'Libraries and frameworks to build UI interfaces in the browser',
+        code: 'framework',
+        id: 'framework'
+      }
+    },
+    links: {},
+    reviews: {},
+    heroes: {},
+    meta: {
+      pending: false,
+      lastUpdate: '2018-07-14T12:48:34.028Z'
+    }
+  }
+}
+```

docs/testing.md

@@ -0,0 +1,75 @@
+# Testing the pages with `react-testing-library`
+
+We follow the approach described in [this article](https://blog.kentcdodds.com/introducing-the-react-testing-library-e3a274307e65), trying to test the pages the way the real users interact with the page, rather than testing the component implementation details.
+
+Instead of checking React elements or DOM elements, we target page elements the end-user can see, using:
+
+- `getByText`
+- `getByLabelText` (to target an input element by its label)
+
+## Goal
+
+We want to check that all pages visited by the end-user render correctly (at least without throwing an error!)
+
+All pages top level components, defined inside `src/pages/` folder, should have a test written in `XxxxPage.test.js` file.
+
+```
+src
+├── pages
+│   ├── AboutPage
+│   │   ├── AboutPage.test.js
+│   │   └── index.js
+│   ├── HomePage
+│   │   ├── HomePage.test.js
+│   │   ├── index.js
+```
+
+## Strategy
+
+We use `renderApp` function (from `src/test/render-app.js`) to render the application in "test" mode, mocking some dependencies, specifying the "route" we want to visit.
+
+```js
+it('Should render the `About` page', async () => {
+  const { getByText } = renderApp({ route: '/about' })
+  await wait(() => getByText('Why Best of JavaScript ?'))
+})
+```
+
+Note: we have to "wait" for the element because we use code splitting to load some page bundles on-demand (including the "About" page), therefore we have to wait for the JavaScript bundle related to the page.
+
+`renderApp` method will return an object that includes properties provided by `react-testing-library`, plus some properties we added for convenience:
+
+- `mainNode`: the `<main>` container for the page content
+- `history`: the object used to navigate through routes
+
+```js
+const { container, getByText, debug, mainNode } = renderApp({
+  route: '/tags/react'
+})
+```
+
+## Tips
+
+Note: `react-testing-library` relies on `dom-testing-library`.
+
+For example, `getByText(text)`, provided by the render method, is a shortcut for the method with the same name, provided by `dom-testing-library`:
+
+```js
+import { getByText } from 'dom-testing-library'
+getByText(container, text)
+```
+
+`debug` function will print the HTML code of the whole page.
+
+To print the content of given HTML element, use `prettyDOM`
+
+```
+import { prettyDOM } from 'react-testing-library'
+console.log(prettyDOM(mainNode))
+```
+
+## About performances
+
+Tests are pretty slow, it takes time to render the application every time we call `renderApp` (around 1 second?).
+
+To navigate through pages, we can call `history.push(route)`... but this is almost as slow!

src/components/home/Home.js

@@ -15,7 +15,7 @@ import News from './News'
 const date = new Date(2018, 5, 18)
 
 const Home = props => {
-  log('Render the <Home> component', props)
+  log('Render the <Home> component')
   const { isLoggedin, pending, authActions, popularTags } = props
   return (
     <MainContent>

src/pages/HomePage/index.js

@@ -9,7 +9,7 @@ import * as uiActionCreators from '../../actions/uiActions'
 
 class HomePage extends Component {
   render() {
-    log('Render the <HomePage> container', this.props)
+    log('Render the <HomePage> container')
     const {
       hotProjects,
       auth,