Commit | Line | Data |
---|---|---|
8b286581 TO |
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. | |
a92c416d | 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` |
8b286581 | 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 |
a92c416d | 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/) |
8b286581 TO |
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. |