-
Notifications
You must be signed in to change notification settings - Fork 34
Contributing Guideline
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.
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.
Let's fork the GeoView repo and setup a working local copy.
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.
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.
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).
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.