Skip to content
This repository was archived by the owner on Oct 24, 2021. It is now read-only.

1.3 migration outline #221

Merged
merged 2 commits into from
Feb 12, 2016
Merged

1.3 migration outline #221

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0babd52
1.3 migration outline
tmeasday Feb 4, 2016
d432425
Added a what's new section
tmeasday Feb 4, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions outlines/1.3-migration
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
1. Breaking changes (as we'd normally do this)

2. Recommended changes : Modules [link to app structure guide]
1. Applications: Move all files to imports, initialize in one spot, link via `import`
2. Import *all* symbols from packages, including meteor core packages.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This means we need to document where these symbols come from, which is currently completely not in the docs. It could also get a bit awkward, like:

import { Meteor } from 'meteor';

// lol
Meteor.loginWithPassword

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair point. What do we recommend then? Non-core symbols? What's the definition?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know, it's kind of a rough spot overall.

On the one hand, I love the explicit imports.

On the other hand, it's weird that you don't actually get to see where the function came from, you just see where the namespace came from, which kind of defeats the main purpose of imports.

On the third hand, it shuts up the linter complaining about globals... I wonder how hard it would really be to improve the APIs of all the core packages to be compatible with modules, so you could do import { loginWithPassword } from 'accounts-password'.

Speaking of which, do you currently still get globals from Meteor packages even when your file is in imports?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Speaking of which, do you currently still get globals from Meteor packages even when your file is in imports?

I would have thought so, I mean Meteor puts those symbols on window; it doesn't matter where the code being executed lives.

I wonder how hard it would really be to improve the APIs of all the core packages

Yeah I mean if we are going to recommend that package authors export const X from their packages, then we should really do the same, even if we leave the api.exports() (or attaching to the Meteor namespace) for backwards compat.

We should probably call stuff out in the docs as deprecated too. I fear to ask, but is there a way to do this? ;)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried to add a @deprecated JSDoc tag like 1.5 years ago, but people never really got on board with it. We could bring back the dream, though!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm into it. It sounds like something to look at in concert with rationalizing / cataloging the docs as we've discussed before. Did you make progress on that yet?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well all of this would be just adding additional metadata to the API methods, which is something the docs app is actually very well-equipped to do. For example, maybe we could use the jsdoc @module annotation: http://usejsdoc.org/tags-module.html

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's put this on the agenda for the next guide meeting

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/meteor/guide/blob/master/meeting-notes.md#agenda-for-next-standup

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

3. No longer use `api.exports()` in packages (?), publish to NPM if not Meteor specific (?)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should include something about how to then use those packages in other Meteor packages. Like if you publish some utility to NPM, how do you use it in your Meteor-specific package? Do you still use Npm.depends?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good questions. I don't know the answer; @benjamn?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Asked in #platform, hopefully will get an answer soon

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have an answer for this, will write the version checking package and document it here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

4. Install npm packages directly, instead of using wrapper packages (unless the wrapper package adds a synchronous API).
5. Install React from NPM (remove `react` package?), see React guide for more.

3. Recommended changes: Testing [link to testing guide]
1. Integration testing: Migrating from velocity
1. You can move your tests alongside your modules with the `*.tests.*` naming convention.
2. Depending on your testing library, you may need to upgrade or replace your test package (link to libraries)
3. Run integration tests with `meteor test-app --integration`
2. Unit testing: Migrating from package tests
1. If you were using in-app packages for testing, you can now use the unit test mode to test your modules.
2. If you were using tinytest, you will need to migrate your test code (Mocha is recommended)
3. If you were using Mocha/Jasmine/..?, you can now place your tests in the imports folder alongside the unit to test and they'll automatically be added to your unit test suite.
4. Run unit tests with `meteor test-app --unit`

4. Recommended changes: Mobile [link to mobile guide]
1. Are there any things people should do differently?


5. What's new in the 1.3 guide:
1. App structure article
2. Testing article
3. React article
4. Angular article
5. Mobile article (?)
6. i18n section of UI guide (?)