integration-docs: Update the SVN integration doc. #871
Conversation
zulip/integrations/svn/doc.md
Outdated
| You can configure the channel and topic where notifications are sent by | ||
| updating the `commit_notice_destination` function in | ||
| `{{ config_file_path }}`. By default, notifications are sent to a topic | ||
| named after the repository, in the "commits" channel. |
There was a problem hiding this comment.
This uses an incoming webhook bot, but not the URL generated for that, correct?
Maybe, "By default, notifications are sent to the "commits" channel with the repository as the topic name."?
Since a Zulip organization might not have a channel named "commits", I wonder if this should be noted somewhere above? I guess the bot owner would get a DM about the channel not existing when testing the integration.
There was a problem hiding this comment.
Yes, there's no URL generation for any of the integrations in this repo.
I've been removing the instruction with the create-channel macro, based on #32269 and the CZO topic #documentation>integrations docs as a new user.
I think Alya Abbott's opinion was to get the user thinking about the target channel, but without having an explicit instruction for that.
I checked the other open docs PRs (IRC, RSS), and it seems both of them involve the channel in some way (IRC - subscribe the bot; RSS - config options). SVN's the one that doesn't. I'm not sure how to go about this.
Do you think a tip might be an okay middle ground, not an instruction, but still reminds the user?
Or should we just edit:
"By default, notifications are sent to a topic named after the repository, in the "commits" channel."
to
"By default, notifications are sent to a topic named after the repository, in the "commits" channel, if it exists."
which can serve as a subtle reminder to make sure the target channel exists.
There was a problem hiding this comment.
Thank you for the review! Updated as recommended.
I've not made any changes related to the existence of the target channel, as I'm unsure how to proceed.
I've switched to using backticks instead of double quotes for channel names, and added the prefix # in front of channel names (because that's the convention in the Help docs - example), based on your review comment on another doc PR.
Screenshot
zulip/integrations/svn/doc.md
Outdated
| You can configure the channel and topic where notifications are sent by | ||
| updating the `commit_notice_destination` function in | ||
| `{{ config_file_path }}`. By default, notifications are sent to a topic | ||
| named after the repository, in the "commits" channel. |
There was a problem hiding this comment.
Yes, there's no URL generation for any of the integrations in this repo.
I've been removing the instruction with the create-channel macro, based on #32269 and the CZO topic #documentation>integrations docs as a new user.
I think Alya Abbott's opinion was to get the user thinking about the target channel, but without having an explicit instruction for that.
I checked the other open docs PRs (IRC, RSS), and it seems both of them involve the channel in some way (IRC - subscribe the bot; RSS - config options). SVN's the one that doesn't. I'm not sure how to go about this.
Do you think a tip might be an okay middle ground, not an instruction, but still reminds the user?
Or should we just edit:
"By default, notifications are sent to a topic named after the repository, in the "commits" channel."
to
"By default, notifications are sent to a topic named after the repository, in the "commits" channel, if it exists."
which can serve as a subtle reminder to make sure the target channel exists.
Screenshots
SVN doc link
Self-review checklist
(variable names, code reuse, readability, etc.).
Communicate decisions, questions, and potential concerns.
Individual commits are ready for review (see commit discipline).
Completed manual review and testing of the following: