Skip to content

Contributing Guideline

Jump to bottom
Johann Levesque edited this page Jan 7, 2021 · 14 revisions

This guide is intended for JavaScript developers who are interested in contributing to the Canadian Geospatial Platform Viewer code base. You should be comfortable with the source control tool named Git, have an account on GitHub, and possess some basic experience with npm and node.

Tools

Below is a list of the software you'll need to download and install before continuing:

  • A source code editor. We use Visual Studio Code with these extension (Prettier, ESLint and Better Comment), but feel free to use one you're most comfortable with.
  • Git

A version control system (VCS) for tracking changes in computer files and coordinating work on those files among multiple people.

  • Node.js v12.13.0+ supported, v15.5.1 current

Node.js® is a JavaScript runtime built on Chrome's V8 JavaScript engine. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient. Node.js' package ecosystem, npm, is the largest ecosystem of open source libraries in the world.

Local Setup

Let's fork the GeoView repo and setup a working local copy.

Fork the project

Login to your https://github.com account and navigate to https://github.com/Canadian-Geospatial-Platform/GeoView. On this page click on the "Fork" button near the top right corner and follow the on screen prompts to have your own copy of GeoView.

Setup forked repository

Now that you have a forked copy of the repo, it is time to set it up on your local machine. Run the following commands in terminal, git bash, or wherever Git and Node are available:

Clone the forked repo

git clone [email protected]:[GITHUB USERNAME]/fgpv-vpgf.git LOCAL/REPO/PATH
cd LOCAL/REPO/PATH

Replace [GITHUB USERNAME] with your github username and LOCAL/REPO/PATH to wherever you'd like to save a copy of the forked repo on your local system. Git will create this path for you if it does not exist.

Add remotes

git remote add upstream https://github.com/Canadian-Geospatial-Platform/GeoView.git

To make sure you are properly setup, check if both remote are ok

git remote -v

You should see

origin  https://github.com/[GITHUB USERNAME]/GeoView (fetch)
origin  https://github.com/[GITHUB USERNAME]/GeoView (push)
upstream        https://github.com/Canadian-Geospatial-Platform/GeoView (fetch)
upstream        https://github.com/Canadian-Geospatial-Platform/GeoView (push)

You'll be pulling changes from upstream, but pushing to origin.

Fetch origin + upstream branches & tags

git fetch --all

Checkout + npm install

git checkout -b BRANCH upstream/UPSTREAM-BRANCH
npm install

Replace BRANCH with the name you want to create locally and UPSTREAM-BRANCH to whatever branch/tag you'd like to start working with. It will be typically develop.

Run locally

To run the modifications done to the code base do the following:

npm run serve

Open your browser then navigate to http://localhost:8080 to see the viewer in action.

Meta Documentation

We are using jsdoc notation for documenting the viewer library.

Documentation blocks for jsdoc should start with /** and generally follow the javadoc format and markup style:

/**
 * Main function description.
 * @function functionName
 * @return {Object} random variable
 */

Documenting Functions

Javascript allows functions to be defined in a variety of ways. In the context of a service or directive the function will automatically be linked as long as the @module tag is declared on the top level item.

Function Sample

        /**
         * Add RCS config layers to configuration after startup has finished
         * @function rcsAddKeys
         * @param {Array}  keys    list of keys marking which layers to retrieve
         * @return {Promise} promise of full config nodes for newly added layers
         */
  • @functioncan be omitted for @class contexts, the parser is smart enough to figure that out, @function should be used everywhere else
  • for Promise, describe the type which it will resolve with
  • @private can be used to document functions which are not exposed by the service, directive or class being documented

Commits

Commit message format Each commit message consists of a header and a footer. The header has a special format that includes a type, scope and subject:

<type>(<scope>): <subject>
<footer>

Any line of the commit message cannot be longer 100 characters. This allows the message to be easier to read on github as well as in various git tools.

Type Must be one of the following:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • refactor: A code change that neither fixes a bug or adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Scope The scope could be anything specifying place of the commit change. For example UI, geoSearch, plugin, API, etc...

Subject The subject contains succinct description of the change.

Footer The footer is the place to reference GitHub issues that this commit Closes (e.g. Closes #11).

Translations

The viewer can support multiple languages. We currently support both English and French. Use this guide to understand how to add, remove, or change language translations as well as how to use these translations in your code.

We use the i18next localization library.

Translations files

The translations file is located in /public/locales/language/translation.json. This file contains the translations for the specified language (en-CA or fr-CA)for every viewer component. The file structure is a JSON object with a translation key and a value.

Translation key is string identifier that we'll use later in this guide to tell the translation service to fetch this particular translation. It contains no spaces or special characters. We can create nested object to organize translations into groupings.

Here is a sample translation for en-CA:

{
    "mapnav": {
        "fullscreen": "Full Screen",
        "home": "Home",
        "zoomIn": "Zoom in",
        "zoomOut": "zoom out"
    },
    "mapctrl": {
        "mouseposition": {
            "east": "E",
            "west": "W",
            "north": "N",
            "south": "S"
        }
    }
}

Each files needs to have the same key hierarchy to make sure translation is applied properly.

Updating a language

Find the line in /public/locales/language/translation.json that contains the translation you want to change and make the modifications needed for each languages.

Using translations

You should refer to the i18next localization library documentation for a complete guide. Here we'll go through the most useful use cases:

  • Import the useTranslation to your file import { useTranslation } from 'react-i18next';
  • Create the translation object const { t } = useTranslation();
  • Call the object with the proper key
    • Directly inside JavaScript
       const myValue = t('mapctrl.mouseposition.north')
    • Inside HTML object
       <ButtonGroup orientation="vertical" aria-label={t('mapnav.ariaNavbar')} variant="contained">

This object will return the appropriate key value for the language selected by the user.

Contributing Guide

Clone this wiki locally