fleet/docs/Contributing/adr/0002-github-discussions.md

ADR-0002: Not using GitHub Discussions 💬

Status 🚦

Accepted

Date 📅

2025-07-16

Context 🔍

Our team faces a challenge with managing complex technical discussions related to GitHub issues:

• 🗣️ GitHub issues are not conducive to having several complex discussions on multiple aspects of a story
• 💬 These discussions frequently happen in Slack instead
• ⏰ We lose all history in Slack after 90 days
• 🔍 There is no way to find the Slack discussion from the issue later
• 🌐 We are public by default, but Slack discussions are not public

This leads to loss of valuable context and decision-making history that could help future contributors understand why certain choices were made.

We initially considered GitHub Discussions as a potential solution to preserve these conversations and link them to issues.

Decision ✅

We have decided not to use GitHub Discussions for managing complex technical conversations.

This decision was made after evaluating GitHub Discussions and discovering several blocking issues that prevent it from solving our core problems:

• 🔗 Poor integration with GitHub Issues: There is no standard linkage between Discussions and Issues, making it difficult to maintain context between the two systems.
• 🚫 No Slack notifications: We cannot get GitHub Discussion notifications in Slack, which is critical for our workflow:
  • Toast does not support GitHub Discussions
  • GitHub Slack plugin is too noisy for our needs
  • We could not find any other suitable integrations
  • Using a Slack webhook is also too noisy since it cannot DM a person and simply publishes to a channel
  • Building our own custom integration would be too time-consuming

Consequences 🎭

Benefits ✨

• 🎯 Avoids introducing a tool that doesn't solve our core problems
• ⏱️ Saves time that would be spent on custom integration development
• 🔄 Prevents workflow fragmentation across too many platforms

Drawbacks ⚠️

• 📉 We still lose valuable discussion history after 90 days in Slack
• 🤷 No clear path forward for preserving complex technical discussions
• 🔍 Future contributors will continue to lack context on decision-making

Impact 💫

• 🚦 No change to current workflows
• 🔎 Team will continue searching for a better solution

Future considerations 🔮

• 🔍 Continue evaluating other tools and platforms for discussion preservation
• 💡 Consider alternative approaches such as:
  • 📝 Improving documentation practices to capture key decisions
  • 💭 Using issue comments more effectively
  • 📋 Creating design documents for complex features
  • 🔧 Exploring other discussion platforms that integrate better with our toolchain

Alternatives considered 🤔

Alternative 1 — use GitHub Discussions despite limitations

• Description: Adopt GitHub Discussions and work around the notification issues
• Pros: Native GitHub feature, preserves discussions indefinitely, searchable
• Cons: Poor Slack integration breaks our workflow, requires constant manual checking, no standard linkage to issues
• Reason not chosen: The lack of Slack notifications would significantly disrupt our team's workflow and likely lead to missed discussions

Alternative 2 — build a custom Slack integration

• Description: Develop our own integration to bridge GitHub Discussions and Slack
• Pros: Could provide exactly the notifications we need, customizable
• Cons: Significant development time, ongoing maintenance burden, diverts resources from core product
• Reason not chosen: Too time-consuming and would require ongoing maintenance

Alternative 3 — use an existing Slack webhook with modifications

• Description: Configure Slack webhooks to notify about GitHub Discussions
• Pros: No custom development needed, quick to implement
• Cons: Too noisy (publishes to channels only), cannot DM individuals, no filtering options
• Reason not chosen: Would create too much noise in channels and doesn't support targeted notifications

References 📖

• GitHub Discussions Documentation
• Toast
• GitHub Slack App