Merge pull request #403 from onaio/staging

Gisida 1.3.1

.babelrc

@@ -1,7 +1,6 @@
 {
     "presets": [
-        "es2015",
-        "es2016",
+        "env",
         "stage-0"
     ],
     "retainLines": true

.circleci/config.yml

@@ -1,27 +1,41 @@
 version: 2
+commands:
+  early_return_for_forked_pull_requests:
+    description: >-
+      If this build is from a fork, stop executing the current job and return success.
+      This is useful to avoid steps that will fail due to missing credentials.
+    steps:
+      - run:
+          name: Early return if this build is from a forked PR
+          command: |
+            if [ -n "$CIRCLE_PR_NUMBER" ]; then
+              echo "Nothing to do for forked PRs, so marking this step successful"
+              circleci step halt
+            fi
 jobs:
   build:
     working_directory: ~/gisida
     docker:
       - image: circleci/node:6.11.5
     steps:
       - checkout
-      - run: 
+      - run:
           name: Install dependencies
-          command: yarn install
+          command: yarn install --ignore-engines
       - run:
           name: Run eslint
           command: npm run lint
-      - run: 
+      - run:
           name: Run jest
           command: npm test
   publish:
     docker:
       - image: circleci/node:6.11.5
     steps:
+      - early_return_for_forked_pull_requests
       - checkout
       - run: echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" >> ~/.npmrc
-      - run: yarn install
+      - run: yarn install --ignore-engines
       - run: yarn build
       - run: npm publish
 workflows:
@@ -37,4 +51,3 @@ workflows:
               only: /[0-9]+(\.[0-9]+)*/
             tags:
               only: /v[0-9]+(\.[0-9]+)*/
-

.eslintignore

@@ -0,0 +1,3 @@
+# ignore test folder
+
+test/*

.eslintrc

@@ -1,18 +1,18 @@
 {
   "env": {
-    "browser": true
+    "browser": true,
+    "jest": true
   },
-  "extends": "airbnb",
+  "extends": ["airbnb", "prettier"],
   "parserOptions": {
     "ecmaFeatures": {
       "experimentalObjectRestSpread": true,
       "jsx": true
     },
     "sourceType": "module"
   },
-  "rules": {
-
-  },
+  "plugins": ["prettier"],
+  "rules": {},
   "parser": "babel-eslint",
   "globals": {
     "mapboxgl": true,

.gitignore

@@ -6,4 +6,5 @@ npm-debug.log
 *.iml
 coverage/
 dist/
+build
 yarn-error.log

.prettierrc

@@ -0,0 +1,6 @@
+{
+  "printWidth": 100,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "arrowParens": "avoid"
+}

README.md

@@ -74,7 +74,7 @@ $ npm install gisida
 ### 2. Import and initializing the store.
 
 ```javascript
-import { initStore } from "gisida";
+import { initStore } from 'gisida';
 
 const store = initStore();
 ```
@@ -301,40 +301,28 @@ $ git clone git@github.com:onaio/gisida.git
 $ npm develop
 ```
 
-### Production build
-
-- Build production distribution
+- Run tests
 
 ```
-$ npm build
+$ npm test
 ```
 
-- Publish to npm
+- Run tests and generate coverage report
 
 ```
-$ npm publish
+$ npm run test:coverage
 ```
 
-### Releases
-
-1. Check https://github.com/onaio/gisida/releases to see what the next release version number should be, i.e. if the last release is `0.0.7` the next should be `0.0.8` depending on the Semantic Versioning guide, refer to (https://semver.org/).
-
-2. Create branch for new version being released, `git checkout -b <version-number>`
-
-```
-$ git checkout -b 0.0.8
-```
+### Production build
 
-3. Run `npm version <version-number>`. This creates a commit and updates version number in package.json.
+- Build production distribution
 
 ```
-$ npm version 0.0.8
+$ npm build
 ```
 
-4. Push release branch to Github and tag `git push -u --follow-tags origin <version-number>` e.g
+- Publish to npm
 
 ```
-$ git push -u --follow-tags origin 0.0.8
+$ npm publish
 ```
-
-5. Merge release to master once it passes review

docs/README.md

@@ -0,0 +1,70 @@
+# Gisida Docs
+
+This directory contains documentation on Gisida, Gisida React, and Gisida Clients best practices, protocols, and procedures.
+
+- [New Project Checklist](new-project-checklist.md)
+- [Getting Started with Gisida](getting-started.md)
+
+## Contributing
+
+Gisida and Gisida React repositories use the following branches:
+
+- `master` containing the latest versioned code published to npm
+- `staging` containing the latest code in development
+- `<feature branch>` containing new code as it is being developed
+
+### Feature Branches
+
+When developing new code, from new features to bug fixes to refactors, this work is do done in a feature branch. Ideally, each feature branch should:
+
+1. be branched off of `staging`
+2. contain code-changes specific to a specific work item
+3. have a Pull Request
+4. be merged into `staging`
+
+### Pull Requests
+
+Pull Requests (PRs) should be opened as soon as progress has been made on a feature branch, this is for the sake of transparency and collaboration. PRs must include the following before merging:
+
+1. A reference to the Github issue ([preferably with keywords](https://help.github.com/en/enterprise/2.18/user/managing-your-work-on-github/closing-issues-using-keywords))
+2. A **summary** of what is included in the PR (bullets are fine)
+3. Up-to-date code from `staging` / `master`
+4. **Tests** for new code and for existing code effected by your changes
+5. **Passing Tests** on CircleCI
+6. **Documentation** for new features and for existing features effected by your changes
+7. **Approval** via PR reviews
+
+### Tests and Documentation
+
+There will be times when adding tests and documentation will be a stand-alone task, this is fine and should not often block PRs. In these cases, start with basic tests/docs and simply create a new ticket describing the tests/docs still needed and reference these new tickets in the PR.
+
+### Code Reviews
+
+When your code is ready for feedback request Reviews from at least two engineers, and alert them to your request via Slack (or verbally). Reviewers are able to Approve, Request Changes, or simply comment on the PR. If there are changes requested which you feel do not belong in the PR, simply respond in the PR and make sure the requested changes are documented in a ticket before dismissing the review. At least one Approval is required before merging.
+
+## Versioning
+
+Gisida and Gisida React use [Semantic Versioning](https://semver.org/) schema, a few examples might be:
+
+- `v2.0.0` A **major** release which is incompatible with prior releases
+- `v1.4.0` A **minor** release which is compatible with prior minor releases
+- `v1.2.23` A **patch** release which are small / backward-compatible code releases
+- `v1.4.0-rc.1` A **release candidate** pre-release which are useful for deploying releases for QA before publishing the new release to npm
+- `v1.2.3-reveal.1` A **tagged** release which may or may standardized and included in future releases (we try not to do this but can be useful in a time-crunch)
+
+_Note: Release candidates and tagged releases are the only time releases should be made from feature branches._
+
+### Release Process
+
+All major, minor, and patch releases should be tagged from `staging`, release candidate and tagged releases may use feature branches. When tagging and publishing a new release, take the following steps:
+
+1. Merge your feature branch to `staging`
+2. Go to the [Github Releases page](https://github.com/onaio/gisida/releases) and click `Draft a new release`
+3. Name the Tag version according to the Semantic Versioning described above
+4. Select `staging` for the Target branch
+5. Use the Tag version as the Release title
+6. Include in the description a list of all merged PRs since the last release
+7. Click Publish release
+8. Merge `staging` into `master`
+9. Publish the release by locally running: `git fetch --tags origin && npm login && npm publish --tag=<version>`
+10. Verify the release was published to npm

docs/getting-started.md

@@ -0,0 +1,39 @@
+# Getting Started with Gisida
+
+## Implementation
+
+Using the [gisida](https://github.com/onaio/gisida) and [gisida-react](https://github.com/onaio/gisida-react) libraries to create new dashboards is as simple as installing, importing, and initializing Gisida components and stores. Doing this in a [Create React App](https://github.com/facebook/create-react-app) project is recommended.
+
+### Install
+
+```
+npx create-react-app my-gisida-app && cd my-gisida-app
+yarn add gisida gisida-react
+yarn start
+```
+
+### Import
+
+```
+import { initStore } from 'gisida';
+import { App, Map, Menu } from 'gisida-react';
+```
+
+### Initialize
+
+```
+const store = initStore();
+ReactDOM.render((
+  <Provider store={store}>
+    <App>
+      <Map mapId="map-1">
+        <Menu />
+      </Map>
+    </App>
+  </Provider>
+));
+```
+
+## Configuration
+
+Initializing the app's redux store via the `gisida.initStore()` method requires both site-level and layer-level configuration files. By default, the application requires a `public/config/site-config.json` to initialize the Map and load `public/config/layers/*.json` configurations.

docs/new-project-checklist.md

@@ -0,0 +1,39 @@
+# New Project Checklist
+
+Before starting a new Gisida project there are a few requirements to have in mind and on hand:
+
+1. Project name
+2. Site title
+3. Logo (optional)
+4. Geometries
+5. Data
+6. Layers and Sections
+7. Security and Passwords (optional)
+
+### Project name
+
+This should be a simple yet descriptive name for the project. This will be used as the name of your new repository so it should be all lowercase letters and no spaces.
+
+### Site title
+
+This title will be displayed as the name of the webpage and should be human readable.
+
+### Logo (optional)
+
+By default the gisida-react TitleBar component will render a logo image based on the value of `APP.appIcon` from the site-config file. All image types supported by major browsers acceptable and square logos are highly recommended.
+
+### Geometries
+
+Rendering Gisida maps requires valid geometries in order to plot marks, these geometries are most commonly administrative boundaries and collections of points. Currently we support GEOJSON and Mapbox Tilesets as valid geometry sources; GEOJSON can be used to generate Tilesets and Shapefiles can be used to manually generate GEOJSON.
+
+### Data
+
+Data can come in many formats from many sources and is required to encode / visualize information and render more than simple line and symbol layers. Often data will be included in the geometries, and additional / supplemental data can be loaded and joined to specific geometric features.
+
+### Layers and Sections
+
+Knowing which geometries and which data need to be displayed is the first step in configuring layers and rendering a menu with nestable groups of layers.
+
+### Security and Passwords
+
+Gisida supports a basic password configuration, as well as an oAuth2 option for authorizing Ona Data and Canopy (Superset) integrations.

docs/setting-up-new-project

@@ -0,0 +1,18 @@
+# Setting Up Client Dashboard
+
+The following steps allow you to build a gisida dashboard that runs off [gisida](https://github.com/onaio/gisida) and [gisida-react](https://github.com/onaio/gisida-react):
+
+## Sourcing Geodata
+
+Gisida uses [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/api/), which expects a collection of gis data that form the background setting for a map called a basemap. We can use existing basemaps from mapbox or create a custom basemap, we should then add the URL to the client's repository so we can render a basic map.
+
+Once we have the basemap configured we will need to build basic boundaries and infrastructure layers. These layers can be gathered from various sources including but not limited to [hdx](https://data.humdata.org/)
+we can build these layers from the following sources:
+#### Shapefiles
+This file requires conversion into GeoJSON file. We can use [qgis](https://qgis.org/en/site/) to do this conversion or use online alternatives to achieve the same. 
+
+#### GeoJSON
+This file can be loaded locally or uploaded to mapbox. We encourage uploading these files to mapbox considering their sizes. Mapbox determines the zoom extents for the uploaded GeoJSON which may fail to meet our expectations. To determine zoom extents we use [tippecanoe](https://github.com/mapbox/tippecanoe) which makes it possible to set the zoom extents. This conversion outputs a [mbtile](https://docs.mapbox.com/help/glossary/mbtiles/) which can be uploaded to mapbox and loaded from the client's repository.
+
+## Setting Up Client Repository
+We encourage private repositories for clients since we have proprietary resources on these repositories. This repo should hold a bundle file that runs off latest versions of gisida and gisida-react respectively. This repository houses client site-config, data directory and custom components. A more detailed documentation on this can be found [here](https://github.com/onaio/gisida/blob/staging/docs/getting-started.md).