Contributing to SuiteCRM

From SuiteCRM Documentation
Jump to: navigation, search

Contributing to SuiteCRM

Contents

How to Contribute

We want everyone to be able to contribute to SuiteCRM regardless of what technical knowledge they may possess. Whether your a non-tech savvy consumer, a graduate seeking a new project to dabble in, or a veteran developer – all are welcome to maintain our title of the world's best open source CRM!

Issue raising

An issue is an area where you can feel the project could be improved, for example, you could report a problem or bug you've encountered while using the software, a feature you feel is missing, or a gap in the project's documentation.

When raising issues via our GitHub repository ensure you state the issue clearly with a full description of steps to reproduce, what version(s) of SuiteCRM the issue was found in and; if relevant what platform it is running on and a screenshot of the issue. This will allow any contributor to easily identify and potentially address the issue. Here is the GitHub guide to all things issues.

Good example of a raised issue:

https://github.com/salesagility/SuiteCRM/issues/1519

Security

We take Security seriously here at SuiteCRM so if you have discovered a security risk report it by emailing security@suitecrm.com. This will be delivered to the product team who handle security issues. Please don't disclose security bugs publicly until they have been handled by the security team.

Your email will be acknowledged within 24 hours during the business week (Mon - Fri), and you’ll receive a more detailed response to your email within 72 hours during the business week (Mon - Fri) indicating the next steps in handling your report.

Labelling

We have a number of labels that we tag issues with to define it's type, priority, and action.

Type:

  • bug
  • duplicate
  • enhancement
  • invalid
  • question
  • suggestion

Priority:

  • Low Priority
  • Medium Priority
  • High Priority

Action:

  • Resolved: Next Release
  • Fixed Proposed
  • Merged
  • On Roadmap
  • Pending Input
  • Wrong Branch
  • Review

We encourage users whom feel an issue should be raised as a higher priority for a next release that they should make a comment to that affect. This also applies to incorrect labelling.

Providing a Bug Fix

To provide a code contribution for an issue you will need to set up your own fork of the SuiteCRM repository, make your code changes, commit the changes and make a Pull Request to the appropriate branch on the SuiteCM repository. See our Quick Guide to Fork SuiteCRM. Once you have set up your forked repository you can begin making commits to the project.

Separate each issue fix into a new branch in your repository (from the hotfix-7.8.x branch) and name it with the issue ID e.g. bugfix_3062 or issue-1234.

When committing to your individual bugfix branch follow the message format below.

Fixed #1234 - <the subject of the issue>

e.g of a commit command

$ git commit -m "Fixed #1436 - Reports with nested Parentheses are removing parameters"

This commit message format allows us to easily include all bug fixes within major and minor release notes.

If you are new to Writing Commit Messages in git follow the guide here

Make a Bug Fix Pull Request

After you have made your commits and pushed them up to your forked repository you then create a Pull Request to be reviewed and merged into the SuiteCRM repository. Make a new Pull Request for each issue you fix – do not combine multiple bugfixes into one Pull Request.

Ensure that in your Pull Request that the base fork is salesagility/SuiteCRM and base branch is hotfix-7.8.x and the head fork is your repository and the base branch is your unique bugfix branch e.g. bugfix_1234

We will automatically reject any Pull Requests made to the wrong branch!

CLA Check

If you have not signed our CLA (Contributor License Agreement) then your Pull Request will fail a check and unable to be merged into the project. You will only required to sign this once.

Travis CI

When a new Pull Request is opened, Travis CI will test the merging of the origin and upstream branch and update the Pull Request. If this check fails you can review the test results and resolve accordingly. To test prior to making a Pull Request install PHPUnit via composer into your develop environment then cd into the tests directory and run:

$ sh runtests.sh

Providing a Feature

To contribute a feature to SuiteCRM, similar to providing a Bug Fix, you must create a forked repository of SuiteCRM and set up your git and development environment.

Once done, create a new branch from develop and name it relevant to the feature's propose e.g campaign-wizard-ui. Following our Code Standards develop the new feature and ensure your forked repository is kept up to date with minor/major releases. See our Quick Guide to Fork SuiteCRM to update your repository.

Make sure your commit messages are relevant and descriptive. When ready to submit for review make a Pull Request detailing your feature's functionality.

Ensure that in your Pull Request that the base fork is salesagility/SuiteCRM and base branch is develop and the head fork is your repository and the base branch is your feature branch.

Add any new PHPUnit tests to the new feature branch if required e.g new modules or classes.


Reviewing Features

We will review the code and provide feedback within the Pull Request and issues relating to your feature. If the feature is to be included in the core product we will request for the forked repo to have an Issues tab so we can raise any bugs from our testing. This will also allow you to fix those issues using the below commit message format similar to how to submit bug fixes to the hotfix-7.8.x branch.

$ git commit -m "Fixed #1436 - Reports with nested Parentheses are removing parameters"

Note*** You can add an Issues tab to your forked repository via the 'Settings' tab.



New features that have been accepted and merged will be included in the next suitable Major release of the project for e.g 7.7 or 7.8 are major releases. Minor releases only include bug fixes or in-house features developed e.g 7.6.5 or 7.7.1 would be minor releases.

Quick Guide to Fork SuiteCRM

Fork the SuiteCRM repository

You can do this entirely from the github website. See Forking Git to learn how.

Setup Git on your local machine

Follow the guide produced by Github, which provides detailed instructions on setting up git and connecting to Github from your local machine.

Clone your repository on your local machine

With git setup and your Github fork created, we can now clone the git repository to our local machine. Change to the directory you wish to do this at, and issue this command to clone the SuiteCRM repository ( changing username for your username in Github )

$ git clone git@github.com:username/SuiteCRM.git

Now that we have cloned the repository locally, we next need to setup the remote repositories that this repository will reference. By default, git creates the origin remote, which points to the fork you created on github (https://github.com/username/SuiteCRM) . However, in order to stay up to date with the changes to the parent repository (https://github.com/salesagility/SuiteCRM) you'll want to setup the upstream remote as well. Here's how:

$ cd SuiteCRM
$ git remote add upstream git://github.com/salesagility/SuiteCRM
$ git fetch upstream

Now anytime you want to update your forked branch it's a simple process. Just change to the branch you want to update from the upstream ( for example, the master branch ) and then issue the commands below:

$ git checkout master
$ git fetch upstream
$ git merge upstream/master
$ git push origin master

These commands will pull down the latest changes from the upstream repo (https://github.com/salesagility/SuiteCRM) to your local repo, then merge the changes into your local clone's master branch, and finally push those changes back up to your fork's repository on Github. This is key to keep your master, hotfix, and develop up to date after a minor and major release.

Code of Conduct

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.


Examples of behaviour that contributes to creating a positive environment include:

  • Using welcoming and inclusive language
  • Being respectful of differing viewpoints and experiences
  • Gracefully accepting constructive criticism
  • Focusing on what is best for the community in a professional manner
  • Showing empathy towards other community members


Examples of unacceptable behaviour by participants include:

  • The use of sexualized language or imagery and unwelcome sexual attention or advances
  • Trolling, insulting/derogatory comments, and personal or political attacks
  • Public or private harassment
  • Publishing others' private information, such as a physical or electronic address, without explicit permission
  • Other conduct which could reasonably be considered inappropriate in a professional setting


The SuiteCRM project maintainers are responsible for clarifying the standards of acceptable behaviour and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behaviour. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.


The SuiteCRM project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviours that they deem inappropriate, threatening, offensive, or harmful.


This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, within project forums, posting via an official social media account, or acting as an appointed representative at an online or offline event.


Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported by contacting the project team at community@suitecrm.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.


This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at version