Welcome

Thank you for your interest in contributing to our open source projects. We are so thankful for your willingness to join us. Before you begin, you should take a moment and read the Code of Conduct. The Code of Conduct outlines expectations for each member of the community.

Our community is a group of skilled professionals that are dedicated to leveraging technology for the purpose of delivering the Gospel to every nation. The following guide will cover ways that you can participate in the ongoing work of the community. We are so grateful for your participation and look forward to working with you!

Projects

Here are a few projects that we have been working on:

A website detailing the digital and spiritual landscape of each country in the world.

View Code Visit Site

If you would like to learn more about each project, you can visit each project’s code repository using the View Code buttons above. In each project’s repository you will find:

Code

All of the source code resides on GitHub, and is free for anyone to download and use.

Issues

The Issue Tracker provides the community a place to submit bug reports and feature requests. The community members can also find issues that need help fixing.

Pull Requests

The Pull Requests tab displays all requests to update the codebase. Each pull request will also contain discussions over the requested change and how it impacts the code.

Projects

These are Kanban style boards that track progress on specific tasks that we are trying to complete on the project.

Wiki

The wiki contains project specific documentation, which may include details about setting up a development environment, creating plugin guides, and how to run tests locally.

If you are not familiar with GitHub, you may want to take a moment and browse one of the projects above.

Report a Bug

Our community uses GitHub Issue Tracking to track bug reports related to a project. You should visit the specific project’s code repository to report the bug. See the projects section above. Once there, click on the Issues tab. Before you submit the bug report, you should search the issue tracker for a similar issue. If you are unable to find a similar issue, then:

1. Click on the New Issue button.
2. Click the Get Started button next to Bug Report.

You will be presented with a template that will help guide you through reporting the bug. In order for us to address the issue, we need as much details that you can provide. At the bare minimum, please include the following:

• A title that contains the current date (MM/DD/YYYY) and a brief and concise description of the bug.
• A detailed description of the bug.
• Steps to reproduce the bug.

Once you have provided as much details as possible, and removed any template text that is not used, then click the Submit new issue button.

Request a Feature

Our community uses GitHub Issue Tracking to track feature requests related to a project. You should visit the specific project’s code repository to request a feature. See the projects section above. Once there, click on the Issues tab. Before you submit the feature request, you should search the issue tracker for a similar request. If you are unable to find a similar request, then:

1. Click on the New Issue button.
2. Click the Get Started button next to Feature Request.

You will be presented with a template that will help guide you through requesting the feature. At the bare minimum, please include the following:

• A title that contains the current date (MM/DD/YYYY) and a brief and concise description of the feature.
• A detailed description of the feature.
• A reason why you think we should add the feature.

Once you have provided as much details as possible, and removed any template text that is not used, then click the Submit new issue button.

If a feature request receives no activity for an extended period of time, it will be labeled as Archived.

Ask a Question

Our community uses GitHub Issue Tracking to track questions related to a project. You should visit the specific project’s code repository to ask a question. See the projects section above. Once there, click on the Issues tab.

Before you submit a question, you should do the following:

1. Search the issue tracker for a similar question.
2. Make sure the question has not been asked on StackOverflow.

If it has not been answered, then:

1. Click on the New Issue button.
2. Click the Get Started button next to Questions?.

You will be presented with a template that will help guide you through asking your question. At the bare minimum, please include the following:

• A title that contains the current date (MM/DD/YYYY) and a brief and concise description of the question.
• Your question.

Once you have provided as much details as possible, and removed any template text that is not used, then click the Submit new issue button.

Submit Code

One way you can get involved is by writing some code yourself. The following section will cover the general requirements for submitting code to our projects. For more project specific requirements, you can view the project wiki on GitHub. See the projects section above.

Create a Pull Request

In order to contribute code, we depend on GitHub’s Pull Requests for managing change requests from our community. We will not explain this in detail here, but this is the basic workflow:

1. Select the project that you want to work on.
2. Fork the repository which will create a copy of the repository into your account.
3. Clone your repository onto your local device.
4. Set up the project according to the documentation on the project’s GitHub wiki.
5. Set up the upstream on your local copy, which will point to the project’s original repository.
6. Pull the latest code from the upstream for both the develop and master branches.
7. Create a new descriptively named branch where your work will be done. Your starting branch should be:
   • develop - If you are introducing a feature request or non-critical bug fix.
   • master - If you are posting a critical bug fix. (The issue will be labeled with the critical label)
8. Make your changes. Your changes should follow our Coding Styles, Code Testing, and Code Documentation as outlined below.
9. If you have never contributed to the project, please add your GitHub username and link to your profile in the CONTRIBUTORS.md file.
10. If you are introducing a critical bug fix, you will also need to bump the version number by a patch. The project’s wiki should explain how to bump the version number.
11. Commit your changes.
12. Push your new branch to your fork.
13. Create a Pull Request on the project’s original repository. The branch that you merge into should be:
    • develop - If you are introducing a feature request or non-critical bug fix.
    • master - If you are posting a critical bug fix. (The issue will be labeled with the critical label)

Once you make a pull request, you will want to regularly review your request. We may ask you to make changes, or add more tests. If everything is good, we will accept the pull request. Critical bug fixes are normally deployed immediately after the pull request is merged into the master branch. Feature requests will be deployed on a monthly release cycle.

If you are not familiar with GitHub’s Pull Request workflow, here are some great tutorials to get you started:

• Step-by-step guide to contributing on GitHub
• GitHub - Contributing to a Project
• Try It Out Yourself

Which Branch?

All of our projects use a GitFlow workflow in order to organize the repository branches and manage release versions for the product. The repository contains two main branches:

master

This is the main branch and reflects the production-ready state of the project.

develop

This branch contains the latest development changes for the next release.

When you create a new pull request, it is important to select the correct branch to merge your changes into. If you are patching a critical and breaking bug in the production code, you should merge into the master branch. These issues will be labeled with the critical label. Remember, you will need to bump the version number up a patch before your pull request will be accepted. All other feature requests or bug fixes should be merged in develop. Anything merged into the develop branch will be packaged and released at our next release date. We release on a monthly release cycle. For more details about this branching strategy, check out this article.

Code Styling

As developers, we want to ensure our code is written clean and clear for future developers. In order to ensure the quality of our code, we use linters, static code analysis tools, to check the quality of the code written. These linters compare the code written against language specific standards, also known as coding style guides, and verifies that it conforms to that standard. In the table below, you will see the language specific standards we have decided to implement in our projects. Please get familiar with the standards before submitting code to our projects. Each project will outline how to run the linters on their Github wiki page.

Code Testing

One of the best ways to ensure your code runs correctly all the time, is to back your code with a set of tests. These tests are run every time we receive a pull requests, and push out the latest release. Developers can also run these tests locally in order to ensure the code they are introducing does not break another piece of code. All pull requests must contain at least one test to ensure the code is working properly. Each project will outline which frameworks they use for testing and instructions on how to run the tests in their Github wiki page.

Code Versioning

In order to track the versions of our code, we use the Semantic Versioning technique. Only critical bug fixes will need to change the version number by incrementing it one PATCH. Each project will outline how to increment the versioning in their Github wiki page.

Code Documentation

In order to maintain an understanding of the code and how it works for future development, it is important to correctly document all of the code’s functionality. This allows any developer to assess the purpose of certain functionality and address any concerns in the code. All pull requests require code to be commented. Each project will outline how to comment your code in their Github wiki page.

To insure the free access to our code, we release all of our code under the GNU General Public License (version 3). As part of the licensing requirements, all new files need to include the licensing header comment. All pull requests with new files must add this comment block at the top of the file:

/**
 * This file is part of PROJECT NAME.
 *
 * PROJECT NAME is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * PROJECT NAME is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see
 * <http://www.gnu.org/licenses/>.
 *
 * @author AUTHOR <AUTHOR EMAIL>
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
 *
 */

Please replace PROJECT NAME, AUTHOR, and AUTHOR EMAIL with the correct values.

Pull Request Checklist

Before submitting a pull request, please verify that you have completed the following requirements:

• I have performed a self-review of my own code.
• I have run the project’s linter, and my code has passed.
• I have written at least one test for the new code.
• I have run the tests according to the project’s documentation, and my code has passed the test.
• I have well documented my code so another developer can understand what is happening.
• If I am patching a critical bug, I have correctly bumped the version number.
• I have included the licensing information on all my new files.
• I have added my Github username and profile link to the CONTRIBUTORS.md file of the project.
• I have squashed my commits into as few commits as possible

If everything passes, then you are ready to create your pull request. Happy coding!

Security Issue

If you’ve found a security issue in any of our projects, please use the following procedure instead of using the issue tracker. Please send an email to security [at] missionaldigerati.org (replace the [at] with @) that provides the following information:

• The name of the project
• A detailed description of the security issue
• If available, please provide links to the specific areas in the code that are vulnerable.

We will first try to confirm the issue. Once confirmed, we will work as quickly as possible to fix the problem.

Contact Us

if you have any questions, or need assistance, please send us an email to contribute [at] missionaldigerati.org (replace the [at] with @).