Skip to content

Latest commit

 

History

History
73 lines (62 loc) · 3.66 KB

CONTRIBUTING.md

File metadata and controls

73 lines (62 loc) · 3.66 KB

GoodData Java SDK - Contribution guide

Below are few rules, recommendations and best practices we try to follow when developing the GoodData Java SDK.

Paperwork

  • Every pull request with non-trivial change must be associated with an issue.
  • Every closed non-rejected pull request and issue must be marked with exactly one milestone version.
  • Issue must be properly labeled (bug/enhancement/backward incompatible/...).
  • Add usage examples of new high level functionality to documentation.

Design

Structure

  • Package names for DTOs and services should be named in the same manner as REST API.
  • Don't create single implementation interfaces for services.

DTOs

  • All DTOs which can be updated should be mutable. Please keep mutable only the fields which are subject of change, the rest should be immutable.
  • Create method named String getUri() to provide link to self.
  • Introduce constants:
public static final String URI = "/gdc/someresource/{resource-id}";
public static final UriTemplate TEMPLATE = new UriTemplate(URI);
  • Put Jackson annotations on getters rather then on fields.
  • Consider the visibility - use package protected when DTO is not intended for SDK user, but is needed in related service.
  • Test all DTOs using JsonUnit.

Enums

  • Use enums sparingly, because they don't work with REST API changes (eg. new value added on the backend) never use them when deserializing.
  • Where make sense, use overloaded methods with an enum argument as well as String argument.

Services

  • When programming client for some polling return FutureResult to enable user asynchronous call.
  • Create custom GoodDataException when you feel the case is specific enough.
  • Prefer DTOs to String or primitive arguments.
  • Method naming:
    • get*() when searching form single object (throw exception when no or multiple objects are found, never return null)
    • find*() when searching for multiple objects (collection of objects, never return null)
    • remove*() (i.e. remove(Project project)) instead od delete*()
  • Write integration tests for services using Jadler.
  • If it is possible write acceptance tests to be run with the real backend.
  • Update documentation with usage examples.

Best practices

  • Test class naming:
  • Everything public should be documented using javadoc.
  • When you need some utility code, look for handy utilities in used libraries first (e.g. Spring has its StreamUtils, FileCopyUtils, ...). When you decide to create new utility class, use abstract utility class pattern.

How-tos

Run acceptance tests

These tests have to be run against GoodData API, so one has to first set endpoint and credentials. It's being set by environment variables: host, login, pass, projectToken, warehouseToken. Tests can be then run by: mvn verify -Pat.

One can also use one-liner like this: host=... login=... pass=... projectToken=... warehouseToken=... mvn verify -Pat

One can also run only subset by specifying tests or groups to be run: mvn -Dgroups=featureFlag,project,account verify -Pat or mvn -Dit.test=FeatureFlagServiceAT,ProjectServiceAT,AccountServiceAT verify -Pat.