contributor_guide

Contributor Guide

This article provides an overview the Nasdanika Server and different ways to contribute. It also provides short descriptions of bundles, bundle groups and features constituting the product, as well as overviews of related projects.

Vision

The vision of Nasdanika Server to be an enabler of fast development of server-side applications which utilize complex domain models and are built leveraging Domain-Driven Design principles.

Core principles

Declarative development - higher level abstraction, focus on the business problem instead of low-level plumbing:
- ECore and Java metadata and annotations.
- Helper models.
- Code generation.
Automated build:
- Maven/Tycho.
- Jenkins/CircleCI or similar solutions.
- Docker images.
Self-describing applications - the documentation system is part of the application
- Bunldes, components, services and their relationships. Visualizations - auto-generated UML diagrams.
- ECore models documentation with visualizations by auto-generated UML diagrams.
- Help topics.

Overview

Nasdanika Server is a collection of bundles which facilitate building of server (particularly Web) OSGi/Equinox-based applications which use Eclipse EMF CDO for application domain objects persistence and utilize rich metadata provided by CDO/ECore and Java language as well as helper models and code generators to build such applications in a declarative fashion which isolates the developer from low-level details and thus allows to focus on the business problem.

Nasdanika Server based applications are self-contained Eclipse products which can also be packaged as Docker images.

Nasdanika Workspace Wizard generates initial plug-in projects for the application with Maven nature and pom.xml files, ready to be built with Maven/Tycho. The wizard also generates a Docker file. This allows developers to quickly set up automated builds with tools like Jenkins or build hosting providers like CircleCI.

How to contribute

There are multiple ways how you can contribute to Nasdanika Server development:

Get the word out

If you use Nasdanika Server and can show that its value comparing to other approaches, you can let the world know about your experience by writing blog posts or articles.

You can also build examples, write tutorials, and record videos about different aspects of the Nasdanika Server, e.g. how to build a WebSocket based web application.

Once you publish blog/article/example/tutorial/video, share a link with us by creating a issue, and we will publish the link on the Wiki.

Report bugs

If you find a bug, please create an issue. It is highly recommended to provide code to reproduce the bug! If you provide the code in a form of JUnit test, its even better as it may be later incorporated into the suite of automated tests.

Code contributions

There are also several ways to contribute to the codebase. As an open source project we use the Fork and Pull Model. You can find more information about collaborative development at GitHub in this article - Collaborating with issues and pull requests.

When you contribute code, please make sure that the changes are clearly identifiable. In particular, avoid making non-functional changes in the code which you do not touch, e.g. auto-formatting of the entire compilation unit.

Write automated tests

At this point of time testing of Nasdanika bundles is manual. You can contribute by writing automated tests. In OSGi/Equinox tests are placed in fragment projects. You can use Core Tests as a template.

Write JavaDoc

We strive to make code self-descriptive, but if you find a place where it is not self-descriptive enough you can provide clarifications. Also, if you've written an example, a tutorial, or an article about a particular class or package, you can add links and/or code fragments to the JavaDoc.

Please keep in mind that Nasdanika Server uses Pegdown Doclet and therefore JavaDocs shall be written in markdown.

Fix a bug

If you find a bug and know how to fix it - go for it!

Implement new functionality

Sections below provide brief descriptions of bundles constituting Nasdanika Server, including bundle roadmaps. You may pick an item from a roadmap and implement it.

Bundles

!!! WORK IN PROGRESS !!!

CDO

cdo

cdo.boxing

cdo.feature

cdo.h2

cdo.scheduler

CDO Security

cdo.security

cdo.security.edit
cdo.security.editor
cdo.security.feature

cdo.web

cdo.web.doc

cdo.xa

core

core.tests

equinox.feature

feature

Function

function

function.cdo

cdo.function

html

html.feature

osgi.model

parent

Promise

promise

promise.cdo

cdo.promise

provisioning

provisioning.feature
repository

SCA

cdo.sca

cdo.sca.edit

sca

sca.design

sca.edit

sca.editor

sca.feature

server.jetty.feature

service-stopper

Story

story
story.edit
story.editor
story.feature

Tools ?

tools.design
tools.feature

transaction

web

WebTest

webtest
webtest.feature
webtest.model
webtest.model.routes
webtest.performance
webtest.performance.feature