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

Add a document section about deferInitialization option when releasing v3.10 #1304

Closed
seratch opened this issue Feb 4, 2022 · 4 comments · Fixed by #1308
Closed

Add a document section about deferInitialization option when releasing v3.10 #1304

seratch opened this issue Feb 4, 2022 · 4 comments · Fixed by #1308
Assignees
Labels
docs M-T: Documentation work only
Milestone

Comments

@seratch
Copy link
Member

seratch commented Feb 4, 2022

The pull request #1303 in v3.10 milestone will add a new option deferInitialization. We can add a corresponding document section for it when it's released.


This is great, thanks for tackling this @seratch !

Not sure if we should bundle the documentation for this feature in this PR, or a separate one, but I think before merging this PR we should at least write a draft of the docs for this support. In my experience, writing up the docs alongside (or even before) the code is written up can help clarify how to structure the code too. I am happy to help write the docs if you would find that helpful - let me know, I can try to create a draft!

Originally posted by @filmaj in #1303 (review)

@seratch seratch self-assigned this Feb 4, 2022
@seratch seratch added the docs M-T: Documentation work only label Feb 4, 2022
@seratch seratch added this to the 3.10.0 milestone Feb 4, 2022
@filmaj
Copy link
Contributor

filmaj commented Feb 8, 2022

Thinking about where to add this documentation, I am not entirely sure. My initial thought is a new section under the 'Advanced Concepts' of the bolt-js docs - perhaps "Deferring initialization"? This would be a short section, similar perhaps to the Logging doc, describing 1) why someone would want to defer initialization, 2) how to do it and 3) what errors to expect if this is done incorrectly. Some ideas for copy for these sections:

  1. Perhaps something along the lines of "When initializing your Bolt app with the App constructor, an authentication test call is automatically made to the Slack backend to verify your tokens. In certain situations it may be desirable to more carefully control the timing of these calls. Bolt offers a way to defer initialization via the deferInitialization option, which places responsibility for fully initializing the Bolt app into your hands as the app developer." ?
  2. The right side of the docs layout would show a sample section of an app being constructed with the deferInitialization option, then further down in the code explicit invocation of the init() and then start() methods.
  3. Call out the fact that if start() is called before init(), an exception will be thrown.

Thoughts/opinions/comments?

Oh, and of course updating any reference-style documentation would be in order, too.

@seratch
Copy link
Member Author

seratch commented Feb 8, 2022

@filmaj All look good to me!

Oh, and of course updating any reference-style documentation would be in order, too.

Yes, specifically, https://slack.dev/bolt-js/reference#app-options should be updated too.

@srajiang
Copy link
Member

srajiang commented Feb 8, 2022

@filmaj How about instead of:

When initializing your Bolt app with the App constructor, an authentication test call is automatically made to the Slack backend to verify your tokens.

Something along the lines of:

Bolt offers a way to defer full initialization via the deferInitialization option and to call the equivalent App#init() in your code, putting more control over asynchronous events required for initialization into your hands as the developer.

@filmaj
Copy link
Contributor

filmaj commented Feb 8, 2022

Thanks for the comments and suggestions! PR is up here, if you have further comments or reviews let's move it to the PR: #1308

filmaj pushed a commit that referenced this issue Feb 9, 2022
filmaj pushed a commit that referenced this issue Feb 10, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs M-T: Documentation work only
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants