Merge pull request #724 from JoeMurray/master

provided best practice advice on report extension creation

docs/extensions/civix.md

@@ -354,9 +354,11 @@ To include static resources such as stylesheets, Javascript files, or images pla
 
 ### Add a report {:#generate-report}
 
-CiviReport enables developers to define new business reports using customizable SQL logic and form layouts. If another existing report is close to your needs you may copy and modify it.
+CiviReport enables developers to define new business reports using customizable SQL logic and form layouts. This command is available if you want to create a new report. It also provides an option, if another existing report is close to your needs, to easily copy and modify it.
 
-To to see the available report generation options activate the `civix` help:
+In many cases you can take advantage of the [alterReportVar hook](/hooks/hook_civicrm_alterReportVar) to adjust the columns, sql, or event rows of an existing report to modify it to suit your needs instead of creating a new report. 
+
+To see the available report generation options activate the `civix` help:
 
 ```bash
 civix generate:report --help
@@ -383,6 +385,9 @@ For example, this command will copy the activity report in the class `CRM_Report
 civix generate:report --copy CRM_Report_Form_Activity MyActivity Contact
 ```
 
+!!! note
+    Copying a report like this and modifying it is likely to lead to maintenance issues similar to those related to overriding core files in an extension. In particular, bug fixes or other changes to code that you have copied will not automatically be applied to the copied code your new report. Often a better approach is to extend the class of the core report in your extension (eg `CRM_myExtension_Form_Report_ExtendContributionDetails` extends `CRM_Report_Form_Contribute_Detail`), then selectively override its functions. In the functions that you override, if possible run the original code and then just tweak the behaviour afterwards, i.e: at the beginning of `thisFn()`, call `parent::thisFn()` then add your code.
+
 ### Add a custom search {:#generate-search}
 
 CiviCRM enables developers to define new search forms using customizable SQL logic and form layouts. Use this command to get started: