GitHub Discussions Setup

GitHub Discussions Setup Guide

This document guides you through enabling and configuring GitHub Discussions for the ChurchCRM repository.

Step 1: Enable GitHub Discussions

Manual Setup (Repository Admin)

1. Go to https://github.com/ChurchCRM/CRM
2. Click Settings (gear icon, top right)
3. Scroll down to Features section
4. Find Discussions checkbox
5. ✅ Check the Discussions box
6. Click Save at the bottom of the page

GitHub Discussions is now enabled!

---

Step 2: Create Discussion Categories

Once Discussions are enabled, create these 6 categories:

Category 1: General Questions

• Purpose: General ChurchCRM questions that don't fit other categories
• Description: Ask general questions about features, usage, and ChurchCRM functionality
• Icon: 💬 (or choose from GitHub's options)

Category 2: Installation Issues

• Purpose: Help with installation, setup, and deployment
• Description: Get help with installing ChurchCRM on various hosting platforms (shared hosting, self-hosted, Docker, Azure, etc.)
• Icon: 🚀 (or setup-related icon)

Category 3: User Support

• Purpose: How-to questions and feature usage
• Description: Questions about using ChurchCRM features - Families, Groups, Events, Reports, Finances, etc.
• Icon: 👥 (or people-related icon)

Category 4: Administrator Questions

• Purpose: System administration, configuration, and management
• Description: Questions about backups, upgrades, permissions, SSL, localization, and system maintenance
• Icon: 🔧 (or admin-related icon)

Category 5: Developer Questions

• Purpose: Development, customization, and API questions
• Description: Questions about development setup, contributing code, APIs, database structure, and customization
• Icon: 👨‍💻 (or code-related icon)

Category 6: Troubleshooting

• Purpose: Debug help for issues
• Description: Share issues you're experiencing and get help from the community with troubleshooting and debugging
• Icon: 🐛 (or debug-related icon)

---

Creating Categories Manually

1. Go to ChurchCRM/CRM → Discussions
2. Click New Discussion button (top right)
3. You should see a prompt to Create a category
4. For each category above:
   • Enter the Category name
   • Enter the Description (from above)
   • Select an Emoji icon
   • Click Create category

---

Step 3: Create Pinned Announcements (Optional but Recommended)

Once categories are created, add welcome discussions in key categories:

In "General Questions" category:

Title: Welcome! How to Get Help

Content:

👋 Welcome to ChurchCRM Discussions!

This is where the community helps each other. Whether you have questions about features, 
need setup help, or are troubleshooting an issue, you're in the right place!

**Before posting:**
- Check the [FAQ](https://github.com/ChurchCRM/CRM/wiki/FAQs)
- Search existing discussions to see if your question is already answered
- Check the [Troubleshooting Guide](https://github.com/ChurchCRM/CRM/wiki/Troubleshooting)

**Choosing the right category:**
- [Installation Issues](https://github.com/ChurchCRM/CRM/discussions/categories/installation-issues) - Setup help
- [User Support](https://github.com/ChurchCRM/CRM/discussions/categories/user-support) - How to use features
- [Administrator Questions](https://github.com/ChurchCRM/CRM/discussions/categories/administrator-questions) - System admin
- [Developer Questions](https://github.com/ChurchCRM/CRM/discussions/categories/developer-questions) - Coding & customization
- [Troubleshooting](https://github.com/ChurchCRM/CRM/discussions/categories/troubleshooting) - Debugging issues

**Still need help?**
- Check [ChurchCRM Documentation](https://github.com/ChurchCRM/CRM/wiki)
- Report bugs via [GitHub Issues](https://github.com/ChurchCRM/CRM/issues)

To pin this discussion:

1. Open the discussion
2. Click ... (three dots) → Pin to category

---

Step 4: Update README and Main Documentation

After discussions are live, update:

1. README.md - Add link to Discussions in "Getting Help" section
2. Wiki links - Already updated! (Help.md, Home.md, Troubleshooting.md, etc.)

---

Discussion URL Format

Once categories are created, they'll be accessible at:

• General Questions: https://github.com/ChurchCRM/CRM/discussions/categories/general-questions
• Installation Issues: https://github.com/ChurchCRM/CRM/discussions/categories/installation-issues
• User Support: https://github.com/ChurchCRM/CRM/discussions/categories/user-support
• Administrator Questions: https://github.com/ChurchCRM/CRM/discussions/categories/administrator-questions
• Developer Questions: https://github.com/ChurchCRM/CRM/discussions/categories/developer-questions
• Troubleshooting: https://github.com/ChurchCRM/CRM/discussions/categories/troubleshooting

---

Automating Issue Comments (Advanced)

To automatically add helpful comments to new issues directing users to Discussions, see .github/workflows/issue-comment.yml in the repository.

This workflow:

• Comments on new issues with diagnostic guidance
• Points users to relevant Discussion category
• Helps triage issues vs support questions

---

Tips for Success

1. Sticky welcome post - Pin the welcome discussion in each category for visibility
2. Encourage participation - Thank contributors and highlight good Q&A threads
3. Monitor categories - Check regularly for unanswered questions
4. Link from docs - Documentation should always point to relevant Discussion category
5. Close duplicates - If someone posts the same question, point them to existing discussion

---

See Also

• GitHub Discussions Documentation
• Help & Support Wiki
• Bug Reporting Guide