docs: update Slack CLI and Install Scripts to use the new https://slack.dev docs #34

mwbrooks · 2025-04-11T20:40:19Z

Summary

🤾🏻 Kudos to @zimeg for pointing this out!

This pull request updates all references to https://api.slack.com to https://slack.dev, when available.

In most cases, this just prevents a redirect from happening.

The main benefit is the promote our new CHANGELOG page whenever the Slack CLI has an update:

Requirements

I've read and understood the Contributing Guidelines and have done my best effort to follow them.
I've read and agree to the Code of Conduct.

codecov · 2025-04-11T20:42:00Z

Codecov Report

Attention: Patch coverage is 70.00000% with 3 lines in your changes missing coverage. Please review.

Project coverage is 62.92%. Comparing base (85749e2) to head (c689906).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/update/cli.go	0.00%	2 Missing ⚠️
cmd/function/function.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #34      +/-   ##
==========================================
+ Coverage   62.90%   62.92%   +0.01%     
==========================================
  Files         210      210              
  Lines       22149    22149              
==========================================
+ Hits        13933    13937       +4     
+ Misses       7131     7126       -5     
- Partials     1085     1086       +1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

mwbrooks

Added a few comments to help the kind reviewers! 📚

mwbrooks · 2025-04-11T20:40:51Z

.github/MAINTAINERS_GUIDE.md


 [circleci]: ../.circleci/config.yml
-[commands]: https://api.slack.com/automation/cli/commands
+[commands]: https://tools.slack.dev/slack-cli/reference/commands/slack


note: We might be able shorten this URL in the future to:
https://tools.slack.dev/slack-cli/reference/commands

mwbrooks · 2025-04-11T20:42:02Z

cmd/help/help.go

  $ {{.CommandPath}}{{if eq .Name (GetProcessName)}} <command>{{end}} <subcommand> --help

-  For guides and documentation, head over to {{LinkText "https://api.slack.com/automation"}}{{end}}
+  For guides and documentation, head over to {{LinkText "https://tools.slack.dev/slack-cli"}}{{end}}


thought: I think a more appropriate page is the new, Slack CLI homepage! ✨

mwbrooks · 2025-04-11T20:42:59Z

cmd/triggers/generate.go

 	if len(triggerFilePaths) <= 0 {
 		clients.IO.PrintInfo(ctx, false, style.SectionSecondaryf(
-			"No trigger definition files found\nLearn more about triggers: https://api.slack.com/automation/triggers/link",
+			"No trigger definition files found\nLearn more about triggers:\nhttps://tools.slack.dev/deno-slack-sdk/guides/creating-link-triggers",


note: I added a newline \n since the URL is a little longer.

mwbrooks · 2025-04-11T20:43:14Z

cmd/upgrade/upgrade.go

 var checkForUpdatesFunc = checkForUpdates

-const changelogURL = "https://api.slack.com/automation/changelog"
+const changelogURL = "https://docs.slack.dev/changelog"


note: MVP change!

mwbrooks · 2025-04-11T20:43:54Z

internal/slackerror/errors.go

+		Remediation: fmt.Sprintf(`Learn about building apps with the Deno Slack SDK:
+
+https://tools.slack.dev/deno-slack-sdk
+
+If you are using a Bolt framework, add a deploy hook then run: %s

 Otherwise start your app for local development with: %s`,
-			style.Commandf("deploy --experiment=bolt", true),
+			style.Commandf("deploy", true),


note: Updated an old Bolt Experiment reference, how does it read?

mwbrooks · 2025-04-11T20:44:47Z

scripts/install-dev.sh

                echo "🛑 Error: This installer is only supported on Linux and macOS"
                echo "🔖 Try using a different installation method:"
-                echo "🔗 https://api.slack.com/automation/cli/install"
+                echo "🔗 https://tools.slack.dev/slack-cli"


note: Install script updates! So we'll want to deploy those next release 🚀

This is a good landing page to point to IMO since the exact error at this point might not be known to the installer.

Once more I'm optimistic that issues will be useful in debugging issues with the installation script when these are encountered 🙏 ✨

Edit: I also look forward to the next release! 🚀

Yea, I'm looking forward to weaving GitHub Issues into more of the output from the CLI!

mwbrooks · 2025-04-11T20:45:06Z

scripts/install.sh

                if [ -z "$LATEST_SLACK_CLI_VERSION" ]; then
                    echo "🛑 Error: Installer cannot find the latest Slack CLI version!"
-                    echo "🔖 Check the status of https://api.slack.com and try again"
+                    echo "🔖 Check the status of https://slack-status.com/ and try again"


note: Cool with this? The URL seems more appropriate?

🧠 This is a nice change! IIRC the status of CLI downloads will match other services of Slack and might not be related to the api.slack.com page.

Tracking status problems down from reported issues seems ideal to me now that this can be reported via GitHub issues.

Before this codebase was open source we might've been reliant on sharing updates through other channels but I do not recall if we've had to do that...

Edit: I realize this particular change is after erroring while gathering metadata from the "api.slack.com" pages!

This makes even more sense to use the https://slack-status.com/ site instead in case the linked subdomain might error somehow else 😅

Good points! If we find that https://slack-status.com/ doesn't reflect our file serving endpoints (I imagine it does) then we can always update this error to ask people to submit a GitHub Issue. This would allow us to investigate it further.

zimeg

@mwbrooks All of these updates are so much appreciated 📚 ✨

These pages and related have been in constant motion the past few days but now seems like the right time to make these updates.

I did leave a few comments of links to "api.slack.com" that might have alternative "docs.slack.dev" endpoints we might use instead?

That's no blocker but I do think we should make these replacements where possible. I'm adding a commit that updates a few more links in comments and related too, but please revert that if it's not making the right changes 🤖

zimeg · 2025-04-11T21:38:25Z

.github/cli-sdk-specification.md


 ## 📄 Hook Specification

-Hooks are entry points for the CLI to initiate inter-process communication with the SDK. SDKs should implement one hook: `get-hooks`. It is the recommended approach for SDKs to enable communication with the CLI (for more details, see the [Hook Resolution](#hook-resolution) section). 


zimeg · 2025-04-11T21:40:43Z

.github/cli-sdk-specification.md

 ### 🪝 `build` (optional)

-Implementing this hook allows for the CLI to [deploy function code to Slack's managed infrastructure](https://api.slack.com/automation/deploy). The work of assembling the application bundle according to Slack's application bundle format is delegated to the SDK via this hook.
+Implementing this hook allows for the CLI to [deploy function code to Slack's managed infrastructure](https://tools.slack.dev/deno-slack-sdk/guides/deploying-to-slack). The work of assembling the application bundle according to Slack's application bundle format is delegated to the SDK via this hook.


📣 I'm glad the specification is included with the repo.

Some sidethought makes me think we might want to include the build hook before deploy for bolt apps too.

I don't mean to sidetrack this PR though! We could instead discuss this on a separate PR around this document 🤖

Definitely want consistency in how the hooks are executed - it shouldn't skip hooks based on the framework, instead the framework can have a no-op (exit 0) script.

.github/cli-sdk-specification.md

cmd/project/samples.tmpl

internal/api/client.go

zimeg · 2025-04-11T21:56:34Z

scripts/install.sh

                if [ -z "$LATEST_SLACK_CLI_VERSION" ]; then
                    echo "🛑 Error: Installer cannot find the latest Slack CLI version!"
-                    echo "🔖 Check the status of https://api.slack.com and try again"
+                    echo "🔖 Check the status of https://slack-status.com/ and try again"


🧠 This is a nice change! IIRC the status of CLI downloads will match other services of Slack and might not be related to the api.slack.com page.

Tracking status problems down from reported issues seems ideal to me now that this can be reported via GitHub issues.

Before this codebase was open source we might've been reliant on sharing updates through other channels but I do not recall if we've had to do that...

zimeg · 2025-04-11T21:58:23Z

scripts/install-dev.sh

                echo "🛑 Error: This installer is only supported on Linux and macOS"
                echo "🔖 Try using a different installation method:"
-                echo "🔗 https://api.slack.com/automation/cli/install"
+                echo "🔗 https://tools.slack.dev/slack-cli"


This is a good landing page to point to IMO since the exact error at this point might not be known to the installer.

Once more I'm optimistic that issues will be useful in debugging issues with the installation script when these are encountered 🙏 ✨

zimeg · 2025-04-11T21:58:47Z

scripts/install-dev.sh

                echo "🛑 Error: This installer is only supported on Linux and macOS"
                echo "🔖 Try using a different installation method:"
-                echo "🔗 https://api.slack.com/automation/cli/install"
+                echo "🔗 https://tools.slack.dev/slack-cli"


Edit: I also look forward to the next release! 🚀

Co-authored-by: Eden Zimbelman <[email protected]>

mwbrooks · 2025-04-14T20:52:08Z

@zimeg As always, thanks for the thorough review! I've added all of your suggestions and it inspired me to do another search through our api.slack.com references. Commit c689906 also updates our app manifest reference to this new page:
https://docs.slack.dev/reference/app-manifest

docs: update all references to https://slack.dev when possible

ad30d27

mwbrooks added docs M-T: Documentation work only changelog Use on updates to be included in the release notes semver:patch Use on pull requests to describe the release version increment labels Apr 11, 2025

mwbrooks added this to the Next Release milestone Apr 11, 2025

mwbrooks self-assigned this Apr 11, 2025

mwbrooks commented Apr 11, 2025

View reviewed changes

mwbrooks marked this pull request as ready for review April 11, 2025 20:45

mwbrooks requested a review from a team as a code owner April 11, 2025 20:45

mwbrooks requested review from lukegalbraithrussell and zimeg April 11, 2025 20:45

zimeg approved these changes Apr 11, 2025

View reviewed changes

zimeg and others added 8 commits April 11, 2025 15:26

docs: include reference to pages of docs with changed paths

05875d9

Update .github/cli-sdk-specification.md

516e5b6

Co-authored-by: Eden Zimbelman <[email protected]>

Update .github/cli-sdk-specification.md

185943b

Co-authored-by: Eden Zimbelman <[email protected]>

Update .github/cli-sdk-specification.md

23c3d8a

Co-authored-by: Eden Zimbelman <[email protected]>

Update .github/cli-sdk-specification.md

7b82392

Co-authored-by: Eden Zimbelman <[email protected]>

Update .github/cli-sdk-specification.md

235f22d

Co-authored-by: Eden Zimbelman <[email protected]>

Merge branch 'main' into mwbrooks-slack-dot-dev-urls

5b9a32c

docs: use docs.slack.dev app manifest reference page

c689906

mwbrooks changed the title ~~docs: update Slack CLI and Install Scripts to use the new https://slack.dev website~~ docs: update Slack CLI and Install Scripts to use the new https://slack.dev docs Apr 14, 2025

mwbrooks merged commit 9e6bc44 into main Apr 14, 2025
6 checks passed

mwbrooks deleted the mwbrooks-slack-dot-dev-urls branch April 14, 2025 21:58


		## 📄 Hook Specification

		Hooks are entry points for the CLI to initiate inter-process communication with the SDK. SDKs should implement one hook: `get-hooks`. It is the recommended approach for SDKs to enable communication with the CLI (for more details, see the [Hook Resolution](#hook-resolution) section).

docs: update Slack CLI and Install Scripts to use the new https://slack.dev docs #34

docs: update Slack CLI and Install Scripts to use the new https://slack.dev docs #34

Uh oh!

Conversation

mwbrooks commented Apr 11, 2025

Summary

Requirements

Uh oh!

codecov bot commented Apr 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

mwbrooks left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mwbrooks commented Apr 14, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov bot commented Apr 11, 2025 •

edited

Loading