Skip to content

Coding Guidelines in iTownsResearch

Jump to bottom
ilokhat edited this page Oct 17, 2019 · 3 revisions

iTowns is a JavaScript library that allows you to develop 3D geovisual applications in a web page.

Thus, developing an "itowns project" is creating a web application which uses the iTowns library.

This library exists in several versions :

  1. the GitHub repository in itownsResearch hosts the research prototype version of iTowns, support for the research and teachings of the GEOVIS team of the IGN LaSTIG

  2. the GitHub repository in "itowns" hosts the iTowns product, a production version developed by other IGN services. It is used to develop and put into production applications such as the 3D viewer of the "French Geoportail"

We always refer to the first one in this document

These repositories publish releases (in the form of minified JavaScript files) that can be used directly in a <script> tag of an HTML page. The "examples" directories contain minimalist examples demonstrating its main features, developed in this way.

For a more expert use, each branch/commit of these repositories can also be used as an npm dependency, when the client application uses npm to package its JavaScript code. This is the way it's done in this "petit tutoriel".

It should be noted that a branch tracking the production version of the library is available in the itownsResearch repository.

Creating an iTowns web application within the itownsResearch Organization

We assume you have the rights to create a repository in the iTownsResearch Organization.

In the root_directory of you project, create an ITOWNS_VERSION text file with information on which version of the library you're using. It will look like :

source: https://github.com/itownsResearch/itowns
branch: master
version/commit: v2.9.0-R

The project is based on a released version of the library

In this case, your ITOWNS_VERSION file resembles this :

source: https://github.com/itownsResearch/itowns
branch: master
version/commit: v2.9.0-R

  • You can grab the builds from the releases page.

  • If you want to use a more expert way of developing, by using npm, you'll have to build the dependency yourself as hinted in this wiki entry.

As an example, for the release v2.9.0-R the process would look like this:

  1. Checkout the specific version tag :
git checkout tags/v2.9.0-R
  1. Build it on your local filesystem :
imran@imran-XXX:~/path/to/itowns$ npm install && npm run prepublishOnly

Then, you can install the dependency in your project with :

imran@imran-XXX:~/path/to/my_project$ npm install /path/to/itowns

The project is based on a specific commit of the library, for example the current master not yet released.

Your ITOWNS_VERSION file shall resemble this :

source: https://github.com/itownsResearch/itowns
branch: my_branch
version/commit: 075013aSomeHashCommitd2e9f9b260d008f2241

You obviously can't grab anything ready, so you'll have to build it yourself in the same way we saw above.

You want to modify the library :

  • You should request write access to the iTownsResearch repository by asking an admin (@ilokhat, @nosy-b, @mbredif or @sidochristophe) to put you in the itowns_committers team
  • In your cloned repository, create your own branch. All your modifications will go there

For example, the process to create a branch based on the current master should be something like :

  1. Check that you're on the correct branch and it is is up to date :
imran@imran-XXX:~/path/to/local/itowns$ git status
Sur la branche master
Votre branche est à jour avec 'origin/master'.

rien à valider, la copie de travail est propre
imran@imran-XXX:~/path/to/local/itowns$ git pull
Déjà à jour.
  1. Create the branch on your local machine and switch to it :
imran@imran-XXX:~/path/to/local/itowns$ git checkout -b my_shiny_branch
Basculement sur la nouvelle branche 'my_shiny_branch'
  1. Push the branch on GitHub :
imran@imran-XXX:~/path/to/local/itowns$ git push origin my_shiny_branch 
...
 * [new branch]        my_shiny_branch -> my_shiny_branch

If the code is to be merged back, you'll open a pull-request : it will be merged by an admin after he reviews it.

You should read https://github.com/itownsResearch/itowns/blob/master/CONTRIBUTING.md

Clone this wiki locally