Skip to content

Latest commit

 

History

History
611 lines (441 loc) · 20.6 KB

CONTRIBUTING.md

File metadata and controls

611 lines (441 loc) · 20.6 KB
Raw

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.

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

Install package with active source control

I.e. you want to install an optional package in a form that allows you to branch it and run arbitrary git commands on it.

composer require --prefer-source mapbender/awesome-optional-package:dev-master@dev

Note: the dev-master is a special type of "version" recognized by composer as a branch name. The @dev relaxes stability requirements so you can directly install, in this case, the latest commit on the master branch. With default "stable" stability, you could only install proper tagged release versions.

This essentially clones the git repository into vendor/mapbender/awesome-optional-package, instead of just extracting a prepackaged zip archive containing the files.

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.

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