CONTRIBUTING.md

GoodData Java SDK - Contribution guide

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

Paperwork

Committer

• The commit message:
  • must be written in the imperative mood
  • must clearly explain rationale behind this change (describe why you are doing the change rather than what you are changing)
• The pull request:
  • with non-trivial change must be associated with an issue
• Add usage examples of new high level functionality to documentation.

Reviewer

Ensure pull request and issues are

• properly labeled (trivial/bug/enhancement/backward incompatible/...)
• marked with exactly one milestone version

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 URI string 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.
• Naming:
  • Uri for URI string of some resource
  • Link for structure containing at least category (e.g. "self") and URI string (can contain also others like title, summary, etc.)

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)
  • list*() when listing whole or paged collection of objects (return collection or collection wrapped by DTO)
  • 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:
  • *Test unit tests, but avoid service tests using mocked RestTemplate - use integration test
  • *IT integration tests (see AbstractGoodDataIT)
  • *AT acceptance tests
• 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.