From 9c2666ca6e0f8837b32600862ab15387dd774060 Mon Sep 17 00:00:00 2001 From: Andrew Z Allen Date: Thu, 15 Feb 2018 19:53:06 -0700 Subject: [PATCH 1/4] Add a FAQ Fixes #525 --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 5d86a5addc5..91db11a24eb 100644 --- a/README.md +++ b/README.md @@ -239,6 +239,16 @@ But patch is welcome. # Contribution See [CONTRIBUTING.md](http://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md). +# FAQ + +> Why are the models in the swagger spec prefixed with the last bit of the proto package name? Is there a reason for this? I find this pretty ugly tbh and don’t see the advantage. + +The reason to generate the prefixes is that we don't have a guaranteed unique namespace. If two packages produce different Foo messages then we will have trouble. + +> Why not strip the prefix if it isn't necessary? + +I tried that, but the problem is that if you do that then when you add a message in that happens to conflict it will break code that is very far away from the code that changed. This is in an effort to adhere to the principle of least astonishment. + # License grpc-gateway is licensed under the BSD 3-Clause License. See [LICENSE.txt](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt) for more details. From e8efd6dff67b40d9b73324c4afc2c48587055886 Mon Sep 17 00:00:00 2001 From: Andrew Z Allen Date: Thu, 15 Feb 2018 19:54:51 -0700 Subject: [PATCH 2/4] Linkify POLA --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 91db11a24eb..380ae829af6 100644 --- a/README.md +++ b/README.md @@ -247,7 +247,7 @@ The reason to generate the prefixes is that we don't have a guaranteed unique na > Why not strip the prefix if it isn't necessary? -I tried that, but the problem is that if you do that then when you add a message in that happens to conflict it will break code that is very far away from the code that changed. This is in an effort to adhere to the principle of least astonishment. +I tried that, but the problem is that if you do that then when you add a message in that happens to conflict it will break code that is very far away from the code that changed. This is in an effort to adhere to the [principle of least astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment). # License grpc-gateway is licensed under the BSD 3-Clause License. From d81af4a3ed4b7c989c785f1178cecaf0bcca5ec9 Mon Sep 17 00:00:00 2001 From: Andrew Z Allen Date: Fri, 27 Apr 2018 16:27:34 -0600 Subject: [PATCH 3/4] Remove FAQ from README.md Moving it into its own file in the docs section --- README.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/README.md b/README.md index 380ae829af6..5d86a5addc5 100644 --- a/README.md +++ b/README.md @@ -239,16 +239,6 @@ But patch is welcome. # Contribution See [CONTRIBUTING.md](http://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md). -# FAQ - -> Why are the models in the swagger spec prefixed with the last bit of the proto package name? Is there a reason for this? I find this pretty ugly tbh and don’t see the advantage. - -The reason to generate the prefixes is that we don't have a guaranteed unique namespace. If two packages produce different Foo messages then we will have trouble. - -> Why not strip the prefix if it isn't necessary? - -I tried that, but the problem is that if you do that then when you add a message in that happens to conflict it will break code that is very far away from the code that changed. This is in an effort to adhere to the [principle of least astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment). - # License grpc-gateway is licensed under the BSD 3-Clause License. See [LICENSE.txt](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt) for more details. From 5589a821a9e5ee380627b7ac67dcecaa0cabe07e Mon Sep 17 00:00:00 2001 From: Andrew Z Allen Date: Fri, 27 Apr 2018 16:30:20 -0600 Subject: [PATCH 4/4] Address reviewer feedback --- docs/_docs/faq.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 docs/_docs/faq.md diff --git a/docs/_docs/faq.md b/docs/_docs/faq.md new file mode 100644 index 00000000000..45de82db0fa --- /dev/null +++ b/docs/_docs/faq.md @@ -0,0 +1,13 @@ +--- +category: documentation +--- + +# FAQ + +> Why are the models in the swagger specification prefixed with the last part of the proto package name? + +The reason to generate the prefixes is that we don't have a guaranteed unique namespace. If two packages produce different Foo messages then we will have trouble. + +> Why not strip the prefix? + +When a message is added which happens to conflict with another message (e.g. by importing a message with the same name from a different package) it will break code that is very far away from the code that changed. This is in an effort to adhere to the [principle of least astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment).