Skip to content

Contributing

Jump to bottom
Robert Spencer edited this page May 10, 2024 · 45 revisions

How to contribute

We love to hear ideas from other ChurchInfo and ChurchCRM users! It's what makes this platform so great and versatile. If you have an idea to contribute, please take a few moments to share it with us!

The project welcomes, and depends on, contributions from developers and users in the open source community. Contributions can be made in a number of ways. A few examples are:

  • Code patches via pull requests
  • Documentation improvements
  • Bug reports and patch reviews

First Steps

  1. Read this whole page "top to bottom."
  2. Make sure you have a GitHub account
  3. Introduce yourself in the developer chat at https://gitter.im/ChurchCRM/CRM
  4. Take a look at the Open Issues page.
    • We've made it easy for beginners with the good first issue Label - these are issues that should be relatively easy to fix.
  5. Have fun!

Documentation

Please familiarize yourself with the wiki for the part(s) of code that you're changing.

If you are changing something that affects the user interface, please update the appropriate documentation and help files to ensure continued user friendliness of the application.

Development Workflow - Getting Things Done

When contributing to ChurchCRM, please follow these steps in order:

  1. Document the Issue
  2. Make Changes
  3. Submit Changes for review
  4. Wait for approval / comments / merge

1. Document the Issue

Before working on any code, first check to see if the issue you're addressing has already been reported. If a similar issue has already been reported, please review the comments, and add any notes you may wish to contribute.

All pull requests must pertain to an open issue, and the issue number must be included in the pull request. Pull requests that are not linked to an issue will be rejected.

If the issue you want to address has not already been reported, first create a new issue. Include as much detail as you can. Clearly describe the issue including steps to reproduce when it is a bug. If possible, use the built-in bug reporter to collect various parameters from your installation.

Issues should be very specific so that code changes remain small and scoped to a particular issue. Large changes, while sometimes necessary, are generally discouraged.

Issue Workflow

Newly reported issues will not be part of a milestone.

The team will try to review issues without a milestone within 7 days of being reported.. After the team reviews the issue, we will assign it to either "Backlog" or "On-Deck"

  • Backlog means that the issue or feature request is valid, but is not priority.
  • On-Deck means that the issue is under consideration for the upcoming milestones.

When an issue has been resolved, it will be moved to the milestone release which contains the fix.

2. Making Changes

Create a topic branch from where you want to base your work. This makes it easier to see exactly what you're changing, and allows us to ask questions if necessary.

To quickly create a topic branch based on master; git checkout -b <bug>/<issue number>-<description>. Please note the naming scheme. Please avoid working directly on the master branch, as this makes PRs difficult

Make commits of logical units - Whenever you get a specific piece of code working is a good time to commit. Include comments about what changes you made in the commit.

Commit Early, Commit Often is a great motto.

Check for unnecessary whitespace with git diff --check before committing.

Changes to ChurchCRM will trigger version number changes in accordance with Semantic Versioning 2.0.0

Testing

All PRs require appropriate tests of each piece of code that is modified. PRs lacking proper tests will not be merged. Please see our Automated Testing documentation.

We are happy to help you write tests, but tests are required.

3. Submitting changes

When you're confident that the changes you've made are ready to be incorporated into the project, you should open a Pull Request. Be sure that your Pull Request targets the ChurchCRM/CRM project. Pull requests made to other repositories will not be seen by ChurchCRM project maintainers.

If your changes affect the UI/UX, Please include a screenshot or screencast (LICEcap is a free animated GIF screen cast application)

The core team looks at Pull Requests on a regular basis. We are 100% volunteer, so your patience is appreciated.

After feedback has been given we expect responses within two weeks. After two weeks we may close the pull request if it isn't showing any activity.

Pull requests are the only way that code changes may be incorporated into the project. Any code changes submitted via snippets, zip archives, or other means will be rejected.

Personal Branches

All unreleased code within organizational repositories should not be used in production. All branches in the ChurchCRM organization are subject to modification by organization members.

If you require a personal branch that is not to be modified by ChurchCRM maintainers, please Create a Fork of the project in your own GitHub account. You can still create pull requests to the core project from your fork.

Personal Forks

If you have already cloned the ChurchCRM/CRM repository and now wish to contribute to development efforts, you may need to take additional steps:

  1. Obtain a list of "Git remotes" from your current repository:
git remote -v

You will likely see the official remote listed:

origin  https://github.com/ChurchCRM/CRM.git (fetch)
origin  https://github.com/ChurchCRM/CRM.git (push)
  1. Remove the reference to the official ChurchCRM origin:
git remote remove origin
git remote -v origin

Note that there is no longer an HTTPS URL associated with origin.

  1. Update your copy of the repository to point at your personal fork:
git remote add origin https://github.com/<YOUR GIT USERNAME>/CRM.git
git remote -v
origin  https://github.com/<YOUR GIT USERNAME>/CRM.git (fetch)
origin  https://github.com/<YOUR GIT USERNAME>/CRM.git (push)
  1. Push your local copy of the repository to your personal fork
git push --set-upstream origin master
Counting objects: 2941, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (1932/1932), done.
Writing objects: 100% (2941/2941), 4.72 MiB | 4.04 MiB/s, done.
Total 2941 (delta 1951), reused 1485 (delta 746)
remote: Resolving deltas: 100% (1951/1951), completed with 259 local objects.
To https://github.com/crossan007/CRM.git
   7c3f2af86..2c2373dea  master -> master
Branch 'master' set up to track remote branch 'master' from 'origin'.

We cannot guarantee compatibility with future release from personal forks.

In other words, if you modify a file that is also modified in a future release, your changes will be lost.

4. Merging Changes

Master branch is evergreen - only peer reviewed, working code should be merged into master with approval from one or more ChurchCRM Project Maintainers. After code is merged to master, a release should occur within 7 days.

See Pull Request Reviews: https://dev.to/vaidehijoshi/crafting-better-code-reviews

Website - Demo System - Twitter @church_crm

Clone this wiki locally