[DOC beta] Registry and Container Reform

[mixonic]

2.1 should land in about two weeks. The following docs are lacking:

• Initializer docs/guides must be updated to accept only application as an argument
• Instance Initializer docs/guides must be updated to accept applicationInstance as the argument
• Guides must be audited emberjs/guides#789
• Requires deprecation guide entries for all relevant items

The main guidance existing today is the blog post for 2.1 beta, which also links to RFCs and PRs.

Please tag PRs for this with [DOC beta]

[mixonic]

/cc @dgeb, I've also sent the bat signal out to the docs team.

[rwjblue]

• Initializer docs/guides must be updated to accept only application as an argument
• Instance Initializer docs/guides must be updated to accept applicationInstance as the argument

Seems to be correct where Ember.Application.initializer and Ember.Application.instanceInitializer are documented:

• https://github.com/emberjs/ember.js/blob/master/packages/ember-application/lib/system/application.js#L726-L783
• https://github.com/emberjs/ember.js/blob/master/packages/ember-application/lib/system/application.js#L833-L949

[rwjblue]

• Registry methods must be made public and the methods doc'd, or the methods on application should be make public (unsure)

The container and registry are absolutely not being made public.

We have made a small subset of functionality public in a mixin (see here and here).

Those proxy mixins seem to be appropriately documented and marked as @public, but please double check/confirm when you have a chance as we absolutely may have missed something.

[rwjblue]

• Deprecated method in registry_proxy should be flagged deprecated

The property that is deprecated is calling any methods on application.registry, but that was never documented (either public or private). Where would we document that? Are you suggesting to add documentation for Ember.Application#registry just to mention that it is deprecated?

• Requires deprecation guide entries for all relevant items

Agreed.

[rwjblue]

I submitted #12337 with screenshots to ensure Ember.Application and Ember.ApplicationInstance have the proper linkages and docs.

[mixonic]

Updated after confirming some of Robert's feedback.

The property that is deprecated is calling any methods on application.registry, but that was never documented (either public or private). Where would we document that? Are you suggesting to add documentation for Ember.Application#registry just to mention that it is deprecated?

https://github.com/emberjs/ember.js/blob/master/packages/ember-runtime/lib/mixins/registry_proxy.js#L14 shows RegistryProxy as public. I was suggesting that RegistryProxy itself should likely not be public.

[rwjblue]

https://github.com/emberjs/ember.js/blob/master/packages/ember-runtime/lib/mixins/registry_proxy.js#L14 shows RegistryProxy as public. I was suggesting that RegistryProxy itself should likely not be public.

That was just added in #12337 (because I had to add @class to link properly with Ember.Application and Ember.ApplicationInstance), I'll update.

[rwjblue]

Changed RegistryProxyMixin and ContainerProxyMixin to be @private at the class level (methods are still @public) in #12339.

[acorncom]

[ ] Guides must be audited

Just ran through the guides. As far as I can see, we aren't using initializers anywhere (nor do we want to per @locks if I remember correctly). @locks, can you confirm?

[mixonic]

@acorncom they are rather heavily documented here: http://guides.emberjs.com/v2.0.0/services-and-initializers/initializers/ and ideally this is a chance for the docs to improve on that front.

[acorncom]

@mixonic indeed they are, I stand corrected. In my defense, I believe those changes hadn't yet been deployed to the live site when I made the comment :-)

[acorncom]

@mixonic I've just opened a guides issue for the docs team, do you want to reference it in the checklist above? Due to the way guides and versioning currently work, we may have to have a pull request pending and merge it as soon as 2.1 is released ...

[mixonic]

@acorncom updated, thanks :-)

[michaelrkn]

If this is a 2.1 feature, the guides documentation needs to land before 2.1 is released, so that it is documented. In fact, I believe the current contract is "no new features without documentation", so not having this documented in the Guides should probably be a 2.1 blocker.

[rwjblue]

@michaelrkn - The train stops for no one 😝. We can either remove the feature from 2.1 or get the guides updated (API documentation has been addressed in PR's notated above). We have a week or so to get it done, all we need is a volunteer 👯 ...

[acorncom]

For future changes like this, can we get an issue opened in the guides repo? Not sure any of us knew that this was coming (I just happened to be browsing over here and noticed the docs mention) ...

[dgeb]

Sorry to not chime in here until now. I'm willing to help out where needed.

[michaelrkn]

@dgeb can you take on emberjs/guides#789?

[dgeb]

@michaelrkn ok, will do 👍

[mixonic]

A deprecation guide is still needed this weekend.

[rwjblue]

Deprecation guide entries done (and deprecate calls updated to show the URL's) in the following PR's:

• Add deprecation guide for initializer arity. website#2376
• Add Application.registry info to deprecation guide. website#2378
• [DOC beta] Add URL for deprecation guide on initializer arity. #12430
• [DOC beta] Add links to app.registry.* deprecations. #12432

[rwjblue]

Closing as I believe all the items are addressed. @mixonic please reopen if you see something I have missed....