Move examples within bazelbuild/bazel into bazelbuild/examples repository

[limdor]

There is already a folder with bazel examples inside the bazel repository
https://github.com/bazelbuild/bazel/tree/master/examples

It would be good to add in the readme a reference to it and a small sentence explaining what is the difference or why they are separated. It would be nice in the future to have them in a single place and not have them splited between this repo and the bazelbuild/bazel repo.

[aiuto]

We should deprecate examples within bazelbuild/bazel in favor of bazelbuild/examples.
The biggest problem with examples in the bazel repo is that we don't want to have examples that depend on repos beyond what is needed to build bazel. That artifically limits us.

We don't need an explanation. We just need to

• move them to bazelbuild/examples
• provide a versioning scheme so there is an examples branch or tree for each LTS track

[limdor]

Make sense, I just renamed the ticket to reflect this. If you already have another ticket for that we can close it. Should we create also one in bazelbuild/bazel to put everyone in sync or no need for that?

[limdor]

We should deprecate examples within bazelbuild/bazel in favor of bazelbuild/examples. The biggest problem with examples in the bazel repo is that we don't want to have examples that depend on repos beyond what is needed to build bazel. That artifically limits us.

We don't need an explanation. We just need to

• move them to bazelbuild/examples
• provide a versioning scheme so there is an examples branch or tree for each LTS track

@aiuto did your opinion on this topic changed? Just asking because this was some time ago and before I create too many PR I would like to confirm that this is still the wish of the Bazel team.

[aiuto]

My opinion did not change, but it's not really my call.
I add my new examples to examples, because they can run on CI, so I have some belief they are really working ones. And it is a much lower barrier to entry than changing the docs on bazelbuild/bazel. We can approve PRs directly against examples.

[limdor]

Ok thanks for the feedback. Whose call would be? It would be nice in order to have the example a bit more organized and less spread around.

[aiuto]

@radvani13 is the product manager. @meteorcloudy leads the team that "delivers" Bazel, so that includes CI and the doc generation pipeline. We don't, sadly, have a dedicated documentation specialist for either the site or the examples. Our process has been to try to match incoming PRs to the the best subject matter reviewer. That is best suited for targeted additions rather than large restructurings. I recently rewrote the README to provide a cookbook style index into the examples.
https://github.com/bazelbuild/examples
While that provides an index, when you land on each section, there should be much more text. For example, the index has "A rule with both explict and implicit outputs", but the folder does not have a README talking about why rules might have implicit outputs.