Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added bolt@1.x support schedule to migration guide #449

Merged
merged 1 commit into from
Mar 27, 2020
Merged
Changes from all commits
Commits
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
20 changes: 13 additions & 7 deletions docs/_tutorials/migration_v2.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,14 @@ permalink: /tutorial/migration-v2
# Migrating to v2.x

<div class="section-content">
This guide will walk you through the process of updating your app from using `@slack/bolt@1.x` to `@slack/bolt@2.x`. There are a few changes you'll need to make but for most apps, these changes can be applied in 5 - 15 minutes.
This guide will walk you through the process of updating your app from using `@slack/bolt@1.x` to `@slack/bolt@2.x`. There are a few changes you'll need to make but for most apps, these changes can be applied in 5 - 15 minutes.

*Note: Make sure to checkout our [support schedule](#slackbolt1x-support-schedule) for `@slack/bolt@1.x` if you don't plan on upgrading right away*
</div>

---

## Upgrading your listeners to `async`
### Upgrading your listeners to `async`

Listeners in your app should updated to `async` functions and `say()`, `respond()`, and `ack()` should be prefaced with `await`.

Expand All @@ -37,11 +39,11 @@ app.action('some-action-id', async ({action, ack, say}) => {
```


## Error Handling
### Error Handling

The recent changes in Bolt for JavaScript V2 have improved our ability to catch errors and filter them to the global error handler. It is still recommended to manage errors in the listeners themselves instead of letting them propagate to the global handler when possible.

### Handling Errors in Listeners with `try`/`catch`
#### Handling Errors in Listeners with `try`/`catch`

```javascript
app.action('some-action-id', async ({action, ack, say, logger}) => {
Expand All @@ -55,7 +57,7 @@ app.action('some-action-id', async ({action, ack, say, logger}) => {
})
```

### Handling Errors with the Global Error Handler
#### Handling Errors with the Global Error Handler

```javascript
app.error((error) => {
Expand All @@ -70,7 +72,7 @@ Other error related changes include:
- If multiple errors occur when processing multiple listeners for a single event, Bolt for Javascript will return a wrapper error with a `code` property of `ErrorCode.MultipleListenerError` and an `originals` property that contains an array of the individual errors.


## Message Shortcuts
### Message Shortcuts

[Message shortcuts](https://api.slack.com/interactivity/shortcuts/using#message_shortcuts) (previously referred to as message actions) now use the `shortcut()` method instead of the `action()` method.

Expand All @@ -92,7 +94,7 @@ app.shortcut('message-action-callback', async ({shortcut, ack, context}) => {
})
```

## Upgrading Middleware
### Upgrading Middleware

If you wrote a custom middleware, adjust your function to `async` and update `next()` to `await next()`. If your middleware does some post processing, instead of passing a function to `next()`, you can now run it after `await next()`.

Expand Down Expand Up @@ -120,3 +122,7 @@ async function noBotMessages({ message, next }) {
}
}
```

### @slack/bolt@1.x support schedule

`@slack/bolt@1.x` will be deprecated on **June 30th, 2020**. We plan on continuing to implement bug fixes and will also consider back-porting new features on a case by case basis up until then. Once `@slack/bolt@1.x` has been deprecated, we will only implement **critical bug fixes** until the official end of life date and close non critical issues and pull requests. End of life is slated for **April 30th, 2021**. At this time, development will fully stop for `@slack/bolt@1.x` and all remaining open issues and pull requests will be closed.