Create v2 Migration document #920
Conversation
Codecov Report
@@ Coverage Diff @@
## master #920 +/- ##
=====================================
Coverage 100% 100%
=====================================
Files 4 4
Lines 425 425
Branches 101 101
=====================================
Hits 425 425
Continue to review full report at Codecov.
|
Readme.md
Outdated
| @@ -91,35 +91,13 @@ app.use(co.wrap(function *(ctx, next) { | |||
| })); | |||
| ``` | |||
|
|
|||
| ### Old signature middleware (v1.x) - Deprecated | |||
| ### KOA v1.x Middleware Signature | |||
There was a problem hiding this comment.
We never use all caps. can we change this to Koa? :)
| @@ -80,7 +80,7 @@ app.use((ctx, next) => { | |||
|
|
|||
| ### GeneratorFunction | |||
|
|
|||
| To use generator functions, you must use a wrapper such as [co](https://github.com/tj/co) that is no longer supplied with Koa. | |||
| To use generator functions, you must use a wrapper such as [co](https://github.com/tj/co). | |||
There was a problem hiding this comment.
i think we should just remove this section as it would only confuse people
There was a problem hiding this comment.
I thought it was weak, but didn't know if the unbundling of co mattered. Seems not. Removed.
There was a problem hiding this comment.
Oh, wait! I completely misread this. My mistake. I thought you were referring to the dependency section in the migration page which is where I moved the "no longer supplied text" to.
@jonathanong When you refer to "this section" are you referring to the "GeneratorFunction" section?
Should I add back the dependency section I just removed?
There was a problem hiding this comment.
After thinking about it, I agree. The overview document should focus on the recommended way, which I think now is async and leave the other two formats for deeper documentation. I'd like to submit that as a separate PR, though, so as to not block the merging of this migration guide.
There was a problem hiding this comment.
I went ahead and restored the Dependency changes section I mistakenly removed. I don't know if its meaningful, I'm not actually a v1.x user, I was attracted by the v2.x release.
There was a problem hiding this comment.
yup, I meant the GeneratorFunction section. we shouldn't be recommending people to use generator functions, and if they do, it should be the v1.x version that should be migrated to async functions. this is a generation function with (ctx, next) arguments, which is a mix of v1.x and v2.x APIs and is awkward
|
this is great! anyone else have recommendations? |
docs/migration.md
Outdated
|
|
||
| ## v1.x support | ||
|
|
||
| The v1.x branch is still supported and may also receive feature updates. Except for this migration |
There was a problem hiding this comment.
may also receive feature updates
Is this misleading? I think I saw @jonathanong expressing no intent to add features in v1.x branch from this point on. Just to make sure.
There was a problem hiding this comment.
i would say, "should not expect feature updates".
There was a problem hiding this comment.
Updated to "should not expect feature updates."
|
|
||
| ## Upgrading middleware | ||
|
|
||
| You will have to convert your generators to async functions with the new middleware signature: |
There was a problem hiding this comment.
i would show next() in the signature
docs/migration.md
Outdated
|
|
||
| 1. Wrap all your current middleware in koa-convert | ||
| 2. Test | ||
| 3. npm outdated to see which koa middleware is outdated |
There was a problem hiding this comment.
wrap commands in backticks so they're easier to read npm outdated
docs/migration.md
Outdated
| 1. Wrap all your current middleware in koa-convert | ||
| 2. Test | ||
| 3. npm outdated to see which koa middleware is outdated | ||
| 4. Update one outdated middleware, remove using koa-convert |
There was a problem hiding this comment.
same with modules koa-convert
|
except for small fixes 👍 |
Give v2 migration its own document.
Hopefully, this creates a place that can collect any other necessary documentation on migrating. I've added some of the comments from #533, which is hard to find now because the issue is closed. Slight updates to main readme to make it friendlier to those new to Koa with v2.