mirror of
https://github.com/fleetdm/fleet
synced 2026-05-01 10:27:35 +00:00
a31db7fc83
See doc. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added a new decision record outlining the reasons for not using GitHub Discussions for technical conversations and summarizing considered alternatives. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Luke Heath <luke@fleetdm.com>
94 lines
4.2 KiB
Markdown
94 lines
4.2 KiB
Markdown
# 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](https://docs.github.com/en/discussions)
|
|
* [Toast](https://www.toast.ninja/)
|
|
* [GitHub Slack App](https://github.com/integrations/slack)
|