Skip to content

Latest commit

 

History

History
727 lines (511 loc) · 22.9 KB

CONTRIBUTING.md

File metadata and controls

727 lines (511 loc) · 22.9 KB

Developer Guide

The Mapbender team welcomes contributions from all members - so you are welcome to join us in the development!

Third-party patches are essential for the preservation of high standards in Mapbender.

We simply cannot access the huge number of platforms and myriad configurations that run Mapbender.

We want it as easy as possible to carry out changes to get the modules in your environment to run.

Therefore, we provide a few guidelines as an overview for contributors to Mapbender.

Architecture

Mapbender is based on a Symfony framework and uses composer to manage external and internal libraries as own modules.

Installation

Preparing system

To get started with the development you need a PHP interpreter and some additional libraries.

Preparing Ubuntu 16.04

sudo apt-get install php7.0 php7.0-xml php7.0-mbstring php7.0-pgsql php7.0-gd php7.0-curl php7.0-cli php7.0-sqlite php7.0-intl php7.0-json sqlite curl openssl

Preparing Ubuntu 14.04

Activate universe repoisitory:

sudo add-apt-repository universe

Update package list:

sudo apt-get update

Install php interpreter and modules:

sudo apt-get install php5 php5-xml php5-mbstring php5-pgsql php5-gd php5-curl php5-cli php5-sqlite php5-intl sqlite curl openssl

Cloning project source

via SSH

git clone [email protected]:mapbender/mapbender-starter.git mapbender-starter

or

via HTTP

git clone https://github.com/mapbender/mapbender-starter.git mapbender-starter

Switch to project directory

cd mapbender-starter

Run bootstrap script

Running the bootstrap script takes some time to get the required libraries and to prepare the project configurations. Bootstrap saves Mapbender starter configurations in a application/app/db/demo.sqlite configuration file. After that, a SQLite testing database is created. In the end, the script starts an integrated webserver in your terminal. For more on that, check start webserver. Symfony configurations are located under application/app/config.

sh bootstrap

Start web-server

app/console server:run

After executing the command run, your console describes how you can view web application in your browser:

Server running on http://localhost:8000

Open the displayed URL from your console output message in your favorite browser.

For development reasons, it is recommended to use Chromium (Chrome) or Firefox.

If you want to log in, you have to use the standard combination (name: root / pw: root). Please change these patterns if you want a secure access.

To stop the server from running, just press ctrl-C or close your console.

That's it!

The developer installation is only useful for solo development purposes and should be optimized for production or co-working systems.

Modules

Module is a new part of the Mapbender concept, based on Symfony modularity rules and composer dependency manager.

Special builds can be created that exclude subsets of Mapbender functionality.

This allows smaller custom builds when the builder is certain that those parts of Mapbender are not being used.

For example, it is possible to create an application which only uses map view and did not need Digitizer functionality.

Future Mapbender releases may be able to exclude any additional modules apart from the core application.

In the past, the development bundles were part of the git submodules.

Today, each module should be in its own git repository and reuse the same directory structure.

Rules

It's very important to follow enclosed rules:

Each module is:

Each module should have:

  • only one bundle
  • only one primary namespace
  • identical structure
  • own license file
  • own function description README file
  • own CONTRIBUTING.md that describes how other developers should install, setup and contribute in it
  • own tests relevant to new features, elements or functionality

Write your code using PSR-2, a coding style guide standard.

Bundles

A bundle is a set of functionality (similar to a library) which can be created and used outside of the Mapbender. The goal of the Bundle is to restrict the usage of global name spaces and optionally switch, swap and extend the Mapbender functionality.

Bundle structure

A Bundle contains a special set of folders and files:

  • Command/ - Contains commands. Read more about commands [here] (http://symfony.com/doc/current/components/console/introduction.html#creating-a-basic-command)
  • Controllers/ - Contains controllers in other words public API's.
  • Component/ - Contains components in other words services, this contains business logic in classes. The components are used by controllers or other components.
  • DataFixtures/ - Fixtures are used to load a controlled set of data into a database. This data can be used for testing or could be the initial data required for the application to run smoothly.
  • DependencyInjection/ - Contains only one file, this makes components in magical way available as services, if they are registred in Resources/config/services.xml bundle folder.
  • Documents/ - Contains documents related to the bundle. MD for text and PUML for charts formats are preferred.
  • Exception/ - Contains exceptions.
  • Element/ - Contains Mapbender elements. This folder isn't symfony conform.
  • Element/Type - Contains Mapbender elements administration types/forms.
  • Entity/ - Contains entities.
  • EventListener/ - Contains event listeners.
  • Resources/config/ - Contains configurations.
  • Resources/public/ - Contains web resources (CSS, JS, images).
  • Resources/views/ - Contains twig and php templates.
  • Resources/translations/ - Contains translations.
  • Template/ - Contains mapbender templates.
  • Tests/ - Contains PHPUnit and functional tests.
  • composer.json - Describes the bundle as composer package/library. Example
  • LICENSE - Contains LICENSE text.
  • README.md - Contains README text.
  • CONTRIBUTING.md - Contains CONTRIBUTING text.
  • MapbenderNameBundle.php - Bundle description file, this registers and makes available bundle elements, templates, manager controllers and layers register.

Read more about best practices for reusable bundles here.

Bundle creation

Create a git repository outside of Mapbender, as your own project.

cd ~/Projects
mkdir new-awesome-bundle
cd new-awesome-bundle
git init

In order to create a bundle, please take a look at the bundle structure.

Don't forget to follow module rules!

Create bundle description class

Bundles can contains Templates, Elements, [Roles], administration manager menu items or ACL classes. Bundle class file describes which Templates, Elements or ACL classes are delivered and available for the bundle. The name of bundle description file should contain full name of bundle and class name like this: MapbenderMapbenderNameBundle.php

Description class should extend the MapbenderBundle class

Register bundle components

Methods available to rewrite from MapbenderBundle:

  • getElements - Should return a list of element classes provided by the bundle. Each entry in the array should have a fully qualified class name. See source for an example.
  • getTemplates - List of template classes provided by bundle. Each entry in the array is a fully qualified class name. See source for an example.
  • getManagerControllers - List of controllers to be embedded into administration manager interface. The list must be an array of arrays, each giving the integer weight, name, route and array of route prefixes to match against. See source for an example.
  • getACLClasses - List ACL bundle classes. See source for an example.
  • getRoles - List bundle roles. The list must be an array with
    • name: String, must start with ROLE_, e.g. ROLE_USER_ADMIN
    • title: String, human readable, e.g. "Can administrate users"
    • @return array roles. See source example.

Create composer package

Create a composer.json as described in the example.

Dont forget to fill it up:

  • authors - Is required in order to know the technical director of the modules.
  • name - Unique name of the module. You can check the existens by composer packagist service.
  • license - license short name.
  • description - Describes the module.
  • autoload - [psr-4] Path to the namespace classes to load them correctly.
  • target-dir - Path where bundle root should be placed in.

Better if autoload and target-dir will be copied from example as is, so only bundle names should be changed.

{
    "name": "mapbender/new-awesome-bundle",
    "description": "New awesome bundle description",
    "keywords": ["mapbender","awesome","geo"],
    "type": "library",
    "license": "MIT",
    "authors": [
        {"name": "Andriy Oblivantsev"}
    ],
    "require": {
        "php": ">=5.3.3",
        "imag/ldap": "2.x"
    },
    "autoload": {
		"psr-4": {"Mapbender\\NewAwesomeBundle": "."}
    },
    "target-dir": "Mapbender/NewAwesomeBundle",
    "extra": {
        "branch-alias": {
            "dev-master": "1.0-dev"
        }
    }
}

More about composer definition here.

Save bundle

Versioning

To learn about semantic versioning please read the documentation here.

Create version

git tag 0.0.1

List versions

git tag -l

Push version

git push --tags

Register bundle

Switch to mapbender project directory.

Register new git repository as composer bundle/module in composer.json.

Example:

{
    "require-dev": {
        "mapbender/new-awesome-bundle": "dev-master"
    },
    "require": {
        "mapbender/new-awesome-bundle": "*"
    },
    "repositories": [
        {"type": "git","url": "https://github.com/mapbender/new-awesome-bundle.git"}
    ]
}

Update composer after add new module

../composer.phar update -o

Switch to module directory

cd vendor/mapbender/new-awesome-bundle/Mapbender/NewAwesomeBundle/

This is a normal git repository, bundle and composer package at the same time.

Now you are ready to change and commit code directly in the project.

To get involved, please look at digitizer structure as example.

Submodules

Nice ability to get bundles and modules linked with each other!

Please stop develop this way!

This workflow is deprecated.

This approach has been used a long time to develop and distribute Mapbender, but due to the course complexity and many changes in diverse bundles, located in different sub-modules, without versioning, we decided to change the development workflow to composer packages named as modules.

Elements

Definition

Mapbender elements are an optional part of each bundle and should be stored under SomeBundle/SomeElementName folder.

Each Mapbender element is:

Each Mapbender element has its own:

Creation

Generate a new element by giving:

  • name of bundle
  • name of new element
  • source directory, relative to application folder, where the bundle is stored
app/console mapbender:generate:element "Mapbender\DigitizerBundle" MyNewElement vendor/mapbender/digitizer

Now there are new files located in the bundle folder. For more information read the full tutorial.

In order to introduce our new element and to show it by adding a new element, it should be registered in the main bundle file in "getElements" method, located in the root folder of the bundle.

Example:

  • Bundle file: Mapbender/DigitizerBundle/MapbenderDigitizerBundle.php
...
class MapbenderDigitizerBundle extends MapbenderBundle
{
    public function getElements()
    {
        return array(
            'Mapbender\DigitizerBundle\Element\MyNewElement'
        );
    }
}

Templates

  • Fullscreen - is the main template. This should be used for a desktop based application.

  • Mapbender mobile template - is the current mobile template. This is in development and can be used for simple tasks. Use it at your own risk.

  • Classic template - is deprecated. This template shouldn't be used. The only reason why it's still in the list is for backwards capability of Mapbender 3.0.x based projects.

  • Responsive - isn't ready and shouldn't be used. This template is just a playground for future development and for new templates. Use it at your own risk.

Styling

Application template styling can be done by using the CSS tab in the backend for adding your own style sheets.

CSS/SCSS text will be parsed to use on top of the application it's stored for.

Creation

A template is a part of the bundle. It's located in the "Templates/" directory.

  • Create new template PHP-Class in "Template" directory
  • Extend Mapbender template by:
    • "Mapbender/CoreBundle/Component/Fullscreen" for desktop application
    • "Mapbender/MobileBundle/Template/Mobile" for mobile application

Example:

class NewTemplate extends Mapbender\CoreBundle\Component\Template{
}
  • override public methods pass your needs
  • register template in bundle register file "AcmeBundle.php", this is located in bundle root folder
    public function getTemplates()
    {
        return array('Mapbender\AcmeBundle\Template\NewTemplate');
    }
  • remove the cache

Now your template should be avaible. You can use it by creating a new application and choose it in the template list.

Translations

Read more about translations.

To get unique named translations, use a bundle name prefix before subject.

Example

      <trans-unit id="9728e3887eb78b1169723e59697f00b9" resname="somebundle.dialog.button.add">
        <source>somebundle.dialog.button.add</source>
        <target>Add</target>
      </trans-unit>

Generate translations

By using TWIG files, a implemented generator can transform any used translation automatically in 'xlf' files.

Therefore, these few parameters must be submitted:

  • --output-format= - Format of generated translation file. It's important to use [xlf].
  • --force - Force append new translations to existing translation files
  • Language - Language short name (de/en/ru)
  • BundleName - Name of bundle

Example

app/console translation:update --output-format=xlf --force de MapbenderCoreBundle

Feature branch

It's mandatory to use the "feature/" prefix in the branch name.

Example:

  • Create branch:
cd mapbender
git checkout -b "feature/mega-cool-feature-x"
  • Improve the code.
  • Save changes:
git add *
git commit -m "Add some new stuff"
  • Merge current release code:
git fetch -a
git merge "release/3.0.6"
  • If conflicts arise, resolve them.
  • Run tests.
  • Push the changes on github:
git push

Then just wait for our feedback. We will check it out and review your code to merge it in the branch. Thanks!

Bug fix branch

It's mandatory to use the "hotfix/" prefix in your branch name.

Example:

  • Create branch:
cd mapbender
git checkout -b "hotfix/bug-short-description"
  • Improve the code.
  • Save changes:
git add *
git commit -m "Fix bug description"
  • Merge current release code:
git fetch -a
git merge "release/3.0.6"
  • If conflicts arise, resolve them.
  • Run or add new tests relevant to the fixed bug.
  • Push the changes on github:
git push

Then just wait for our feedback. We will check it out, test and review your code to merge it in the branch. Thanks!

Release branch

This branch can only be changed by a project maintainer. It's mandatory to use release/ prefix in your branch name.

Example:

  • Checkout release branch:
cd mapbender
git checkout "release/3.0.6"
  • Fetch changes:
git fetch -a
git pull
  • Merge changes:
git merge "hotfix/bug-short-description"
  • If conflicts arise, resolve them.
  • Run or add new tests relevant to the new feature.
  • Review the code.
  • Run tests.
  • Save changes:
git commit -m "Merge 'hotfix/bug-short-description'"
git push

Building packages

There are special composer commands for distributing and building packages:

  • bin/composer build Command to build a package with the following optional parameters:
    • [tar.gz|zip] - Optional parameter that defines the package file format. The default configuration is defined in composer.json as config/archive-format.
    • [dist-name] - Optional parameter that defines the package file name prefix. The default configuration is defined in composer.json as name, a vendor name will be ignored.
    • [dist-version] - Optional parameter that defines the package version. This is included as suffix in the package name. The default configuration is defined in composer.json as version.

You can define the composer distributing path in composer.json as config/archive-dir. The default location is the dist folder located in root of the project.

Build package example

You can build and distribute an articat to dist/test-distribution.1.0.1.tar.gz by running:

bin/composer build zip test-distribution 1.0.1

Building linux tarball-file

bin/composer build tar.gz

Tests

Don't forget to write tests! Moreover, please write a clear commit message. Here are some good explanations:

Examples

bin/phpunit -c app vendor/mapbender
bin/phpunit -c app vendor/mapbender/digitizer
bin/phpunit -c app vendor/mapbender/digitizer/Mapbender/DigitizerBundle/Tests/FeaturesTest.php

Resources

Modules

  • Mapbender - Contains Core, Manager, Print, Mobile and some other bundles this will be extracted as modules in next releases.
  • FOM - Friends of Mapbender contains Administration and Security components bundles. The module is deprecated and will be split in new modules as optional parts of Mapbender3.
  • OWS Proxy - Secure communicate remote hosts through Mapbender3 backend.
  • Digitizer - Digitalizing bundle, which contains geometry services.
  • DataStore - DataStore bundle, which contains data drivers and services.

Libraries