Merge pull request #516 from totten/master-civix-up

Add pointers to civix upgrade instructions

docs/extensions/civix.md

@@ -22,7 +22,7 @@ Help is available on individual commands, e.g.,:
 civix help civicrm:ping
 ```
 
-## Generating a skeletal extension {:#generate-module}
+## Generate a skeletal extension {:#generate-module}
 
 To generate a skeletal extension module, we will use `civix generate:module` and pass in the name for our extension. See [here](/extensions/index.md#extension-names) for details of naming conventions.
 
@@ -489,3 +489,13 @@ The skeletal test class does not do anything useful. For more details on how to
 
 To run the tests see the instructions [for running PHPUnit tests](/testing/phpunit.md#running-tests).
 
+## Upgrade civix {:#upgrade}
+
+What happens when a new version of `civix` comes out? Your extension should continue to work as-is -- after all, `civix` is just a code-generator.
+
+However, if you generate an extension with one version of `civix` (e.g. v16.03), and if you upgrade (e.g. v18.03), and if you run a new generator,
+then you *could* encounter problems. This is because generators and templates evolve over time -- in particular, new templates may rely on new
+helpers and stubs in `<mymodule>.php` and `<mymodule>.civix.php`.
+
+Fortunately, these changes are rare; they tend to have limited impact; and there's documentation for them. From time-to-time, you should check
+[UPGRADE.md](https://github.com/totten/civix/blob/master/UPGRADE.md) for suggestions on updating your code to match the current templates.

docs/extensions/troubleshooting.md

@@ -24,3 +24,8 @@ Q: I've tried to generate a page/report/search/upgrader/etc with civix but it's
 
 A: For all of the various types, you must first run [generate:module](http://generatemodule), and then \`cd\` into the folder (e.g. com.example.myextension) before running one of the other \`generate:\` commands.
 
+## Out-of-date templates
+
+Many of the generators in `civix` rely on helpers and stubs defined in `<mymodule>.php` or `<mymodule>.civix.php`. If you
+run `civix generate:*` on an older extension and have trouble with the generated code, then review [UPGRADE.md](https://github.com/totten/civix/blob/master/UPGRADE.md)
+for (a) general upgrade procedures and (b) a list of specific changes that could require manual attention.

docs/tools/buildkit.md

@@ -218,4 +218,7 @@ git pull
 
 See the [buildkit changelog](https://github.com/civicrm/civicrm-buildkit/blob/master/CHANGELOG.md) for info about specific changes to buildkit.
 
+!!! tip "When upgrading `civix`, check upgrade instructions."
 
+    If you see an upgrade to `civix` in the changelog, and if you maintain extensions with `civix`,
+    then check the general [civix upgrade documentation](/extensions/civix.md#upgrade-templates) and [UPGRADE.md](https://github.com/totten/civix/blob/master/UPGRADE.md).