.github/CONTRIBUTING.md

   1 CiviCRM is a community-driven open-source project. It has a small,
   2 full-time "core team" which facilitates development and works on critical
   3 issues. However, many improvements are driven by the active contributors.
   4
   5 This document provides important information about how to contribute.
   6
   7 ## Review/Release Process
   8
   9 Releases are developed on a monthly cycle.  At the start of the month, the
  10 release-manager will send an invitation to developers who have open PRs,
  11 encouraging them to participate in the release-cycle.  Participation
  12 provides a way to exchange feedback with other developers, get PRs merged,
  13 and ensure the next release works -- all with a predictable timeline.
  14
  15  * For a high-level summary of the release process, see the
  16    [Release Management README](https://github.com/civicrm/release-management/blob/master/README.md).
  17  * For an example invitation, see the previous [invitation for the April-May 2016](https://github.com/civicrm/release-management/issues/1).
  18
  19 ## Pull-Request Subject
  20
  21 When filing a pull-request, use a descriptive subject. These are good examples:
  22
  23  * `CRM-12345 - Fix Paypal IPNs when moon is at half-crescent (waxing)`
  24  * `(WIP) CRM-67890 - Refactor SMS callback endpoint`
  25  * `(NFC) CRM_Utils_PDF - Improve docblocks`
  26
  27 A few elements to include:
  28
  29  * **CRM-_XXXXX_** - This is a reference to the [CiviCRM issue tracker](http://issues.civicrm.org/)
  30    (JIRA). A bot will setup crosslinks between JIRA and GitHub.
  31  * **Description** - Provide a brief description of what the pull-request does.
  32  * **(WIP)** - "Work in Progress" - If you are still developing a set of
  33    changes, it may be useful to submit a pull-request and flag it as
  34    `(WIP)`. This allows you to have discussion with other developers and
  35    check test results. Once the change is ready, update the subject line
  36    to remove `(WIP)`.
  37  * **(NFC)** - "Non-Functional Change" - Most patches are designed to
  38    change functionality (e.g. fix an error message or add a new button).
  39    However, some changes are non-functional -- e.g. they cleanup the
  40    code-style, improve the comments, or improve the test-suite.
  41
  42 ## Testing
  43
  44 Pull-requests are tested automatically by a build-bot. Key things to know:
  45
  46  * If you are a new contributor, the tests may be placed on hold pending a
  47    cursory review. One of the administrators will post a comment like
  48    `jenkins, ok to test` or `jenkins, add to whitelist`.
  49  * The pull-request will have a colored dot indicating its status:
  50    * **Yellow**: The automated tests are running.
  51    * **Red**: The automated tests have failed.
  52    * **Green**: The automated tests have passed.
  53  * If the automated test fails, click on the red dot to investigate details. Check for information in:
  54    * The initial summary. Ordinarily, this will list test failures and error messages.
  55    * The console output. If the test-suite encountered a significant error (such as a PHP crash),
  56      the key details will only appear in the console.
  57  * Code-style tests are executed first. If the code-style in this patch is inconsistent, the remaining tests will be skipped.
  58  * The primary tests may take 20-120 min to execute. This includes the following suites: `api_v3_AllTests`, `CRM_AllTests`, `Civi\AllTests`, `civicrm-upgrade-test`, and `karma`
  59  * There are a handful of unit tests which are time-sensitive and which fail sporadically. See: https://forum.civicrm.org/index.php?topic=36964.0
  60  * The web test suite (`WebTest_AllTests`) takes several hours to execute. [It runs separately -- after the PR has been merged.](https://test.civicrm.org/job/CiviCRM-WebTest-Matrix/)
  61
  62 For detailed discussion about automated tests, see http://wiki.civicrm.org/confluence/display/CRMDOC/Testing
  63
  64 ## Updating a pull-request
  65
  66 During review, there may be some feedback about problems or additional
  67 changes required for acceptance.  If you've never updated a pull-request
  68 before, see [Stackoverflow: How to update a pull request](http://stackoverflow.com/questions/9790448/how-to-update-a-pull-request).
  69
  70 When you push the update to the pull-request, the test suite will re-execute.