Add documentation in migration guide, RestEasy 3.x does not allow same path in @Path annotation for sub resource method and sub resource locator.

Below is a class ProblemResource.java which has a sub-resource method and a sub-resource locator with the same path :

@POST
@Path("items")
public Response create(@MatrixParam("id") final UUID id, @QueryParam("msg") final String msg) {

........

@Path("items")
public ItemCollectionResource locateItems(@MatrixParam("pattern") final String pattern) {
System.out.println("Inside resource locator");

The request to http://localhost:8080/hello/problem/items fails with 405 in EAP 7.x.

Below are the test results :

EAP 6.4.14 (RestEasy 2.x) : works with the same PATH URI for sub-resource method as well as sub-resource locator:

curl --silent --ipv4 --noproxy '*' -H 'Accept: application/json' -D - 'http://localhost:8080/hello/problem/items'
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Tue, 25 Jul 2017 10:58:46 GMT

EAP 7.0.6 (RestEasy 3.x) : Does not work with the same PATH URI for sub-resource method and sub-resource locator:

curl --silent --ipv4 --noproxy '*' -H 'Accept: application/json' -D - 'http://localhost:8080/hello/problem/items'
HTTP/1.1 405 Method Not Allowed
Allow: POST, OPTIONS
Connection: keep-alive
X-Powered-By: Undertow/1
Server: JBoss-EAP/7
Content-Length: 0
Date: Tue, 25 Jul 2017 10:53:52 GMT

The http://localhost:8080/hello/problem/items request fails in EAP 7.x because it expects a POST request due to the ambiguous PATH URI.

Do we have some reference or a bug issue which introduced this change in RestEasy 3.x or a code so that we can include this information for the users who are using RestEasy 2.x and looking to migrate as a reference in our migration guide?

Business Impact : If there are huge number of applications deployed in JBoss, then for applications which need to be migrated from EAP 6 to 7, changes in application code always need to be done. Presently, RestEasy does not complain or log any warnings to the user. Is it possible to implement something in the code which implements or flags some messages to the users that they need to make the desired changes ?