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: .github/CONTRIBUTING.md
+46-15Lines changed: 46 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -91,41 +91,63 @@ In most cases will you only update `{build}` and nothing else. If you're unsure
91
91
Please **do not change already existing since annotations**. This also includes adding ones to already existing methods/classes.
92
92
93
93
### Deprecated methods
94
+
> Please also see the [Deprecation Policy](#deprecation-policy) about how to handle deprecations
95
+
94
96
If you're deprecating a method will you need to add the `@Deprecated` annotation and also include a `@deprecated` tag in the comment explain why it was deprecated and mention possible replacements.
95
97
96
-
You also need to add the `@DeprecatedSince` annotation to indicate since when a method is deprecated. This annotation has a required version field and an optional replacements field.
97
-
You may also add the `@PlannedRemoval` annotation if the object is planned to be removed in a future release. This annotation has a required version field, which indicate in what version the object will be removed.
98
-
The specified version has to be at least 2 versions away from the one that the object got deprecated in (i.e. deprecating a method in `5.2.0` will require you to set the version to at least `5.2.2` in the `PlannedRemoval` annotation).
98
+
You also need to add the `@DeprecatedSince` annotation to indicate since when a method is deprecated. This annotation has the fields `major`, `minor`, `patch` and `replacement` from which the last one is optional.
99
+
You may also add the `@PlannedRemoval` annotation if the object is planned to be removed in a future release. This annotation has a `major`, `minor` and `patch` field to mark the version for when the object is removed.
100
+
101
+
### CheckUtil
102
+
JavaBotBlockAPI has a CheckUtil with some static void methods for checking various things such as if a String is empty.
103
+
104
+
When using any methods of the CheckUtil should you add the following text to the Javadoc comment as its own Paragraph:
105
+
```java
106
+
/**
107
+
* <p>Following Exceptions can be thrown from the {@link org.botblock.javabotblockapi.core.CheckUtil CheckUtil}:
108
+
* <ul>
109
+
* <li>{@link java.lang.NullPointerException NullPointerException} - Mention the cause here.</li>
110
+
* <li>{@link java.lang.IllegalStateException IllegalStateException} - Mention the cause here.</li>
111
+
* </ul>
112
+
*/
113
+
```
114
+
115
+
The CheckUtil has the following methods which can have the mentioned Excpetions:
116
+
117
+
-`ChekUtil#notEmpty(String value, String name)` - Checks the String "value" is empty and throws a NullPointerException with the message `name + " may not be empty."` in such a case.
118
+
-`CheckUtil#notEmpty(Map<?, ?> value, String name)` - Checks if the Map "value" is empty and throws a NullPointerException with the message `name + " may not be empty."` in such a case.
119
+
-`CheckUtil#condition(boolean expression, String message)` - Checks if the boolean "expression" returns true and throws a IllegalStateException with the message `message`.
99
120
100
121
### Other Styling
101
122
Please make sure that all text is on the same vertical line (block).
102
123
This means that when f.e. a `@return` is used, that you have to use two spaces after `@param` instead of one.
103
124
104
125
### Order of the parts
105
-
Here is an example of the different parts being used:
126
+
Here is an example of using the different parts together:
106
127
```java
107
128
/**
108
129
* Adds "Bar" to the provided text.
109
130
* <br>Will throw an error when not providing text.
131
+
*
132
+
* <p>Following Exceptions can be thrown from the {@link org.botblock.javabotblockapi.core.CheckUtil CheckUtil}:
133
+
* <ul>
134
+
* <li>{@link java.lang.NullPointerException NullPointerException} - When foo is empty.</li>
135
+
* </ul>
110
136
*
111
137
* @param foo
112
138
* The text that should get "Bar" added to it.
113
139
*
114
140
* @return The provided String with "Bar" added to it.
115
141
*
116
-
* @throws IllegalArgumentException
117
-
* When the provided String is empty/null.
118
-
*
119
-
* @since v1.0.0
142
+
* @since 1.0.0
120
143
*
121
144
* @deprecated Use {@link #getFooBar() getFooBar()} instead.
122
145
*/
123
146
@Deprecated
124
-
@DeprecatedSince(version="1.0.0", replacements= {"#getFooBar"}) // If you deprecate a method, add this one too.
125
-
@PlannedRemoval(version="1.0.2") // When the objects gets removed in the future, add this annotation.
thrownewIllegalArgumentException("foo may not be empty");
147
+
@DeprecatedSince(major=1, minor=0, patch=0, replacements= {"#getFooBar"}) // If you deprecate a method, add this one too.
148
+
@PlannedRemoval(major=1, minor=0, patch=2)
149
+
publicString getFooBar(@NonnullString foo){
150
+
CheckUtil.notEmpty(foo, "Foo");
129
151
130
152
return foo +"Bar";
131
153
}
@@ -135,14 +157,23 @@ public String getFooBar(String foo) throws IllegalArgumentException{
135
157
*
136
158
* @return {@code "foobar"}
137
159
*
138
-
* @sincev1.0.1
160
+
* @since 1.0.1
139
161
*/
140
162
publicString getFooBar(){
141
163
return"foobar";
142
164
}
143
165
```
144
166
167
+
## Deprecation Policy
168
+
To not fully break the Wrapper on each release do we follow a general deprecation policy, to give people time to move to any replacement method, if available.
169
+
170
+
If possible should always a replacement method, field or other object be provided when deprecating an object.
171
+
Any deprecated method is also planned for removal which is indicated by the `@PlannedRemoval` annotation. The version you define there has to be at least two patch-versions from the one the object became deprecated.
172
+
This means that deprecating a method in `6.2.0` results in the major, minor and patch version of the annotation to display `6`, `2` and `2` respectively.
173
+
174
+
At **no point** should an object just be removed. We always mark it as deprecated first and give the aforementioned minimal delay for people to update, before removing it completely.
175
+
145
176
## [Code of Conduct]
146
177
We want to give everyone a chance to contribute to the project.
147
-
So please keep your comments and messages nice. Every message that is considered rasist, insulting or similar will be removed.
178
+
So please keep your comments and messages nice. Every message that is considered racist, insulting or similar will be removed.
148
179
If you continue to send those messages will we permanently remove you from this repository.
0 commit comments