Skip to content

Latest commit

 

History

History
233 lines (157 loc) · 5.2 KB

developer-guide.md

File metadata and controls

233 lines (157 loc) · 5.2 KB
Raw

Developer Guide

This document provides information for developers working on ngeo.

Pre-commit

To activate the pre-commit run:

pip install pre-commit
pre-commit install --allow-missing-config

Don't worry about the time take on the first run

Careful: If the pre-commit fail the commit will be aborted.

Commit without pre-commit

git commit (-n|--no-verify)

More information on pre-commit.

Run our code

Type make help to display available targets.

Code structure

We have 3 repositories with sources code:

  • src: this folder contains the major part of source code.
  • srcapi: this folder contains the source code which we offer a more stable API.
  • api: this folder contains the JavaScript API of the project.

Publish examples to GitHub Pages

Let's say you're working on a new feature in a specific branch and want to publish examples to show others what that new feature's UI looks like. The Makefile provides a gh-pages target for exactly this.

To publish the current branch's examples to GitHub Pages:

make gh-pages GITHUB_USERNAME=<your_github_username>

The GITHUB_USERNAME variable is used to specify the user/organization name to publish to on GitHub.

For example

make gh-pages GITHUB_USERNAME=camptocamp

Will publish the examples to https://camptocamp.github.io/ngeo/<branchname>/.

The published examples use the ngeo.js standalone build.

Simple example.

Unit tests

Writing tests

The unit tests are located in test/spec/ and uses the Jasmine Framework. Please refer to the AngularJS's unit-testing guide for how to write unit tests.

Running tests

To run the unit tests on the command line, just run make test. All the tests will be run inside PhantomJS.

Running tests in debug mode

For debugging purposes it is useful to run the unit tests in an actual browser with make test-debug. This task starts the Karma server and opens Chrome/Chromium. Click on Debug to open a new page that runs all unit tests. Now you can start the debugger.

To run only a single test or test group, use fdescribe or fit to focus on a test:

fdescribe('...', function() {

  fit('...', function() {

Create a package on npm

Checkout the latest version

git checkout <release-branch>
git fetch origin
git reset --hard origin/<release-branch>

Where <release-branch> stand for 2.x.

Verify that the <version> (2.x.x) in package.json match with the tag you'll create. Then create a tag named the same as the version.

git tag <version>
git push origin <version>

GitHub Actions will create a new package on npm.

If you create a new release, bump version in the package.json file:

git checkout -b bump
vi package.json
git add package.json
git commit -m "Bump version to <version + 1>"
git push origin bump

Do the pull request on branch <release-branche>

Create a new stabilization branch

When we create a new stabilization branch we should also duplicate the localization.

Go on master:

git checkout master
git pull origin master

Create the new branch:

git checkout -b x.y

Update the .github/workflows/main.yaml:

     env:
-      MAIN_BRANCH: master
+      MAIN_BRANCH: 'x.y'

In the GitHub project settings deactivate the 'Status' Rule.

Commit and push the changes:

git add .github/workflows/main.yaml
git commit -m "Update the branch"
git push origin x.y

In the GitHub project settings reactivate the 'Status' Rule.

Back on master:

git checkout master

Get the actual localization:

make transifex-get

Update the Makefile:

- MAJOR_VERSION ?= x.y
- DEMO_BRANCH ?= prod-x-y
+ MAJOR_VERSION ?= x.y+1
+ DEMO_BRANCH ?= prod-x-y+1

Update the package.json:

-  "version": "x.y.0",
+  "version": "x.y+1.0",

Update the SECURITY.md:

| x.y+1 | To be defined |

Note: when you do the release you should define date or the version x.y to now + 18 months for a standard release, and now + 36 months for an LTS release.

Create the label backport x.y.

Commit and push the changes:

NEXT_VERSION=x.y+1
git add package.json Makefile SECURITY.md
git checkout -b "start-${NEXT_VERSION}"
git commit -m "Start the version ${NEXT_VERSION}"
git push origin "start-${NEXT_VERSION}"

Create a pull request from the new branch.

Login to transifex:

echo "[https://www.transifex.com]" > ~/.transifexrc
echo "api_hostname  = https://api.transifex.com" >> ~/.transifexrc
echo "rest_hostname = https://rest.api.transifex.com" >> ~/.transifexrc
echo "hostname = https://www.transifex.com" >> ~/.transifexrc
echo "username = $(gopass show gs/ci/transifex/rw/username)" >> ~/.transifexrc
echo "password = $(gopass show gs/ci/transifex/rw/password)" >> ~/.transifexrc
echo "token = $(gopass show gs/ci/transifex/rw/token)" >> ~/.transifexrc

Create the new localization resource:

make transifex-init

Update the references in the index.html file of the gh-pages branch.