# How to Contribute to ChurchCRM ChurchCRM is a community project. Every church that uses it does so because someone — a volunteer, a developer, a designer, a pastor's assistant — gave a little of their time to make it better. **You don't need to write code to make a meaningful contribution.** Churches need to find ChurchCRM, understand it, and feel confident choosing it. That takes writers, designers, testers, social media managers, translators, and developers working together. --- ## Every Skill Matters | Your skill | How you help | |------------|-------------| | **Developer** | Fix bugs, add features, build community plugins | | **Plugin builder** | Create integrations ChurchCRM doesn't include yet | | **QA tester** | Find bugs, test new features, validate fixes | | **Designer** | UI/UX improvements, logo work, social graphics | | **Writer / content creator** | Blog posts, tutorials, case studies | | **Documentation writer** | User guides, admin docs, developer wiki | | **Translator** | Translate ChurchCRM into your language | | **Social media manager** | Grow ChurchCRM's presence and reach | | **Marketer** | Help churches discover ChurchCRM | | **Photographer / image creator** | Screenshots, promotional images, social assets | | **Community helper** | Answer questions on Discord and GitHub | --- ## No Code Required ### Write Content ChurchCRM's story needs to be told. Blog posts, tutorials, how-to guides, and church testimonials help other congregations understand what ChurchCRM can do and feel confident choosing it. **What's needed:** - Blog posts about ChurchCRM features and use cases - Church testimonials ("how we use ChurchCRM at our church") - Tutorial articles for common workflows - Comparison guides for churches evaluating software **Where to contribute:** Open an issue on [GitHub](https://github.com/ChurchCRM/CRM/issues) with the `documentation` label, or share your draft on [Discord](https://discord.gg/tuWyFzj3Nj). --- ### Improve Documentation The [official documentation site](https://docs.churchcrm.io) covers every feature but always needs clearer explanations, better examples, and updated screenshots. The docs are Markdown files in the [docs.churchcrm.io repository](https://github.com/ChurchCRM/docs.churchcrm.io). **What's needed:** - Clearer how-to steps for existing guides - New guides for features that lack documentation - Correcting outdated information after releases - Adding screenshots showing the current Tabler UI (7.1+) **No GitHub experience required** — you can [edit pages directly in the browser](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files) on GitHub. --- ### Translate ChurchCRM is used in 46 languages. Every new translation opens ChurchCRM to thousands of churches that couldn't use it before. **Translate via POEditor (no Git required):** 1. Join the [ChurchCRM POEditor project](https://poeditor.com/join/project/RABdnDSqAt) 2. Select your language (or request a new one) 3. Translate strings directly in the browser 4. Translations are automatically pulled into the next release **See:** [Localization for Translators](https://github.com/ChurchCRM/CRM/wiki/Localization-For-Translators) --- ### Test the Application You don't need to be a developer to test ChurchCRM. Browser testing, accessibility checks, and feature validation catch real bugs before they reach churches. **What's needed:** - Test new releases on different browsers and devices - Try common workflows (adding families, recording attendance, generating reports) - Report anything confusing or broken on [GitHub Issues](https://github.com/ChurchCRM/CRM/issues) - Test the [live demo](https://churchcrm.io/demo.html) and report issues **Use the [Bug Reporting Guide](https://github.com/ChurchCRM/CRM/wiki/Bug-Reporting-and-Diagnostics)** to include useful information when filing issues. --- ### Design & Create Images ChurchCRM's marketing site, documentation, and social presence all need visual assets — screenshots, promotional graphics, social media images, and UI design feedback. **What's needed:** - Updated screenshots showing the current ChurchCRM interface (Tabler UI) - Social media graphics for feature announcements - Promotional images for blog posts - UI/UX feedback on the application — what feels confusing, what could be clearer - Logo usage and brand asset improvements **Share your work** on [Discord](https://discord.gg/tuWyFzj3Nj) in the `#design` channel or open a GitHub issue with the `design` label. --- ### Social Media & Marketing ChurchCRM has thousands of users but most churches have never heard of it. Spreading the word is one of the highest-leverage ways to help — every church that switches from a paid subscription to ChurchCRM saves money they can redirect to ministry. **What's needed:** - Share ChurchCRM on social media (Facebook church groups, LinkedIn, X/Twitter, Instagram) - Write reviews on software directories (Capterra, G2, SourceForge, AlternativeTo) - Tell other churches in your denomination or network about ChurchCRM - Help with ChurchCRM's own social media presence by suggesting content or post ideas **Connect:** Share what you're doing on [Discord](https://discord.gg/tuWyFzj3Nj) so the team knows. --- ### Answer Questions in the Community People get stuck. A quick, helpful answer to a question on Discord or GitHub Discussions saves a church administrator hours of frustration and keeps them using ChurchCRM. **Where to help:** - [Discord server](https://discord.gg/tuWyFzj3Nj) — real-time questions from users - [GitHub Discussions](https://github.com/ChurchCRM/CRM/discussions) — in-depth questions No expertise required for most questions — if you've used ChurchCRM for a while, your experience is valuable. --- ## Developer Contributions ### Contribute to the Core Application Fix bugs, add features, improve performance, and expand test coverage in the main ChurchCRM codebase. **Quick start:** 1. Make sure you have a [GitHub account](https://github.com/signup/free) 2. Join [Discord](https://discord.gg/tuWyFzj3Nj) and introduce yourself 3. Ask in Discord what's a good place to start — maintainers will point you to something concrete 4. Set up your [development environment](#setting-up-your-development-environment) 5. Open a pull request **All PRs must be linked to an open issue.** If the issue doesn't exist yet, open it first. ### Build a Community Plugin Add a feature ChurchCRM doesn't include yet — a third-party API integration, a custom workflow, a specialized report — without modifying core code. Plugins survive upgrades and can be shared in the community registry. **Best for:** Service integrations (MailChimp, SMS, OpenLP, etc.), church-specific workflows, optional features not every installation needs. **Start here:** [Creating Community Plugins](https://github.com/ChurchCRM/CRM/wiki/Creating-Community-Plugins) > **Upgrade safety:** Direct modifications to ChurchCRM source files are overwritten when you upgrade. All custom features must live in plugins to survive releases. --- ## Setting Up Your Development Environment ### Quick Start (Recommended) **GitHub Codespaces (Easiest):** 1. Go to the [ChurchCRM GitHub repository](https://github.com/ChurchCRM/CRM) 2. Click "Code" → "Codespaces" → "Create codespace on master" 3. Wait 2–3 minutes for automatic setup 4. Run `npm run docker:dev:start` then open `http://localhost` with `admin`/`changeme` **VS Code Dev Containers:** 1. Install the "Dev Containers" extension in VS Code 2. Clone the repo and open it in VS Code 3. Click "Reopen in Container" when prompted **DDEV (Local Docker):** ```bash git clone https://github.com/ChurchCRM/CRM.git churchcrm cd churchcrm ddev start ddev setup-churchcrm ddev launch ``` Login: **admin** / **changeme** ### Coding Standards - **Database:** Propel ORM only — no raw SQL - **UI:** Bootstrap 5 / Tabler CSS classes (not Bootstrap 4) - **PHP:** 8.4+, PSR-12 style, explicit nullable types - **i18n:** Wrap all UI text with `gettext()` (PHP) or i18n helpers (JS) - **Business logic:** Service classes in `src/ChurchCRM/Service/` Full standards: `.github/copilot-instructions.md` in the repo ### Testing All pull requests require Cypress tests: ```bash npm run test # Run all tests (headless) npm run test:ui # Interactive browser testing ``` --- ## First Steps for Any Contributor 1. **Join Discord** — [discord.gg/tuWyFzj3Nj](https://discord.gg/tuWyFzj3Nj) — introduce yourself and tell us what you'd like to help with 2. **Browse open issues** — [github.com/ChurchCRM/CRM/issues](https://github.com/ChurchCRM/CRM/issues) — filter by label to find work that matches your skill 3. **Try the demo** — [churchcrm.io/demo.html](https://churchcrm.io/demo.html) — use ChurchCRM so you understand what you're helping with --- ## Code of Conduct All contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md). We are a welcoming, respectful community. Thank you — every contribution, no matter how small, helps a church somewhere run a little better.