From 12d6281547028d314ce33f424cefa84e1434c8bd Mon Sep 17 00:00:00 2001
From: Don Hirst <dvhirst@aol.com>
Date: Sat, 9 Sep 2017 15:59:31 -0700
Subject: [PATCH] Update verify-fix.md
Reading for content; editing for consistency.
---
docs/core/verify-fix.md | 152 ++++++++++++----------------------------
1 file changed, 44 insertions(+), 108 deletions(-)
diff --git a/docs/core/verify-fix.md b/docs/core/verify-fix.md
index 4fd4dea7..23c007c2 100644
--- a/docs/core/verify-fix.md
+++ b/docs/core/verify-fix.md
@@ -7,16 +7,11 @@ Suppose you (or some like-minded spirit) report a bug on the [Jira](/tools/issue
## Step 1. Check the "Fix Version" in JIRA
-The JIRA issue includes a field called *Fix Version*. This declares the
-expected release which will include the fix.
+The JIRA issue includes a field called *Fix Version*. This declares the expected release which will include the fix.
-If the fix is low-risk (small) or critical (dealing with data-corruption
-or security), the *Fix Version* will usually be the next point-release.
-Otherwise, the *Fix Version* version will usually be the next
-major-release.
+If the fix is low-risk (small) or critical (dealing with data-corruption or security), the *Fix Version* will usually be the next point-release. Otherwise, the *Fix Version* version will usually be the next major-release.
-However, every patch is evaluated on a case-by-case basis, so it's
-important to read the *Fix Version*.
+However, every patch is evaluated on a case-by-case basis, so it's important to read the *Fix Version*.
!!! summary "Example"
@@ -30,116 +25,74 @@ For an example, see [CRM-16501](https://issues.civicrm.org/jira/browse/CRM-16501
## Step 2. Check the proposal status in Github
-When a developer prepares a fix for an issue, he submits a proposal
-("PR" or "pull-request") via *github.com*. The proposal is evaluated
-using both [continuous integration](/testing/continuous-integration.md) and
-peer review. The proposal will have one of three statuses:
+When a developer prepares a fix for an issue, he submits a proposal ("PR" or "pull-request") via *github.com*. The proposal is evaluated using both [continuous integration](/testing/continuous-integration.md) and peer review. The proposal will have one of three statuses:
-- Open (green): The proposal has not been accepted yet. It's waiting
- for peer review.
+- Open (green): The proposal has not been accepted yet. It's waiting for peer review.
- Merged (purple): The proposal has been accepted.
-- Closed (red): The proposal has been rejected or abandoned. (This may
- happen for a variety of reasons - it could be a problem in the
- proposal itself, or perhaps it took too long to get peer review, or
- perhaps the author came up with a different/better proposal.)
-
-Returning to the example of
-[CRM-16501](https://issues.civicrm.org/jira/browse/CRM-16501),
-the developer (Tim Mallezie) included a link to *github.com:*
-[#5829](https://github.com/civicrm/civicrm-core/pull/5829). Inspecting that
-page, you can see that the status is Merged, and another developer
-(Kurund Jalmi) approved the proposal.
+- Closed (red): The proposal has been rejected or abandoned. (This may happen for a variety of reasons - it could be a problem in the proposal itself, or perhaps it took too long to get peer review, or perhaps the author came up with a different/better proposal.)
+
+Returning to the example of [CRM-16501](https://issues.civicrm.org/jira/browse/CRM-16501), the developer (Tim Mallezie) included a link to *github.com:* [#5829](https://github.com/civicrm/civicrm-core/pull/5829). Inspecting that page, you can see that the status is Merged, and another developer (Kurund Jalmi) approved the proposal.
## Step 3. Try the fixed code
-To be sure that the patch actually works, you'll need try it out. There
-are a few different ways to try it out – the choice will depend on your
-skillset, time/motivation, and the version/status of the fix.
+To be sure that the patch actually works, you'll need try it out. There are a few different ways to try it out – the choice will depend on your skillset, time/motivation, and the version/status of the fix.
-These options are generally sorted by difficulty, with the easiest
-option first.
+These options are generally sorted by difficulty, with the easiest option first.
### Option A. Use the CiviCRM sandbox
- **Summary**:
- - The [CiviCRM sandboxes](https://civicrm.org/sandboxes) are
- public web-sites which are automatically rebuilt once every day.
- The easiest way to test a fix is to try it on the sandbox.
+ - The [CiviCRM sandboxes](https://civicrm.org/sandboxes) are public web-sites which are automatically rebuilt once every day. The easiest way to test a fix is to try it on the sandbox.
- **Required Skills**:
- - No particular skills are required (beyond normal Civi
- user skills).
+ - No particular skills are required (beyond normal Civi user skills).
- **Required Time**:
- - Minimal. Generally 5-15min. Possibly up to an hour if you need
- to reproduce some special configuration options on the sandbox.
+ - Minimal. Generally 5-15min. Possibly up to an hour if you need to reproduce some special configuration options on the sandbox.
- **Timeframe**:
- - You can usually test a fix on the sandbox within 24hr ***after
- the proposal has been approved*** (merged).
- - If the fix was recently approved (ie a few hours ago), then be
- patient and come back tomorrow.
- - If you feel really anxious, you can compare the timestamp for
- when it was merged against [the build history of the sandboxes](https://test.civicrm.org/view/Sites/job/demo.civicrm.org/).
+ - You can usually test a fix on the sandbox within 24hr ***after the proposal has been approved*** (merged).
+ - If the fix was recently approved (ie a few hours ago), then be patient and come back tomorrow.
+ - If you feel really anxious, you can compare the timestamp for when it was merged against [the build history of the sandboxes](https://test.civicrm.org/view/Sites/job/demo.civicrm.org/).
- **Caveats**:
- - This only works ***after*** the proposal has been
- accepted (merged).
- - The automatic rebuild only works with Drupal and
- WordPress sandboxes. At time of writing, the Joomla sandboxes
+ - This only works ***after*** the proposal has been accepted (merged).
+ - The automatic rebuild only works with Drupal and WordPress sandboxes. At time of writing, the Joomla sandboxes
cannot be rebuilt automatically.
- - The sandboxes use fake, generic data with a
- standardized configuration. The data and configuration on your
- server may be different.
- - Outgoing email sending is disabled on all sandboxes to prevent
- accidental spamming etc. So it might not be possible to test
- the email related issues.
+ - The sandboxes use fake, generic data with a standardized configuration. The data and configuration on your
+ server may be different.
+ - Outgoing email sending is disabled on all sandboxes to prevent accidental spamming etc. So it might not be possible to test the email related issues.
### Option B. Install the next release
- **Summary**:
- - Wait for the next release. When it's available, upgrade your
- server (as usual).
+ - Wait for the next release. When it's available, upgrade your server (as usual).
- **Required Skills**:
- CiviCRM system administration
- **Required Time**:
- Moderate. Generally 20-60 min.
- - If you need a major upgrade, have many customizations, or don't
- have much experience with setting up CiviCRM test systems, then
- it may take several hours.
+ - If you need a major upgrade, have many customizations, or don't have much experience with setting up CiviCRM test systems, then it may take several hours.
- **Timeframe**:
- - (For a point release) Point releases may be issued on [the first or third Wednesday of each month](https://civicrm.org/blogs/totten/release-policy-and-new-release-candidates).
- However, this is discretionary, and it may not happen if there
+ - (For a point release) Point releases may be issued on [the first or third Wednesday of each month](https://civicrm.org/blogs/totten/release-policy-and-new-release-candidates). However, this is discretionary, and it may not happen if there
are a small number of fixes. If this matters, ask.
- - (For a major release) Major releases are generally issued every
- 6 months (+/- 3 months). Consult the [CiviCRM Roadmap](https://civicrm.org/roadmap).
+ - (For a major release) Major releases are generally issued every 6 months (+/- 3 months). Consult the [CiviCRM Roadmap](https://civicrm.org/roadmap).
- **Caveats**:
- - This is the slowest process. If the patch doesn't work, then
- you'll need to wait for the next release and try again (minimum:
- 2 weeks. maximum: 9 months).
+ - This is the slowest process. If the patch doesn't work, then you'll need to wait for the next release and try again (minimum: 2 weeks. maximum: 9 months).
### Option C. Install the nightly tarball on a test server
- **Summary**:
- - Set up a test server. Duplicate your CMS+CiviCRM configuration
- on the test server.
+ - Set up a test server. Duplicate your CMS+CiviCRM configuration on the test server.
- Download and install the [latest nightly tarball](https://civicrm.org/blogs/totten/pre-release-policy-and-nightly-builds) from <http://dist.civicrm.org/by-date/latest/>
- **Required Skills**:
- CiviCRM system administration
- Testing / staging / production management
- **Required Time**:
- Moderate. Generally 20-60 min.
- - If you need a major upgrade, have many customizations, or don't
- have much experience with setting up CiviCRM test systems, then
- it may take several hours.
+ - If you need a major upgrade, have many customizations, or don't have much experience with setting up CiviCRM test systems, then it may take several hours.
- **Timeframe**:
- - You can usually test a nightly tarball within 24hr ***after the
- proposal has been approved*** (merged).
- - If the fix was recently approved (ie a few hours ago), then be
- patient and come back tomorrow.
- - If you feel really anxious, you can compare the timestamp for
- when it was merged against the timestamp on *dist* server.
+ - You can usually test a nightly tarball within 24hr ***after the proposal has been approved*** (merged).
+ - If the fix was recently approved (ie a few hours ago), then be patient and come back tomorrow.
+ - If you feel really anxious, you can compare the timestamp for when it was merged against the timestamp on *dist* server.
- **Caveats**:
- - This only works ***after*** the proposal has been
- accepted (merged).
- - Do not install nightly tarballs on production servers. For more
- discussion of why, see the original blog post, [Pre-Release Policy and Nightly Builds](https://civicrm.org/blogs/totten/pre-release-policy-and-nightly-builds).
+ - This only works ***after*** the proposal has been accepted (merged).
+ - Do not install nightly tarballs on production servers. For more discussion of why, see the original blog post, [Pre-Release Policy and Nightly Builds](https://civicrm.org/blogs/totten/pre-release-policy-and-nightly-builds).
!!! tip
@@ -162,31 +115,19 @@ option first.
- **Required Time**:
- Moderate. Generally 20-60 min.
- **Timeframe**:
- - You can download patches as soon as they are **proposed**. This
- means you can try new patches **before** they've been reviewed
- or approved.
+ - You can download patches as soon as they are **proposed**. This means you can try new patches **before** they've been reviewed or approved.
- **Caveats**:
- - Patches do not always apply cleanly. For example, if there is a
- big gap in the versions (eg your test system is 4.6.0 and the
- *Fix Version* is 4.6.5), or if the patch is large, then there's
- an increased risk that minutiae will prevent the patch from
- loading on your system.
- - Patches may have hidden dependencies. For example, patch #456
- may only work correctly if patch #123 is also loaded. This risk
- can only be assessed on a case-by-case basis.
+ - Patches do not always apply cleanly. For example, if there is a big gap in the versions (e.g., your test system is 4.6.0 and the *Fix Version* is 4.6.5), or if the patch is large, then there's an increased risk that minutiae will prevent the patch from loading on your system.
+ - Patches may have hidden dependencies. For example, patch #456 may only work correctly if patch #123 is also loaded. This risk can only be assessed on a case-by-case basis.
### Option E. Setup a developer system and checkout the patch
- ****Summary**:**
- - Active core contributors setup a development system optimized
- for evaluating new patches.
- - Install <https://buildkit.civicrm.org/> (aka
- <https://github.com/civicrm/civicrm-buildkit>) on a developer
- workstation
- - Create a test site with
- [civibuild](https://github.com/civicrm/civicrm-buildkit/blob/master/doc/civibuild.md)
- using the closest matching git branch. (For example, if the *Fix
- Version* is "4.6.3", then the closest branch is "4.6".)
+ - Active core contributors setup a development system optimized for evaluating new patches.
+ - Install <https://buildkit.civicrm.org/> (aka <https://github.com/civicrm/civicrm-buildkit>) on a developer
+ workstation
+ - Create a test site with [civibuild](https://github.com/civicrm/civicrm-buildkit/blob/master/doc/civibuild.md)
+ using the closest matching git branch. (For example, if the *Fix Version* is "4.6.3", then the closest branch is "4.6".)
- Example: *civibuild create d46 --url <http://d46.localhost>*
- (If the proposal has not been approved) Checkout the proposal
- Example: *cd build/d46/sites/all/modules/civicrm; hub
@@ -197,16 +138,11 @@ option first.
- Git-based source-code management
- Unix/Linux (CLI) system administration
- **Required Time**:
- - (Initial setup) Generally, 30min - 4 hours. (Depending on
- environment and experience level.)
+ - (Initial setup) Generally, 30min - 4 hours. (Depending on environment and experience level.)
- (Subsequent tests) Generally, 10-30 min.
- **Timeframe**:
- - You can download patches as soon as they are **proposed**. This
- means you can try new patches **before** they've been reviewed
- or approved.
+ - You can download patches as soon as they are **proposed**. This means you can try new patches **before** they've been reviewed or approved.
- **Caveats**:
- Not supported on Windows. Use a Linux VM.
- - If you use a MySQL/Apache bundle (such as MAMP or XAMPP), you
- may need to do extra configuration to enable scripting of the
- CLI environment.
+ - If you use a MySQL/Apache bundle (such as MAMP or XAMPP), you may need to do extra configuration to enable scripting of the CLI environment.
- If you get stuck, reach out on [Mattermost](https://chat.civicrm.org)
--
GitLab