an extensible, consistent and logical directory hierarchy for the examples

I don't disagree, but some of the reasons for the current directory structure: 1) separating examples with different dependencies and 2) letting users copy-paste the examples (because lots of people try to copy-paste).

links, fixed typos/grammar

This is not actionable. Were there specific things that you saw that needing resolving?

dependency on released version: the current master (SNAPSHOT) version of examples depends on master (SNAPSHOT) version of the grpc library. Can we change it to depend on the latest released grpc version so the user who just wants to build examples doesn't need to build the grpc library?

No. We want to add examples as we add features and want to make sure we don't break the examples. Our documentation says to check out the latest tagged release.

The one possibility here is to have nightly/continuous snapshot builds that the examples could use.

an extensible, consistent and logical directory hierarchy for the examples

I don't disagree, but some of the reasons for the current directory structure: 1) separating examples with different dependencies and 2) letting users copy-paste the examples (because lots of people try to copy-paste).

There are examples under examples/src/main/java/io/grpc/examples/ and then there are sub- directories for other examples under examples/ (android/, example-alts/ and so on). I don't know if that's by design, and whether that structure can be changed to make it more intuitive or consistent.

links, fixed typos/grammar

This is not actionable. Were there specific things that you saw that needing resolving?

You are right - I have seen stuff (text in readme files) that can be corrected but I should list it to make it actionable or open a PR to fix them myself. Will try to do that.

dependency on released version: the current master (SNAPSHOT) version of examples depends on master (SNAPSHOT) version of the grpc library. Can we change it to depend on the latest released grpc version so the user who just wants to build examples doesn't need to build the grpc library?

No. We want to add examples as we add features and want to make sure we don't break the examples. Our documentation says to check out the latest tagged release.

Yes, the doc does say that but people might be interested in the latest examples e.g. stuff added since the latest tagged release. Also I thought there is almost always a delay between when a new feature is added to the grpc library and when the example using that feature is added. But if both are added together then I agree the current mechanism is needed.

The one possibility here is to have nightly/continuous snapshot builds that the examples could use.

That is a great idea and can address the problem as well.

and then there are sub- directories for other examples under examples/ (android/, example-alts/ and so on)

Each of those have different dependencies (e.g., Android, ALTS).

Yes, the doc does say that but people might be interested in the latest examples e.g. stuff added since the latest tagged release.

Where does it say that? If it encourages using master, that should be changed.

Also I thought there is almost always a delay between when a new feature is added to the grpc library and when the example using that feature is added.

We do update the examples at the same time when we deprecate an API or introduce a direct replacement for an existing API. While I agree new examples aren't written often, existing examples are updated immediately when appropriate.

Yes, the doc does say that but people might be interested in the latest examples e.g. stuff added since the latest tagged release.

Where does it say that? If it encourages using master, that should be changed.

I meant to say the doc does mention using latest release tag (and not master).

We do update the examples at the same time when we deprecate an API or introduce a direct replacement for an existing API. While I agree new examples aren't written often, existing examples are updated immediately when appropriate.

One can imagine developers using examples as the starting point for writing new gRPC applications and then going on to build their apps for production. In that case it is best for that starting point (i.e. examples) to be based on released gRPC code instead of SNAPSHOT. But that's just my (not so strong) opinion.

I meant to say the doc does mention using latest release tag (and not master).

I'm sorry. I see now I misread what you said.

One can imagine developers using examples as the starting point for writing new gRPC applications and then going on to build their apps for production. In that case it is best for that starting point (i.e. examples) to be based on released gRPC code instead of SNAPSHOT. But that's just my (not so strong) opinion.

In that case we don't want them to use the un-released examples. They would need to wait for a gRPC release to use any recently-added features and if we add something and then delete it within a release they will be trying to use something that "never existed."

If users check out master and expect to use the examples, then that means we can't update examples until immediately preceding the release, which is far too prohibitive. The other option is we could move the examples into a separate repository. Although that would make them less likely to be updated, in my opinion.