You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+47-33Lines changed: 47 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,78 +5,92 @@ Below are few **rules, recommendations and best practices** we try to follow whe
5
5
## Paperwork
6
6
7
7
### Committer
8
+
8
9
* The **commit message**:
9
-
* must be written in the **imperative mood**
10
-
* must clearly **explain rationale** behind this change (describe _why_ you are doing the change rather than _what_ you are changing)
10
+
* must be written in the **imperative mood**
11
+
* must clearly **explain rationale** behind this change (describe _why_ you are doing the change rather than _what_
12
+
you are changing)
11
13
* The **pull request**:
12
-
* with non-trivial, non-dependencies change must be **[associated with an issue](https://help.github.com/articles/closing-issues-via-commit-messages/)**
14
+
* with non-trivial, non-dependencies change must be *
15
+
*[associated with an issue](https://help.github.com/articles/closing-issues-via-commit-messages/)**
13
16
* Add usage examples of new high level functionality to
*If you need also constants with `UriTemplate`, do not put them into DTOs not to drag Spring dependency into model module.
42
+
*If you need also constants with `UriTemplate`, do not put them into DTOs not to drag Spring dependency into model
43
+
module.
36
44
*Put _Jackson_ annotations on getters rather then on fields.
37
45
*Consider the **visibility**- use `package protected` when DTO is not intended forSDK user, but is needed
38
-
in related service.
46
+
in related service.
39
47
*Test all DTOs using _[JsonUnit](https://github.com/lukas-krecan/JsonUnit)_.
40
48
***Naming**:
41
-
* `Uri` for _URI string_ of some resource
42
-
* `Link` for structure containing at least _category_ (e.g. "self") and _URI string_
43
-
(can contain also others like _title_, _summary_, etc.)
49
+
* `Uri` for _URI string_ of some resource
50
+
* `Link` for structure containing at least _category_ (e.g. "self") and _URI string_
51
+
(can contain also others like _title_, _summary_, etc.)
44
52
45
53
### Enums
54
+
46
55
*Use enums sparingly, because they don't work with REST API changes (eg. new value added on the backend) **never use
47
-
them when deserializing**.
56
+
them when deserializing**.
48
57
* Where make sense, use overloaded methods with an enum argument as well as `String` argument.
49
58
50
59
### Services
60
+
51
61
* When programming client for some polling return [`FutureResult`](src/main/java/com/gooddata/FutureResult.java)
52
-
to enable user asynchronous call.
62
+
to enable user asynchronous call.
53
63
* Create custom [`GoodDataException`](src/main/java/com/gooddata/GoodDataException.java) when you feel the case
54
-
is specific enough.
64
+
is specific enough.
55
65
* Prefer DTOs to `String` or primitive arguments.
56
66
* **Method naming**:
57
-
* `get*()` when searching form single object (throw exception when no or multiple objects are found,
58
-
never return `null`)
59
-
* `find*()` when searching for multiple objects (collection of objects, never return `null`)
60
-
* `list*()` when listing whole or paged collection of objects (return collection or collection wrapped by DTO)
61
-
* `remove*()` (i.e. `remove(Project project)`) instead od `delete*()`
62
-
* In addition to unit tests, write also **integration tests** and **acceptance tests** if possible. See "What to test where" in "Best practices" below.
67
+
* `get*()` when searching form single object (throw exception when no or multiple objects are found,
68
+
never return `null`)
69
+
* `find*()` when searching for multiple objects (collection of objects, never return `null`)
70
+
* `list*()` when listing whole or paged collection of objects (return collection or collection wrapped by DTO)
71
+
* `remove*()` (i.e. `remove(Project project)`) instead od `delete*()`
72
+
* In addition to unit tests, write also **integration tests** and **acceptance tests** if possible. See "What to test
73
+
where" in "Best practices" below.
63
74
* Update [documentation](https://github.com/gooddata/gooddata-java/wiki/Code-Examples) with usage examples.
64
75
65
76
## Best practices
77
+
66
78
* **What to test where**:
67
-
* `*Test` = unit tests
68
-
* focus on verifying bussiness logic, corner cases, various input combinations, etc.
69
-
* avoid service tests using mocked `RestTemplate` - use integration tests with mocked API responses instead
70
-
* `*IT` = integration tests
71
-
* focus on verifying all possible outcomes of API calls
72
-
* see common ancestor [`AbstractGoodDataIT`](src/test/java/com/gooddata/AbstractGoodDataIT.java) setting up [Jadler](https://github.com/jadler-mocking/jadler/wiki) for API mocking
73
-
* `*AT` = acceptance tests
74
-
* focus on verifying the happy path against the real backend (so we're sure mocks in ITs are correct)
75
-
* see common ancestor [`AbstractGoodDataAT`](src/test/java/com/gooddata/AbstractGoodDataAT.java) setting up GoodData endpoint based on passed environment variables
79
+
* `*Test` = unit tests
80
+
* focus on verifying bussiness logic, corner cases, various input combinations, etc.
81
+
* avoid service tests using mocked `RestTemplate` - use integration tests with mocked API responses instead
82
+
* `*IT` = integration tests
83
+
* focus on verifying all possible outcomes of API calls
84
+
* see common ancestor [`AbstractGoodDataIT`](src/test/java/com/gooddata/AbstractGoodDataIT.java) setting
85
+
up [Jadler](https://github.com/jadler-mocking/jadler/wiki) for API mocking
86
+
* `*AT` = acceptance tests
87
+
* focus on verifying the happy path against the real backend (so we're sure mocks in ITs are correct)
88
+
* see common ancestor [`AbstractGoodDataAT`](src/test/java/com/gooddata/AbstractGoodDataAT.java) setting up
89
+
GoodData endpoint based on passed environment variables
76
90
*Everythingpublic should be **documented** using _javadoc_.
77
91
*When you need some **utility code**, look for handy utilities in used libraries first (e.g. _Spring_ has
78
-
its `StreamUtils`, `FileCopyUtils`, ...).When you decide to create new utility class,
79
-
use _abstract utility class pattern_.
92
+
its `StreamUtils`, `FileCopyUtils`, ...).When you decide to create new utility class,
0 commit comments