.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 Scope
  20
  21 A good pull request (PR) addresses a clearly-defined problem. There should be a detailed description logged in the [issue tracker](http://issues.civicrm.org/). Excellent PRs also increase test coverage. If you are tempted to do additional tweaks or code cleanup outside the scope of that issue, you could make a separate commit and include them in the PR if they are minor & non-controversial, or create a seperate PR if they are more complex.
  22
  23 There is no size limit for PRs as long as they are focused on completely solving a discreet problem. As a practical matter, though, bigger PRs may take longer to review and merge. When possible, split "epic" issues into bite-sized chunks as long as each seperate PR is functionally complete and does not cause merge conflicts with your other PRs. In the latter case, add commits to an existing PR.
  24
  25 ## Pull-Request Subject
  26
  27 When filing a pull-request, use a descriptive subject. These are good examples:
  28
  29  * `CRM-12345 - Fix Paypal IPNs when moon is at half-crescent (waxing)`
  30  * `(WIP) CRM-67890 - Refactor SMS callback endpoint`
  31  * `(NFC) CRM_Utils_PDF - Improve docblocks`
  32
  33 A few elements to include:
  34
  35  * **CRM-_XXXXX_** - This is a reference to the [CiviCRM issue tracker](http://issues.civicrm.org/)
  36    (JIRA). A bot will setup crosslinks between JIRA and GitHub.
  37  * **Description** - Provide a brief description of what the pull-request does.
  38  * **(WIP)** - "Work in Progress" - If you are still developing a set of
  39    changes, it may be useful to submit a pull-request and flag it as
  40    `(WIP)`. This allows you to have discussion with other developers and
  41    check test results. Once the change is ready, update the subject line
  42    to remove `(WIP)`.
  43  * **(NFC)** - "Non-Functional Change" - Most patches are designed to
  44    change functionality (e.g. fix an error message or add a new button).
  45    However, some changes are non-functional -- e.g. they cleanup the
  46    code-style, improve the comments, or improve the test-suite.
  47
  48 ## Testing
  49
  50 Pull-requests are tested automatically by a build-bot. Key things to know:
  51
  52  * If you are a new contributor, the tests may be placed on hold pending a
  53    cursory review. One of the administrators will post a comment like
  54    `jenkins, ok to test` or `jenkins, add to whitelist`.
  55  * The pull-request will have a colored dot indicating its status:
  56    * **Yellow**: The automated tests are running.
  57    * **Red**: The automated tests have failed.
  58    * **Green**: The automated tests have passed.
  59  * If the automated test fails, click on the red dot to investigate details. Check for information in:
  60    * The initial summary. Ordinarily, this will list test failures and error messages.
  61    * The console output. If the test-suite encountered a significant error (such as a PHP crash),
  62      the key details will only appear in the console.
  63  * Code-style tests are executed first. If the code-style in this patch is inconsistent, the remaining tests will be skipped.
  64  * 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`
  65  * 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
  66  * 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/)
  67
  68 For detailed discussion about automated tests, see http://wiki.civicrm.org/confluence/display/CRMDOC/Testing
  69
  70 ## Updating a pull-request
  71
  72 During review, there may be some feedback about problems or additional
  73 changes required for acceptance.  If you've never updated a pull-request
  74 before, see [Stackoverflow: How to update a pull request](http://stackoverflow.com/questions/9790448/how-to-update-a-pull-request).
  75
  76 When you push the update to the pull-request, the test suite will re-execute.