Should docs and examples for webdev.dartlang live here?

[matanlurey]

... instead of in another repository we don't really review often?

/cc @chalin @kwalrath @kevmoo

[chalin]

Good question. Some initial thoughts below.

Are there specific issues that we're trying to address by this? E.g., might there be a feeling that the docs and/or examples aren't keeping up closely enough with the rapid pace of Angular changes?

Aside: Along similar lines, why not bring angular_components under the dart-lang/angular umbrella too --- I'd love to see ACX releases in sync with NG releases. /cc @nshahan

That reminds me, webdev also hosts some (minimal) ACX docs, as well as other non-angular Dart-for-web examples and docs. We also host a full suite of API docs, though it seems that API docs will (so?) be hosted via the pub site, so that might change.

As you know there are pros and cons. Some of the pros of having a separate repo (off the top of my head):

• webdev is off the critical path, meaning Angular releases won't be delayed by issues with the examples and/or docs.
• webdev currently has 30+ examples, some of which use ACX; these examples are built and (component and E2E) tested under ddc and dart2js. E2E currently uses Protractor. As a separate repo, doing all this doesn't slow down angular builds -- and this seemed to be a concern recently.
• The repo is currently fully external, hosted on GH, so there are no issues of having to merge PRs from GH internally, and then pushing updates back out to GH.
• Repo access permissions can easily different for webdev.

Of course, it doesn't have to be all-or-nothing: maybe some core examples could be under dart-lang/angular. Or maybe it could be all of the examples, but leave the docs separate.

AngularTS have docs and examples under the angular/angular repo (but then again, they serve the docs using an Angular app, so that's extra motivation to ensure that that app is always fully operational with each AngularTS release).

The "pros" listed above become "cons" once the docs and examples are put under dart-lang/angular, but if those cons don't bother the core Angular team, then it might indeed be worth considering.

[nshahan]

It would be interesting if we could bring angular_components into the angular mono-repo. It would make it easier to keep them in sync and we could create some build tests from the example app.

The biggest con I see right now is that the development of the widgets is not centralized and changes come from lots of different product teams. Right now I do a lot of manual sanitizing of the code and commit descriptions to clean out internal product names and details. I wouldn't want to complicate the syncing of angular repos with that. When we work out a system to keep this clean, I'd revisit this idea.

[nshahan]

Personally I'd like to see some simple examples and empty template applications in the angular repo.

In the future could the webdev site pull examples from tagged releases in the angular repo so that the examples could evolve for alpha versions while the webdev site shows the stable version?

[matanlurey]

Lots of fun here. Some responses inline.

@chalin:

Are there specific issues that we're trying to address by this? E.g., might there be a feeling that the docs and/or examples aren't keeping up closely enough with the rapid pace of Angular changes?

Nope, this is not an issue with your teams pace, more that I want my team more involved in updating the docs/examples when we change things. If we want to break an API, we should document it/update examples accordingly.

webdev is off the critical path, meaning Angular releases won't be delayed by issues with the examples and/or docs.

We could experiment with things like travis-cron to make this nightly instead of per-push. We don't typically release AngularDart more than once a week, sometimes less frequently, so I don't see this as a huge blocker.

---

@nshahan:

It would be interesting if we could bring angular_components into the angular mono-repo. It would make it easier to keep them in sync and we could create some build tests from the example app.

Definitely. Nothing stops us from hosting the component gallery (or similar) in the examples/ folder pinned to the angular_components repo. Thoughts? I don't know if it makes sense or not.

Personally I'd like to see some simple examples and empty template applications in the angular repo.

Could you give some examples of what examples you'd like to see :)

[nshahan]

@matanlurey

Definitely. Nothing stops us from hosting the component gallery (or similar) in the examples/ folder pinned to the angular_components repo. Thoughts? I don't know if it makes sense or not.

My plan for the near future is to move all of the examples into the angular_components repo /example directory. I'd prefer to keep them close since that is an obvious place to look for them.

Could you give some examples of what examples you'd like to see :)

I think it would be helpful to see basic apps that show off features of the different repos. An app that uses angular_forms, An app that uses angular_router. etc. For templates, I'd like a go to resource for the different app bootstrapping techniques (with explanations of which to use for different circumstances). A template app that uses angular_router would be nice too. I wouldn't want too many templates though so maybe some of that should just be documentation. (and maybe it's already there, I just haven't seen it) 😃

[chalin]

On the topic of templates, we have, as you probably know, the Stagehand templates. Not too long ago we actually cut down on the number of templates (dart-archive/stagehand#390). As of now, for example, there is a single Angular + ACX template (web-angular).

The webdev docs to make use of our Angular-examples repos (https://github.com/angular-examples) as starting points. Having individual repos for each example makes it easier for readers to use them as starting points (at least in WebStorm), as described in the Use WebStorm’s Git support section of the Setup for Development page.

@nshahan:

In the future could the webdev site pull examples from tagged releases in the angular repo so that the examples could evolve for alpha versions while the webdev site shows the stable version?

Yes, we're doing something similar with the Angular-examples repos already. So pulling versions of apps from dart-lang/angular would be fine too.