Description

The Open Graph images are not generated when we share https://www.botkube.io/ over social media. An open graph image or OG image is the image that appears when you post website or video content to your social accounts.

References

• Use https://developers.facebook.com/tools/debug/ to validate results for Facebook.
• Use https://www.linkedin.com/post-inspector/ to validate results for LinkedIn.
• Use https://cards-dev.twitter.com/validator to validate results for Twitter.

Overview

After we've changed documentation domain Algolia configuration needs to be fixed

AC

• index is fixed
• search bar is enabled

Dev Notes

• Add post on official formu https://discourse.algolia.com/t/change-domain-on-an-open-source-site/16694
• request and issue on support zendesk https://support.algolia.com/hc/en-us/requests/525786

Options sidebar on the homepage doesn't load on mobile devices

I forgot to report this issue, but I noticed it ~1 or 2 weeks ago:

When I navigate to https://www.botkube.io/ and click "Community Slack" (http://join.botkube.io/), all I see is "The link is no longer active":

Could you please update that? I would love to join it 🙂 Cheers!

Description

As the official documentation page says:

App Studio has evolved. Configure, distribute, and manage your Teams apps with the new Developer Portal.
App Studio will be deprecated by August 01, 2022.

You can also see that notice in the App studio itself:

The current MS Teams installation instruction describes configuration via App Studio. We should update it and document all steps in the new Developer Portal instead.

All the options are still there, but they are located in different places (tabs / modals, etc.), but we need to update the text and make new screenshots.

Description

In Release Github Action, we generate versioned documentation with docusaurus tool, but it generates a version file which prettier tools does not like it. We need to run npx prettier before pushing to release branch after doc generation.

Expected behavior

# versions.json file
["0.13", "0.14"] 

Actual behavior

# versions.json file
[
  "0.13",
  "0.14"
] 

Steps to reproduce

Contact Details

No response

What happened?

BotKube arch image on the homepage is not getting rendered correctly on a few screen sizes/resolutions.
Above screenshot is on the following configuration:

1920 x 1080 16:9 - 14"

Version

1.0.0 (Default)

Relevant log output

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

There seems to be a confusion in the docs related to installation in slack, It feels like there is no comments about the use of the cloud version, and exporting those bot token and App token is not usefull when we are using the cloud version, as we just need to copy the token from the slack console and directly paste it over to the webpage, so i think a comment metioning that would be nice.

Overview

Our documentation's structure is changing quite often so to track if old links, that where published before in 3rd party platforms, social media or in botkube itself, still working we need to have a list of them and possibility to check 404 errors.

The solution won't be perfect (because tracking all changes will be tedious task) but at least this solution give us a hand on most cases.

AC

• extend this script magefiles/magefile.go#23 (CheckDeadLinks) to check additional markdown (e.g. - archive-links.md)
• provide archive-links.md markdown with old links, that needs to be supported.

Description

The support for notification type was removed in v1.0.0 but it still appears in the current (1.2.0) documentation:

Expected behavior

The configuration option for notification.type should not be present in the documentation including the examples.

Actual behavior

The configuration option is mentioned.

Overview

Acceptance Criteria

Docs

• Docs: Describe how to diagnoze some problems (e.g. get logs, kubectl describe etc.) (something like https://capact.io/docs/operation/diagnostics)

  • how to get logs
  • Use config-exporter to dump the configuration for all bug reports
    • See how it is used in https://github.com/kubeshop/botkube/blob/main/cmd/cli/cmd/migrate.go
    • Guide user to run the job on K8s cluster and get the result

• Docs: Describe common problems (like https://capact.io/docs/operation/common-problems)

  • e.g. Botkube killed by Kubernetes when internet connectivity is too slow
  • Bot not invited to channel - probably it's already fixed by our CLI
  • Donna and Maria had the problems
  • Encourage to join community slack in case someone is stuck and is looking for help

Botkube Open Source

• CLI: Ensure we link to the troubleshooting docs in CLI installation failed message
  • Maybe replace "Installation failed" error message to something different? It's not always about installation, it could be a temporary problem with a pod.
• Agent: Consider increasing thresholds for the probes as plugin download might take a while (e.g. to 50? 100?)
  • https://github.com/kubeshop/botkube/blob/main/helm/botkube/values.yaml#L949
  • https://github.com/kubeshop/botkube/blob/main/helm/botkube/values.yaml#L962
• Goreleaser config for plugins: release plugins in tar.gz archives
  • For local env keep binaries anyway
  • We use go-getter so unpacking that will be out of the box (just need to double check they are packed without additional nested directory)

Reason

Currently we lack a troubleshooting-related guide, which helps with basic debugging. Sometimes on our community Slack we receive similar questions, and we could have a single place with most common issues.

Hi, following the steps mentioned in READMEmd to set up the Hugo site locally, fails with following erros.

$ hugo serve -D
Building sites … WARN 2020/10/02 14:57:37 Page.Hugo is deprecated and will be removed in a future release. Use the global hugo function.
ERROR 2020/10/02 14:57:37 render of "page" failed: execute of template failed: template: _default/single.html:1:3: executing "_default/single.html" at <partial "header.html" .>: error calling partial: execute of template failed: template: partials/header.html:52:7: executing "partials/header.html" at <partial "menu.html" .>: error calling partial: "/home/aananth/workspace/github/botkube-docs/themes/hugo-theme-learn/layouts/partials/menu.html:100:23": execute of template failed: template: partials/menu.html:100:23: executing "section-tree-nav" at <(not .Params.hidden) or $.showhidden>: can't give argument to non-function not .Params.hidden
ERROR 2020/10/02 14:57:37 render of "page" failed: execute of template failed: template: _default/single.html:1:3: executing "_default/single.html" at <partial "header.html" .>: error calling partial: execute of template failed: template: partials/header.html:52:7: executing "partials/header.html" at <partial "menu.html" .>: error calling partial: "/home/aananth/workspace/github/botkube-docs/themes/hugo-theme-learn/layouts/partials/menu.html:100:23": execute of template failed: template: partials/menu.html:100:23: executing "section-tree-nav" at <(not .Params.hidden) or $.showhidden>: can't give argument to non-function not .Params.hidden
ERROR 2020/10/02 14:57:37 render of "page" failed: execute of template failed: template: _default/single.html:1:3: executing "_default/single.html" at <partial "header.html" .>: error calling partial: execute of template failed: template: partials/header.html:52:7: executing "partials/header.html" at <partial "menu.html" .>: error calling partial: "/home/aananth/workspace/github/botkube-docs/themes/hugo-theme-learn/layouts/partials/menu.html:100:23": execute of template failed: template: partials/menu.html:100:23: executing "section-tree-nav" at <(not .Params.hidden) or $.showhidden>: can't give argument to non-function not .Params.hidden
ERROR 2020/10/02 14:57:37 render of "section" failed: execute of template failed: template: _default/list.html:1:3: executing "_default/list.html" at <partial "header.html" .>: error calling partial: execute of template failed: template: partials/header.html:52:7: executing "partials/header.html" at <partial "menu.html" .>: error calling partial: "/home/aananth/workspace/github/botkube-docs/themes/hugo-theme-learn/layouts/partials/menu.html:100:23": execute of template failed: template: partials/menu.html:100:23: executing "section-tree-nav" at <(not .Params.hidden) or $.showhidden>: can't give argument to non-function not .Params.hidden
Built in 100 ms
Error: Error building site: failed to render pages: render of "page" failed: execute of template failed: template: _default/single.html:1:3: executing "_default/single.html" at <partial "header.html" .>: error calling partial: execute of template failed: template: partials/header.html:52:7: executing "partials/header.html" at <partial "menu.html" .>: error calling partial: "/home/aananth/workspace/github/botkube-docs/themes/hugo-theme-learn/layouts/partials/menu.html:100:23": execute of template failed: template: partials/menu.html:100:23: executing "section-tree-nav" at <(not .Params.hidden) or $.showhidden>: can't give argument to non-function not .Params.hidden

Hugo verision

Hugo Static Site Generator v0.74.3-DA0437B4 linux/amd64 BuildDate: 2020-07-23T16:22:34Z

Overview

Versions are not updated during release. Currently it is manual, we can add automation to replace it during release. Ref: https://github.com/kubeshop/botkube-docs/blob/v0.12.4/hack/release.sh

Acceptance Criteria

Reason

Description

Currently, the release pipeline doesn't work and the Botkube version in documents is not updated properly

Highlight CR support in homepage?
Add configuration example
Add screenshots

Overview

Add documentation to explain how to use Botkube event action automations

Acceptance Criteria

The documentation should include,

• How to configure the automation.
• Showcase access to event details using templated automation commands.
• Explain automation for events filtered by name and annotation.
• Showcase use of interactive chat to list, enable, disable automation commands.

Reason

Part of #789

Considering users queries on BotKube Slack, it looks like the multicluster setup documentation is not clear. Let's create a dedicated section for the same (maybe new page) and document setup as well as expected behavior command behaviors

Overview

Yesterday during our RBAC-related conversation, @donnalux and @brampling spotted missing stuff in our docs. It would be great to address them soon so that it is clear to the user.

Acceptance Criteria

Update RBAC doc (https://docs.botkube.io/configuration/rbac) not only for next, but also for 1.1,1.2, 1.3:

• describe explicitly all possible mappings:
  • user: static or channel name
  • group: static or channel name
• describe default permissions (botkube-plugins-default - https://github.com/kubeshop/botkube/blob/main/helm/botkube/values.yaml#L53C40-L53C40)

Reason

Currently it's hard to get a full picture of the RBAC mappings as we don't mention e.g. group static mapping, or what are the defaults.

We should have a release notes sections to announce

• Announcements
• New features
• Breaking changes
• Upgrade notes
• etc
  We already have automated CHANGELOG in place, we may need to refactor it or add separate sections for additional notes

We should have a notification bar on the BotKube website, which highlights latest news from BotKube.

The news could be:

1. Latest release out from BotKube
2. Hacktoberfest participation announcment

Eg. https://css-tricks.com/wp-content/uploads/2011/08/notificationbar.png

Rework the Examples section

As of now the Examples section is a collection of random tasks and screenshots.
It would be better if we give this section more order.

Acceptance Criteria

Real-world use-cases are provided in the examples section.

Reason

Current page is too generic and doesn't provide much value.

Overview

Use Docusaurus as static docs site generator.

AC

• Start from a scratch on a separate branch
  • Split it to few PRs
• Use the latest version of Docusaurus (v2)
• Configure it according to the docs website https://docusaurus.io/docs
  • Use TypeScript, Sass/SCSS (or CSS in JS if supported already)
  • Disable blog
  • Use and configure ideal-image plugin to have responsive images
  • SEO (metadata, meta image)
  • Update basic branding (logo, colors, fonts)
  • Use Google Analytics site
  • Add cookie banner (e.g. https://github.com/buildo/react-cookie-banner)
  • Configure Algolia search
• Split documentation to:
  • Versioned docs for BotKube
  • Unversioned docs for Community (similarly as https://github.com/capactio/website)
• Configure basic CI
• Configure eslint, Prettier

Examples

• https://github.com/capactio/website - versioned docs, separate community docs, cookie banner, basic CI, eslint, prettier
• ⚠️ Self-promotion alert 😄 https://github.com/pkosiec/website - ideal-image, TypeScript, meta-image, Sass/SCSS , basic CI, eslint, prettier

Reason

Currently, the botkube.io website has an outdated look and doesn't have support for documentation versioning.

Description

Helm chart version is not updated on final release cut. For all our releases, we had outdated Helm version badge and image tag, see:

f9ed8a1

Expected behavior

Released documentation has a valid version

Update Update versions in installation docs step:

Description

Following the helm command to deploy botkube for discord:

helm install --version v0.12.4 botkube --namespace botkube --create-namespace \
--set communications.discord.enabled=true \
--set communications.discord.channel=<DISCORD_CHANNEL_ID> \
--set communications.discord.botID=<DISCORD_BOT_ID> \
--set communications.discord.token=<DISCORD_TOKEN> \
--set config.settings.clusterName=<CLUSTER_NAME> \
--set config.settings.kubectl.enabled=<ALLOW_KUBECTL> \
--set image.tag=v0.12.4 \
botkube/botkube

doesn't correctly define the k8s cluster name.

Expected behavior

First message sent by the bot with the correct cluster name.

Actual behavior

First message sent by the bot:
...and now my watch begins for cluster 'not-configured'!

Steps to reproduce

Deploy botkube for discord using that helm command.

Since slack doc hierarchy changed, version replace is not handled properly. It should be fixed here

• Add usage
• Add example
• Update /botkubehelp to show help for @BotKube commands list

kubeshop/botkube#284

Overview

The version list is getting longer and longer. We should figure out a way to display just last 3 versions, and hide legacy/archived ones under All versions. We can see the following pages for inspiration (both are OS, so we can check the code how the "All versions" section is implemented):

• docusaurus.io
  
• https://jestjs.io/docs/getting-started
  

AC

• Display last three/five versions in the version switcher (to agree)
• Keep the previous versions, but hidden under "All/archived versions" page (see the impl in docusaurus or jest documentation)

botkube.slack.com

Description

Outdated things:

• COMMUNICATIONS_SLACK_TOKEN is invalid (missing group)
  • mention how to create such token (https://docs.botkube.io/configuration/#environment-variables)
• switch to socket Slack
• install Botkube from latest release instead from cloned main

Test that it works e2e.

Description

Recent version of botkube (v0.12.4) expects --set communications.discord.botid, but it is --set communications.discord.botID in the current doc. This breaks discord integration in a way that I cannot see kubectl command responses in Discord channel

Expected behavior

When I execute @BotKube ping on Discord, I should see pong message.

Actual behavior

It does nothing when I run @BotKube ping command

Steps to reproduce

• Follow installation steps as described here
• Run botkube commands on discord.

Overview

After rebranding and changing fraze BotKube -> Botkube some of the screenshots can be outdated. It's high time to update them 😉
Also we want to update all screenshots with commands where we can use kubectl prefix

Accepted Criteria

• update all screenshots where we used BotKube and change it to Botkube - (photoshopping if possible)
• update all screenshots with commands where we can possibly use kubectl prefix

Dev Notes:

Update screenshots in these pages next/0.14/0.13: (if it's possible do some photoshopping work. Please update the list if you find more pages for update):

• https://botkube.io/docs/installation/discord/
• https://botkube.io/docs/installation/teams/
• https://botkube.io/docs/configuration/filter/development
• https://botkube.io/docs/usage/
• https://botkube.io/docs/examples/
• https://botkube.io/docs/architecture/