Skip to content

Contributing

Jump to bottom
phili67 edited this page Dec 7, 2017 · 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. If you plan on developing the applicaion, install vagrant or sign up for Cloud9 so you can test your changes in a safe environment.
  4. Introduce yourself in the developer chat at https://gitter.im/ChurchCRM/CRM
  5. Take a look at the Open Issues page. We've made it easy for beginners with the Good First Bug Label - these are issues that should be relatively easy to fix.
  6. 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 testing documentation

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

3. Submitting changes

a. Genuine User Interface (GUI)

  • When you're sure that the functionality(ies), you will introduce, aren't breaking something or introducing a more complex workflow for the user, you can add your PR to the community.

  • Don't forget the rules, more than three clicks lose the user.

  • If you introduce a code that will take a more complex comprehension for the user to do the same thing will lose the user.

  • We are working with real time application, so reflecting the result when you reload the page nor after more than 5 seconds isn't really a feature for the user but a backward.

  • Focus ever on user friendly application and user friendly code, it's nice that another new contributor could understand what was done.

Don't forget to add tooltip everywhere and comment in the code, comprehension in the CRM nor for the new contributors is a main point.

Our goal is to have the easier CRM of the world to manage a church. Last : focus on the user and only the user.

b. CODING part

  • If the goal of your PR is to change the kernel, don't forget that all the code above are really fit the last kernel. It's potentially many bugs at the end in many parts of ChurchCRM and many things to corrected, and for nothing (because the user couldn't see the reflected changes). So our goal is to involve the kernel to increase the functionalities of ChurchCRM or to stabilise the CRM.

  • We're focusing to involve the functionalities and to correct bugs they will introduce and not to introduce new one with only kernel 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 maintiainers.

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.

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 (TEAM part)

  • Don't forget before merging that a contributor has tested his own code a long time, so modifying a code just before merging it, is potentially a very big chance of breaking the code nor to introduce a bug. So the rule should be : never changing a code just before merging it.

  • When the code doesn't really fit the team, it could decide not to merging it or to merge it and after to add a new PR to fit the will of the team.

  • "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