docs/basics/skills.md

@@ -14,7 +14,7 @@ other technologies (such as PHP and Git, which are not CiviCRM-specific) are out
 -   **PHP** - the main programming language in which CiviCRM is written.
     -   [Language reference](http://php.net/manual/en/langref.php)
 -   **Git, GitHub, and GitLab** - Git is a version control system for tracking changes to source code. GitHub and GitLab are web-based tools which host git repositories and issue-tracking systems.
-    -   See [our recommended external resources](/tools/git.md#resources)
+    -   See [our recommended external resources](../tools/git.md#resources)
 -   **Command line / bash** - in general, "the command line" refers to using a text-only interface to run programs such as `civix`, `git`, and many more. Bash is the most common "shell" program used to execute these commands on Unix computers (i.e. Linux and OS X).
     -   [Unix command line tutorial](http://www.ee.surrey.ac.uk/Teaching/Unix/)
     -   *Microsoft Windows has a command line shell which functions very differently from bash. While developing CiviCRM on Windows is possible, it will be a slightly more uphill battle, for this reason and others.*

docs/core/contributing.md

 # How to contribute
 
-This chapter assumes that you have identified a bug or improvement for CiviCRM where the best resolution is to [write and contribute code to core](/core/hacking.md).
+This chapter assumes that you have identified a bug or improvement for CiviCRM where the best resolution is to [write and contribute code to core](hacking.md).
 
 !!! note
 
-    This chapter will refer to a number of resources that are explained in greater depth in the [Developer Community](/basics/community.md) chapter.
+    This chapter will refer to a number of resources that are explained in greater depth in the [Developer Community](../basics/community.md) chapter.
 
 
 ## Create an issue
 
-Creating a good issue is an important first step and often involves research, discussion, and thoughtful description.
+Creating a good issue is an important first step and often involves research, discussion, and thoughtful description.  Identify your "use case" and share the budget and/or skills you plan on contributing.
 
-[Following these comprehensive steps](/tools/issue-tracking.md#guidelines) to create your issue.
+[Following these comprehensive steps](../tools/issue-tracking.md#guidelines) to create your issue.
 
 ## Document your change
 
-Your changes might require documentation updates. Read about [when to document](/documentation/index.md#when) and [how to document](/documentation/index.md#contributing) and follow steps as necessary.
+Your changes might require documentation updates. Read about [when to document](../documentation/index.md#when) and [how to document](../documentation/index.md#contributing) and follow steps as necessary.
 
 ## Write tests
 
 Before you write any code you should write tests. You can use your plain-language description of how things should work to create automated tests for the feature.
   
-CiviCRM comes with a variety of [testing tools](/testing/index.md) that help ensure that changes don't break existing functionality. Since CiviCRM [doesn't release code with failing tests](/tools/jenkins.md), your bug or improvement must not be covered in the existing tests.  Maybe there are incomplete tests, maybe the tests aren't valid measures of the functionality, or maybe your feature lacks test coverage.  Either way, you will need to write them to make sure your work doesn't get undermined by future changes.
+CiviCRM comes with a variety of [testing tools](../testing/index.md) that help ensure that changes don't break existing functionality. Since CiviCRM [doesn't release code with failing tests](../tools/jenkins.md), your bug or improvement must not be covered in the existing tests.  Maybe there are incomplete tests, maybe the tests aren't valid measures of the functionality, or maybe your feature lacks test coverage.  Either way, you will need to write them to make sure your work doesn't get undermined by future changes.
 
 Use your documentation to identify tests that can be run, and then write them.  If you are adding functionality, you may not have the code that the test will call, but you can write your tests as if all the pages and functions exist, defining them later.
 
@@ -33,23 +33,23 @@ The key in making changes is legibility: helping others see what you've changed
 
 ### Coding style
 
-One element of legibility is literal: make your changes according to the [CiviCRM coding standards](/standards/index.md).  This doesn't just make the code more readable on its own; standards make the `diff` more legible too.
+One element of legibility is literal: make your changes according to the [CiviCRM coding standards](../standards/index.md).  This doesn't just make the code more readable on its own; standards make the `diff` more legible too.
 
-Each pull request is [automatically tested](/tools/jenkins.md) by `PHP_CodeSniffer` according to [the standards](https://github.com/civicrm/coder), and you should save time and test your code yourself.
+Each pull request is [automatically tested](../tools/jenkins.md) by `PHP_CodeSniffer` according to [the standards](https://github.com/civicrm/coder), and you should save time and test your code yourself.
 
 ### Making commits
 
-Follow these steps to [make high-quality commits](/tools/git.md#committing).
+Follow these steps to [make high-quality commits](../tools/git.md#committing).
 
 Once you've completed the work, revisit your documentation and tests to see if you've missed anything.
 
 ## Open a pull request
 
-Read about [creating a pull request](/tools/git.md#pr) which includes information on writing a good subject line and minding the scope of your PR.
+Read about [creating a pull request](../tools/git.md#pr) which includes information on writing a good subject line and minding the scope of your PR.
 
-Once you submit your pull request, CiviCRM's [Jenkins server](/tools/jenkins.md) will build a copy of CiviCRM and run tests against it, beginning with `PHP_CodeSniffer`.  If tests fail, you will be able to follow a link to view details.
+Once you submit your pull request, CiviCRM's [Jenkins server](../tools/jenkins.md) will build a copy of CiviCRM and run tests against it, beginning with `PHP_CodeSniffer`.  If tests fail, you will be able to follow a link to view details.
 
-Other developers may comment on your code, raising questions or concerns or marking the changes as approved.  This is fine, but it is important not to hide important discussion.  If substantive discussion occurs in a pull request, note it in Jira.  If a pull request is closed in favor of another, explain that in Jira and mention the old pull request in the new one.
+Other developers may comment on your code, raising questions or concerns or marking the changes as approved.  This is fine, but it is important not to hide important discussion.  If substantive discussion occurs in a pull request which has a separate ticket, make note of the discussion in the ticket.  If a pull request is closed in favor of another, explain that in the ticket and mention the old pull request in the new one.
 
 The goal is that the next person working on this feature area shouldn't have to do a lot of archeology to figure out the motivations, concerns, and impact of your changes.
 
@@ -57,12 +57,12 @@ The goal is that the next person working on this feature area shouldn't have to
 
 While your pull request is reviewed, and even after it is merged, you will need to maintain your code on the site that needed the changes.  There are two main techniques for this.
 
-First, you can keep your `civicrm` directory under version control, including your changes there.  If you need to upgrade while your changes are still in review, [rebase](/tools/git.md#rebase) your changes on top of the new version.
+First, you can keep your `civicrm` directory under version control, including your changes there.  If you need to upgrade while your changes are still in review, [rebase](../tools/git.md#rebase) your changes on top of the new version.
 
 Alternatively, you can use a custom PHP or template override directory.  While this is generally discouraged for long-term customizations of your site (extensions are better), it can be an efficient way to track short-term overrides.  Just declare the path to the custom PHP and template folders in the Administer - System Settings - Directories page and copy your changed file(s) there, placing them under the same directory structure as within the `civicrm-core` repository.  Note the issue number and pull request in a comment at the top of each file, and remember to check the directory each time you upgrade.  Once your change is merged, just delete the override.
 
 ## Review some other code
 
-CiviCRM works through the generosity of its users and the organizations that employ them.  Now that you have a pull request open (and some experience working with the CiviCRM codebase), why not take some time to [review another pull request](/core/pr-review.md)?  
+CiviCRM works through the generosity of its users and the organizations that employ them.  Now that you have a pull request open (and some experience working with the CiviCRM codebase), why not take some time to [review another pull request](pr-review.md)?  
 
-Pick one from the list of open pull requests, review the corresponding Jira ticket, merge the changes into your development copy of CiviCRM, and see how it works.  Share your thoughts on the pull request.  You'll notice that the time you spend reviewing others' code and interacting with the rest of the community will serve you well: you'll be a better CiviCRM developer, and you'll have a better product.
+You'll notice that the time you spend reviewing others' code and interacting with the rest of the community will serve you well: you'll be a better CiviCRM developer, and you'll have a better product.

docs/core/dependencies.md

+# Core Dependencies (Libraries)
+
+The ***core dependencies*** are the software libraries loaded by `civicrm-core` (and distributed alongside
+`civicrm-core`).  These include server-side PHP libraries (such as Symfony Dispatcher) and client-side libraries (such
+as jQuery).
+
+Core dependencies are organized in two areas: [the newer `composer.json` (*preferred*)](#composer) and [the older
+`civicrm-packages.git` (*deprecated*)](#packages).
+
+??? question "How do the _Core Dependencies_ differ from the _Installation Requirements_ or the _Toolchain_?"
+
+    The words "dependency" and "requirement" are similar, but the following are technically distinct areas:
+
+    * The _core dependencies_ (such as jQuery and Symfony Dispatcher) are libraries that must be loaded by CiviCRM at runtime.
+    * The [_installation requirements_](https://docs.civicrm.org/installation/en/latest/general/requirements/) (such as PHP and MySQL) are pre-requisites that a system-builder must provide before installing CiviCRM.
+    * A [_toolchain_](../tools/buildkit.md) is a set of add-on tools (such as `drush` and `phpunit`) used to build the software. These are important for system-builders
+      and developers, but they are not loaded by CiviCRM at runtime.
+
+    This page focuses on the core dependencies (libraries).
+
+<!-- What about npm's `package.json`? This is only used to download some QA tools -- not for core-dependencies. -->
+
+## Principles
+
+??? info "Core dependencies must have broad compatibility..."
+
+    They should work with all supported PHP versions and all UF's/CMS's (Drupal 7/8/9/10, WordPress,
+    Backdrop, Joomla, Standalone).
+
+??? info "Core dependencies may (or may not) be systemically important..."
+
+    * __Example 1__: Symfony Dispatcher defines the `EventSubscriberInterface` which appears in CiviCRM developer documentation and downstream
+    extensions.  Changes to Symfony Dispatcher could affect downstream compatibility, so they should be reviewed carefully. This is
+    systemically important.
+
+    * __Example 2__: `marcj/topsort` is only used internally. CiviCRM could update this library without any downstream impact.
+
+    This must be assessed on a case-by-case basis.
+
+??? info "Patches to core dependencies should be minimized..."
+
+    It is _possible_ to apply our own patches on top of core dependencies (without upstream review). The wisdom of doing
+    so depends on the severity of the issue and the health of the upstream project.
+
+    In general, if upstream is active, then patches should be reviewed, revised, and released in their upstream's workflow.
+
+    However, if a patch is critical to compatibility or security, or if upstream is not maintained, then CiviCRM may
+    apply its own patch (until the issue is resolved upstream).
+
+## Composer.json {:#composer}
+
+[`composer`](https://getcomposer.org/) is the primary tool for managing CiviCRM's _core dependencies_.  It is popular for PHP-based projects, and
+you'll find ample resources online (such as [official documentation](https://getcomposer.org/doc/) and [unofficial
+discussions](https://stackoverflow.com/questions/tagged/composer-php)).
+
+For `civicrm-core`, there are some additional tips and guidelines for how to approach `composer`:
+
+<a id="composer-jscss"></a>
+??? info "Composer handles PHP libraries... and also JS/CSS libraries..."
+
+    As you may expect, `composer` downloads PHP libraries. In `composer.json`, these appear in the usual section (`"require":...`).
+
+    What you may not expect: it also handles JS/CSS libraries. By convention:
+    
+    * JS/CSS dependencies are declared in `composer.json` underneath `"extra": {"download":{...}}`. 
+      (See also: [civicrm/composer-downloads-plugin](https://github.com/civicrm/composer-downloads-plugin))
+    * JS/CSS dependencies are downloaded into the folder `bower_components/`.
+
+    Historically (circa v4.6), the JS/CSS libraries were downloaded via `node`/`bower`.  It was subsequently simplified (circa v5.17) to use a
+    lighter and more maintainable toolchain. The folder-name was preserved within 5.x for interoperability.
+
+<a id="composer-patches"></a>
+??? info "Composer applies patches for third-party libraries..."    
+
+    Core dependencies sometimes require patches for compatibility or security. When necessary, these patches
+    are applied via [cweagans/composer-patches](https://github.com/cweagans/composer-patches/). These patches
+    are declared `composer.json` under `"extra":{"patches":{...}}`
+    
+    Patches must be identified with an absolute URL. This ensures compatibility with all environments, including
+    D7-style (*civicrm as main project*) and D8-style (*civicrm as subordinate project*).
+    
+    Patch URLs should identify immutable content (with some version#, checksum, or UUID). This ensures that
+    consistency in tests/releases/quality-control.
+    
+    Here are a few ways to make a suitable URL:
+
+    1. Paste the patch into a gist. Use the URL of the raw gist. Or...,
+    2. Send a PR upstream. Get it approved. Use the URL of the PR-diff. Or...,
+    3. Get a link to a historical patch-file that was previously bundled into civicrm-core.git. (Not applicable to new patches.)
+
+??? info "CiviCRM might be the _main composer project_ (D7/WP/BD/J)..."
+
+    In Drupal 7, WordPress, Backdrop, and Joomla, site-builders do not traditionally run `composer` themselves.
+
+    For these environments, `civicrm-core` has its own `composer` project. This means:
+
+    * CiviCRM has complete and final discretion in how dependencies are resolved.
+    * The `composer.lock` from `civicrm-core` is authoritative.
+    * All options in `composer.json` (such as post-install scripts) are fully respected.
+
+??? info "CiviCRM might be a _subordinate composer project_ (D8/D9/D10)..."
+
+    In Drupal 8 (and newer), site-builders typically run `composer` themselves. There is a pre-existing project, and
+    CiviCRM is usually added into this project:
+
+    ```bash
+    cd /var/www/my-drupal-site
+    composer require civicrm/civicrm-core ...
+    ```
+
+    For these environments, `civicrm-core` is subordinate:
+
+    * The site-builder has final discretion in how dependencies are resolved.
+    * The `composer.lock` from `civicrm-core` is ignored.
+    * Some options in `composer.json` (such as post-install scripts) are ignored.
+
+## CiviCRM-Packages {:#packages}
+
+Since CiviCRM v1.x, the `packages/` folder has stored a collection of manually curated dependencies.  The folder
+corresponds to a git repository ([`civicrm-packages.git`](https://github.com/civicrm/civicrm-packages/)).
+
+Adding new code to `packages/` is generally deprecated, and many dependencies have switched to `composer.json`.
+However, some important dependencies are still tracked in `packages/`. 
+
+??? question "Why would a dependency still reside in `civicrm-packages`?"
+
+    Each package may be different. Here are a few possible reasons:
+
+    1. Nobody has gotten around to converting it.
+    2. The dependency is no longer maintained by upstream. It is easier to do security and compatibility updates in this repo.
+    3. The dependency requires special loading rules or special conditions.
+    4. The dependency's file-path is important. Moving it requires coordination with other repositories/subsystems.
+
+For more information about managing the `packages/` folder, see [civicrm-packages.git:VERSIONS](https://github.com/civicrm/civicrm-packages/blob/master/VERSIONS.php)

docs/core/hacking.md

@@ -5,7 +5,7 @@
 
 To help you decide, here are a couple of principles:
 
-- Bug fixes should always be applied to core.  See [Contributing to Core](/core/contributing.md) for details.
+- Bug fixes should always be applied to core.  See [Contributing to Core](contributing.md) for details.
 - Some (but not all) enhancements to existing features may be best applied to core, especially if they would be useful to others.
-- New features should generally be packed as [Extensions](/extensions/index.md).
-- If you aren't familiar with CiviCRM, by far the best way to get a sense if you should be editing core is by [talking with the CiviCRM developer community](/basics/community.md#collaboration-tools).
+- New features should generally be packed as [Extensions](../extensions/index.md).
+- If you aren't familiar with CiviCRM, by far the best way to get a sense if you should be editing core is by [talking with the CiviCRM developer community](../basics/community.md#collaboration-tools).

docs/core/pr-review.md

 # How to review a core pull request
 
-When someone [opens a pull request](/tools/git.md#pr) (aka "PR") on CiviCRM Core, it must be reviewed before we can merge it. Reviewing core PRs is a useful (and often much-needed) way of contributing to CiviCRM. You do not need any special access or merge rights. What you do need, is...
+When someone [opens a pull request](../tools/git.md#pr) (aka "PR") on CiviCRM Core, it must be reviewed before we can merge it. Reviewing core PRs is a useful (and often much-needed) way of contributing to CiviCRM. You do not need any special access or merge rights. What you do need, is...
 
 * [GitHub Account](https://github.com)
 * A [CiviCRM Development Environment](https://github.com/civicrm/civicrm-buildkit/blob/master/doc/civibuild.md) (this might be optional, but good to have). One benefit is the ability to check out the PR in your environment.
 * Comfort reading code and patches
 
-Follow the remaining the steps below to review a pull request.
+## Video walk-through
+
+<div style="position:relative;padding-top:63%;">
+  <iframe src="https://www.youtube.com/embed/s7Tt5PGfHl4?rel=0" frameborder="0" allow="encrypted-media" allowfullscreen
+    style="position:absolute;top:0;left:0;width:100%;height:100%;"></iframe>
+</div>
 
 ## Pick a PR
 
@@ -29,7 +34,7 @@ Add a comment to the PR like "Reviewing this now" to let others know that you in
 
 ## Read about the issue
 
-Every PR *should* have an issue ID for [JIRA](https://issues.civicrm.org) linked from the PR's page on GitHub. Read the original issue and understand how to reproduce the problem and what the solution looks like as well.
+Many PRs will have an issue tracking ticket linked from the PR's page on GitHub. Read the original issue and understand how to reproduce the problem and what the solution looks like as well.
 
 ## Read the code changes
 
@@ -41,27 +46,63 @@ On the PR, click over to “Files Changed” and understand what the code is doi
 
 ## Reproduce the problem
 
-Confirm which branch the PR was created against. This is probably either `master` or the LTS. Setup an instance locally from that branch (e.g. with [buildkit](https://github.com/civicrm/civicrm-buildkit)), or test on the [public demo site if possible](https://civicrm.org/demo). Repeat the steps to reproduce described in the Jira Issue.
+Confirm which branch the PR was created against. This is probably either `master` or a Release Candidate branch. Setup an instance locally from that branch (e.g. with [buildkit](https://github.com/civicrm/civicrm-buildkit)), or test on the [public demo site if possible](https://civicrm.org/demo). Repeat the steps to reproduce described in the ticket or PR.
 
 Confirm that the issue was a problem and a problem “worth solving”, generally worthy of being in core.
 
-## Reproduce the fix
+## Validate the fix
+
+Confirm that the PR works as advertised. Follow some mix of these steps:
+
+* Use the automatic demo-site
+* Review automatic test-results
+* Request additional test-results
+* Apply the patch locally
+
+### Use the automatic demo-site
+
+Whenever a pull-request is submitted or updated, the test server will create a new demo-site. Civibot will post a link to the "_Online demo of this PR_".
+
+!!! question "What if there are no demo sites?"
+
+    The demo may have expired. Demos are usually retained for a few days. But if there is a lot of activity, then it may only be a few hours.
+
+    Alternatively, the PR may have a bug that prevents installation.
+
+    In either case, proceed to the next step ("_Review automatic test-results_"). It will provide a console log and the option to retry.
+
+### Review automatic test-results
+
+1. In the PR timeline, find the latest commit.
+2. Find the status icon (*orange dot, red X, or green checkmark*) and click on it.
+3. Drill-down on the "Details".
+4. This page shows a list of automatic tasks -- such as building the demo, running low-level unit-tests, running end-to-end tests, and similar.
+5. Each task will have a few links available, such as:
+    * __Statistical summary__: If the test-suite runs normally, it will provide a report of successes and failures.
+    * __Console output__:  Use this to monitor an active job or to identify fatal errors.
+    * __Retry__: Run the task again. This is useful if the test-results have expired or if the test-server went offline.
+
+### Request additional test-results
 
-Confirm that the PR works as advertised by observing the result in the build.
+By default, the automatic tests include one demo site and a variety of tests. However, deeper tests may be appropriate if:
 
-You can either test locally or on the test server.
+* The patch involves a CiviCRM integration (such as CiviCRM-Drupal or CiviCRM-WordPress).
+* The patch involves low-level code (such as the installer or the bootstrap process).
 
-### Using the test server to review
+If you have permission to add labels, then you may request further tests with any of these labels:
 
-Our test server automatically creates a dedicated CiviCRM installation for every PR so that (in most cases) it's easy to review the PR without needing to set up a local installation with the fix applied. To access the test build follow these steps:
+| Label | Description |
+|--|--|
+| `run-backdrop` | Create a demo-site with Backdrop. Run end-to-end tests on Backdrop. |
+| `run-drupal-7` | Create a demo-site with Drupal 7. Run end-to-end tests on Drupal 7. |
+| `run-drupal-x` | Create a demo-site with Drupal 9/10. Run end-to-end tests on Drupal 9/10. |
+| `run-wordpress` | Create a demo-site with WordPress. Run end-to-end tests on WordPress. |
+| `run-extended-tests` | Run a comprehensive set of tests, including Backdrop, D7/D9/10, WordPress, and several versions of PHP-MySQL. |
+| `run-distmaker` | Create a set of zip-files/tar-files which include the patch. Use these to install locally. |
 
-1. In the PR, find the section at the bottom of the page which says "All checks have passed"
-1. Go to: "Show all checks" > "Details" > "Console Output" > "Full Log"
-1. Search in page for `CMS_URL`
-1. The first result should bring you to a URL which points to an installation for the build of this PR.
-1. Click on the URL to go to the built site and log in with username = `pradmin` and password = `pradmin1234`
+Every label added will create more outputs and require additional time to complete.
 
-### Reviewing locally
+### Apply the patch locally
 
 For more complicated PRs it is sometimes helpful or necessary to manually test them within a local development installation.
 
@@ -89,8 +130,8 @@ An easy way to do this is:
 
 ## Write a review as a comment
 
-1. Evaluate the change against each of our [review standards](/standards/review.md) criteria.
-1. If you like, copy-paste one of the [review templates](/standards/review.md#templates) into your comment and fill out the template. 
+1. Evaluate the change against each of our [review standards](../standards/review.md) criteria.
+1. If you like, copy-paste one of the [review templates](../standards/review.md#templates) into your comment and fill out the template. 
     * If you choose not to use a template, then summarize your actions and findings, and recommend specific next steps (e.g. merging or otherwise).
 1. In your comment, tag [one of the active contributors](https://github.com/civicrm/civicrm-core/graphs/contributors) (e.g. `@eileenmcnaughton`) so they will see that the PR is ready for further action.
 

docs/core/release-process.md

 # Review/Release Process
 
-Releases are developed on a monthly cycle.  At the start of the month, the release-manager will send an invitation to developers who have open PRs, encouraging them to participate in the release-cycle.  Participation provides a way to exchange feedback with other developers, get PRs merged, and ensure the next release works -- all with a predictable timeline.
+Releases are developed on a monthly cycle, with all but urgent bug and security fixes appearing in versions that are released the first Wednesday of each month.  These iterate the second part of the version number.  For example, 5.23.0 was released on Wednesday, March 4, 2020, 5.24.0 was released on Wednesday, April 1, 2020, and 5.25.0 was released on Wednesday, May 6, 2020.
 
-* For a high-level summary of the release process, see the [Release Management README](https://github.com/civicrm/release-management/blob/master/README.md).
-* For an example invitation, see the previous [invitation for the April-May 2016](https://github.com/civicrm/release-management/issues/1).
+There is no active plan to iterate the first part of the version number.  The 4.7.x series generally followed the same monthly pattern as above except that the third part of the version number was iterated each month.  CiviCRM 5.0.0 followed 4.7.31 in April 2018, and the change was solely for numbering purposes: there is no substantial difference between 5.0.0 and 4.7.31 except for routine changes similar to those introduced every month.  The difference from 4.7.31 to 5.0.0 is comparable to that between 4.7.30 and 4.7.31 or that between 5.0.0 and 5.1.0.
 
+During the month, regressions and security vulnerabilities may be fixed in releases that iterate the third part of the version number.  Generally speaking, security changes will only be released on the first or third Wednesday of the month, and they will be announced through [the CiviCRM website and a security announcement email list](https://civicrm.org/security).  Other point releases may appear at any time.
+
+## Timing
+
+Monthly versions require the participation of a variety of people around the world.  While there is no firm time window, and new versions have been released at all times of day, you can typically expect monthly versions to be releases late in the day in the US/Pacific time zone, which may be early Thursday in many parts of the world.
+
+## Branches
+
+The main branch, termed `master`, is where pull requests are typically merged.  These changes will appear in the version released up to 2 months in the future.
+
+Each monthly release is based upon a branch of the codebase that is number for the first two parts of the upcoming release number.  This is branched off of `master` soon after the prior monthly release and is often termed the "Release Candidate" even though no static, numbered release candidates are generally produced.
+
+After the monthly release, the numbered branch is retained, and any changes that will appear in point releases for that version will be merged there.
+
+Pull requests should typically be made against `master` unless they clearly should appear in the release candidate or a point release.  Situations like this usually involve regressions that newly appear in the release candidate or a very recent version.  In these cases, it's not uncommon for reviewers or release managers to request two or three pull requests in tandem: one for `master`, one for the release candidate, and potentially one for the most recent release.
+
+## Example release cycle
+
+This system is best illustrated by the 5.24.x release cycle.  The `5.24` branch was cut from `master` soon after the 5.23.0 release on March 4, 2020.  A number of late changes, including urgent fixes and intra-release-candidate regressions, were merged during March.  On April 1, 2020, the first Wednesday of the month, 5.24.0 was released based upon the branch as it stood that day.
+
+Soon thereafter, the `5.25` branch was cut from `master`.
+
+Over the next couple of weeks, a number of urgent bug fixes were merged to `5.24`, and point releases 5.24.1 and 5.24.2 were released on the 4th and 9th of the month, respectively.  Security changes were merged to the branch and released on April 15, 2020, the third Wednesday of the month, as 5.24.3.  Further urgent bug fixes were merged to the branch and released as 5.24.4, 5.24.5, and 5.24.6 later in the month.
+
+All of these changes were also merged to `master` and `5.25`.  On May 6, 2020, the first Wednesday of the next month, 5.25.0 was released based upon the `5.25` branch.  No further changes have been merged to `5.24`, and any bugs appearing in the 5.24.x series are to be addressed in later branches and versions.  Meanwhile, the `5.26` branch was cut from `master`, denoting the start of the cycle for the release to appear in June.
+
+## Release impact
+
+Despite having a similar numbering pattern, CiviCRM *does not* use Semantic Versioning.  Each monthly version may contain any number of bug fixes, new features, deprecations, database schema changes, and API changes.  Each may require site administrators to reconfigure features, manually change things prior to or after upgrading, or address problems in past upgrades.
+
+The release notes for each monthly version contain a synopsis to highlight these considerations.  The following items are noted for each version:
+
+- **Fix security vulnerabilities?**  A new monthly release will not typically fix security vulnerabilities.  This is as a courtesy to site administrators so that they won't have the pressure to upgrade for security reasons while potentially facing other changed due to the upgrade.  A security release will more commonly contain only the security-specific changes.
+- **Change the database schema?**  This highlights releases that add or remove database tables, fields, indexes or triggers.  The upgrade process will manage these changes, but site administrators with unusual circumstances or direct-to-database integrations will want to take note of these changes.
+- **Alter the API?** 	The API is intended to be a relatively stable way to integrate other systems or build customizations.  A change to the API, whether through adding or deprecating entities or methods, altering the output of a method, or changing permissions for a method, will often need more attention than other changes to the software.
+- **Require attention to configuration options?**  Changes in the CiviCRM code will often require site administrators to revisit configuration settings that would otherwise be left alone.  One common example is system workflow message templates: when the standard template for a receipt is changed, any site administrator who has edited their site's copy of the template will need to merge their site-specific changes with the changes between versions.  Another is when new permissions are added: a site administrator may need to check that the appropriate users have permission to do a task that may have previously required a different permission.
+- **Fix problems installing or upgrading to a previous version?**  Site administrators encountering a problem installing or upgrading may use a variety of workarounds.  A version that resolves these problems may require the workarounds to be undone.  This is also a useful flag for those who encounter problems and revert the upgrade: they can know that their problems may have been addressed.
+- **Introduce features?**  Most monthly versions introduce new features, which are defined as improvements that go beyond making an existing feature behave the way it purports to.
+- **Fix bugs?**  Practically all monthly versions and point releases fix bugs.
+
+## Getting your changes documented accurately
+
+Clear documentation multiplies the impact of any improvement in code.  If your change is a new feature someone might want to use, you should explain that it's there and how to use it.  If you're fixing a bug, you should make it easy for others experiencing it to know that it is fixed in the new version.  If your changes require a site administrator's attention just to continue using CiviCRM as they had before, it's imperative that you catch their attention.
+
+At the very least, be sure that the intent and impact of your changes are clear for the editors of the release notes.  If you need the attention of site administrators as they upgrade, you should write an upgrade message and/or system check.  Finally, the user, system administrator, and developer documentation allow you to explain in-depth how to make use of your changes.
+
+### Descriptions for release notes
+
+The release notes for each monthly version are built upon a list of all commits since the previous monthly version.  The editors of the release notes will never be able to follow all changes as they are developed, deliberated, and merged.  Instead, they need to be able to understand the effect of each pull request within a minute or two and convey that in the release notes.
+
+In a long ticket, it's sometimes hard to distinguish the initial proposal from what ultimately happened.  For the editors, and for their readers who follow the link to read the details, you can't assume they have followed anything that went on.  Conversations sometimes split between GitLab and a pull request (sometimes a pull request that gets closed), and sometimes key things are resolved on email or Mattermost conversations, or in person at a sprint.
+
+An accurate title goes a long way.  If a pull request fixes a bug, and the title describes the bug concisely, that is completely sufficient.  If the title is "Changes to CiviContribute Component Settings not saved", and in fact the bug is that submitting that form does not save the changes, and the fix makes it so that submitting the form saves the changes, that makes for a perfect description.
+
+If the pull request can't be completely described in the title, it's best to add a modifier indicating what details to look for.  "Changes to CiviContribute Component Settings not saved for some users" or "Changes to certain fields in CiviContribute Component Settings not saved" both point to the sort of detail that the editors--and anyone skimming the release notes--would want to read more about.
+
+The second key thing is to link all related issues and pull requests.  If there's a GitLab issue that the pull request addresses, link to it.  If the pull request follows on an earlier, closed one where there was a lot of discussion, link to it.  If there are corresponding pull requests for other branches, link to them.  The first two provide context for describing the issue or solution.  The latter helps the editors be sure that the change is indeed new in that version or already introduced in an earlier point release.
+
+Finally, especially for larger issues, review the pull request and related issue, if there is one, to make sure it's clear what has actually changed.  You can edit the pull request or issue description to add a couple sentences, or if you lack permission to do that, you can add a final comment.  If the issue is only partially resolved or just has groundwork laid, make it clear what has been done and what has yet to come.  You might also consider whether it's appropriate to have a massive issue that will just be partially complete for the foreseeable future: maybe it's better to split it into several.
+
+### Upgrade messages and system checks
+
+If a site administrator might need to do something following the upgrade, add a post-upgrade message.  (These are in the version-specific file in the `CRM/Upgrade/Incremental/php` folder.)  You may also add a pre-upgrade message, but know that by the time a site administrator sees it, the codebase has already been swapped out.  It's not realistic to expect them to revert at that point, so the effect is similar to the post-upgrade messages.
+
+The person applying upgrades will not necessarily be in a position to make configuration changes.  Whether they lack the organizational authority or simply lack the context, the person reading a post-upgrade message may not understand something you're describing or may not feel confident doing it.  This is separate from something simply being technically confusing: the IT director might run the upgrade but defer to the fundraising officer for managing edits to the online contribution receipt.
+
+Of course, some other site administrators may simply blow past the pre- and post-upgrade messages, and there's no way to go back and view them later.
+
+There are two strategies for addressing these issues.  The first is to make the information easy to find and share.  Add documentation in the user or administrator guide, a helper extension like Doctor When, or simply in a clear explanation on the issue or pull request.  Make the post-upgrade message something straightforward for the person running the upgrade to share with their colleagues.
+
+The second is to assume that many site administrators will ignore the message.  Instead, think through the consequences and make sure that the issue is highlighted later through help text, form validation, or a system check.
+
+System checks are a good way to flag problems on a site.  When an administrator logs in for the first time in a day or visits the system status page, problems will be visible.  You can write a system check that ensures that things are configured properly, and if they are not, administrator users will be reminded.
+
+### User, administrator, or developer documentation
+
+When you add a new feature or resolve a bug in a way that requires some thought on the part of site administrators, writing documentation in the User Guide, System Administrator Guide, or this Developer Guide will help people understand and use it properly.
+
+It's common to open a pull request in a documentation repository and point out that it is dependent upon unmerged changes in the code repository.  Add links in both directions, and reviewers can know to merge them together.

docs/core/verify-fix.md

 # Verify a bug fix
 
 !!! note "See also"
-    This page is about verifying a fix after it has been merged into CiviCRM core. Also see instructions on [reviewing a core pull request](/core/pr-review.md) to learn how to review fixes *before* they are merged.
+    This page is about verifying a fix after it has been merged into CiviCRM core. Also see instructions on [reviewing a core pull request](pr-review.md) to learn how to review fixes *before* they are merged.
 
-Suppose you (or some like-minded spirit) report a bug on the [Jira](/tools/issue-tracking.md#jira). With a bit of luck, someone from the community (perhaps a core developer) reproduces the bug, writes a fix, and announces gleefully: "It's fixed! It took four hours, but I did it!" Hooray! Now what? How do you get the fix running on your system? How do you verify that the fix fixed exactly your problem?
+Suppose you (or some like-minded spirit) [report a bug](../tools/issue-tracking.md#guidelines). With a bit of luck, someone from the community (perhaps a core developer) reproduces the bug, writes a fix, and announces gleefully: "It's fixed! It took four hours, but I did it!" Hooray! Now what? How do you get the fix running on your system? How do you verify that the fix fixed exactly your problem?
  
 ## Step 1. Check the "Fix Version" in JIRA
 
@@ -25,7 +25,7 @@ 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.
 -   Merged (purple): The proposal has been accepted.

docs/documentation/index.md

@@ -2,41 +2,37 @@
 
 To *read* documentation, go to [docs.civicrm.org](https://docs.civicrm.org) for the most high-level list of all active documentation.
 
-This page describes the details of the documentation systems within CiviCRM and how to contribute. We also have a more [basic overview](https://docs.civicrm.org/user/en/latest/the-civicrm-community/contributing-to-this-manual/) on how to contribute to this guide or the user guide. 
+This page describes the details of the documentation systems within CiviCRM and how to contribute. We also have a more [basic overview](https://docs.civicrm.org/user/en/latest/the-civicrm-community/contributing-to-this-manual/) on how to contribute to this guide or the user guide.
 
 !!! note "Note: the wiki is not covered here"
-    The [wiki](https://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Documentation) has historically been CiviCRM's documentation system but is being phased out as of 2017. The rest of this page describes MkDocs guides only and does not cover documentation processes that involve the wiki.
+    The [wiki](https://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Documentation) has historically been CiviCRM's documentation system but has been phased out as of 2017. The rest of this page describes MkDocs guides only and does not cover documentation processes that involve the wiki. No new documentation can be created on the wiki.
 
 ## When to document {:#when}
 
-If you are [contributing to core](/core/contributing.md), updating documenting along with your changes is an important step to ensure the long-term usability and maintainability of CiviCRM.
+If you are [contributing to core](../core/contributing.md), updating documenting along with your changes is an important step to ensure the long-term usability and maintainability of CiviCRM.
 
-Not all changes require documentation updates. Here are some guidelines: 
+Not all changes require documentation updates. Here are some guidelines:
 
 * Documentation should almost always accompany **new features**.
-    * Keep in mind that some features are user-facing (and thus require new documentation in the User Guide) whereas some features are *developer*-facing (and thus require new documentation in the Developer Guide.)
+    * Keep in mind that some features are *user*-facing (and thus require new documentation in the User Guide) whereas some features are *developer*-facing (and thus require new documentation in the Developer Guide.)
 * Bug fixes will occasionally require documentation updates. Check existing docs to see what changes might be necessary.
 
 !!! tip
     Try writing documentation *before* writing your code! Then you have a way to organize your thoughts and measure whether the feature works.
-    
-If you are [submitting a core pull request](/tools/git.md#pr) and would like to submit accompanying doc changes, please provide comments in both pull requests for cross reference. Your docs PR will not be merged until your core PR is merged first.
- 
 
-## Guides in MkDocs
+If you are [submitting a core pull request](../tools/git.md#pr) and would like to submit accompanying doc changes, please provide comments in both pull requests for cross reference. Your docs PR will not be merged until your core PR is merged first.
 
-We are using [MkDocs](http://www.mkdocs.org) to produce guides. The content for each of these guides is written in [markdown](/documentation/markdown.md), stored in text files, and hosted in a repository on GitHub. Then, the guides are automatically published to [docs.civicrm.org](https://docs.civicrm.org) using our custom [publishing system](https://github.com/civicrm/civicrm-docs).
+## Guides in MkDocs
 
+We are using [MkDocs](http://www.mkdocs.org) to produce guides. The content for each of these guides is written in [markdown](markdown.md), stored in text files, and hosted in a repository on GitLab. Then, the guides are automatically published to [docs.civicrm.org](https://docs.civicrm.org) using our custom [publishing system](https://lab.civicrm.org/documentation/docs-publisher).
 
 ### Versions
 
-In an effort to maintain documentation anchored to specific versions of CiviCRM, some guides store separate versions of the documentation in different *branches* within the repository.
+We no longer maintain version specfic documentation, we maintain *evergreen* documentation which always tracks the latest version of CiviCRM but, where appropriate indicates the version that new features and significant changes appeared in. For example:
 
-<!-- TODO: clarify "latest" vs "stable" vs "master" -->
+> From CiviCRM version 5.37.0 ReCAPTCHA configuration can be found at **Administer -> Customise Data and Screens -> ReCAPTCHA**. In earlier versions of CiviCRM this lived on the Miscellaneous Settings page.
 
-If you're improving current documentation, please edit the `master` branch, which will be periodically merged into other branches as needed.
-
-In rarer cases, if you have an edit that pertains to a specific version, (e.g. documentation about a feature in an *older* version of CiviCRM, which does not require documentation in the latest version), then please edit the branch corresponding to that version.
+If you're improving current documentation, please edit the `master` or `main` branch.
 
 ### Languages
 
@@ -50,63 +46,67 @@ We welcome contributions, small and large, to documentation!
 
 Before diving into editing, you may find helpful information within the following resources:
 
-- [Markdown syntax](/documentation/markdown.md) - necessary (but simple) syntax to format content
-- [Markdown coding standards](/documentation/markdown.md#standards) - recommendations for markdown syntax to use
-- [Style guide](/documentation/style-guide.md) - to maintain consistent language and formatting
+- [Markdown syntax](markdown.md) - necessary (but simple) syntax to format content
+- [Markdown coding standards](markdown.md#standards) - information on the correct markdown syntax to use
+- [Style guide](style-guide.md) - to maintain consistent language and formatting
 - [Documentation chat room](https://chat.civicrm.org/civicrm/channels/documentation) - live discussion, fast (most of the time) answers to your questions
 - [Documentation mailing list](https://lists.civicrm.org/lists/info/civicrm-docs) - low traffic, mostly used for informational updates regarding documentation projects
 
-
 ### Submitting issues
 
-The simplest way to help out is to *describe* a change that you think *should* be made by writing a new issue in the issue queue for the GitHub guide you are reading. Then someone will see your issue and act on it, hopefully fast. Each guide has its own issue queue. First find the GitHub repository for the guide (listed in the above table), then when viewing on GitHub, click on "Issues". You will need an account on GitHub to submit a new issue, but creating one is quick and free.
+The simplest way to help out is to *describe* a change that you think *should* be made by writing a new issue in the issue queue for the [lab.civicrm.org](https://lab.civicrm.org/) guide you are reading. Then someone will see your issue and act on it, hopefully fast. Each guide has its own issue queue. First find the lab.civicrm.org repository of the guide, which can be found on their respective documentation guide ([User Guide](https://docs.civicrm.org/user/en/latest/), [SysAdmin Guide](https://docs.civicrm.org/sysadmin/en/latest/), [Developer Guide](https://docs.civicrm.org/dev/en/latest/)) at the right corner of the navigation bar. On viewing  lab.civicrm.org, click on "Issues". You will need an account on lab.civicrm.org to submit a new issue, but creating one is quick and free.
 
-### Editing through GitHub
+### Editing through lab.civicrm.org
 
-Please see the documentation for editing with Git in the [CiviCRM user guide](https://docs.civicrm.org/user/en/stable/the-civicrm-community/contributing-to-this-manual/#single_changes).
+Please see the documentation for editing with Git in the [CiviCRM User Guide](https://docs.civicrm.org/user/en/stable/the-civicrm-community/contributing-to-this-manual/#single_changes).
 
 ### Testing locally with MkDocs {:#mkdocs}
 
 The most advanced way to work on a guide is to use git to download all the markdown files to your computer, edit them locally, preview the changes with [MkDocs](http://mkdocs.org/), then use git to push those changes to your personal fork, and finally make a "pull request" on the main repository. This approach makes editing very fast and easy, but does require a bit of setup, and some knowledge of how git works.
 
 1.  Obtain the source files for the guide you want to edit
-    1.  Find the repository on GitHub *(see "repository" links above, or the "GitHub" link on the bottom left of screen of the documentation you are reading)*
-    1.  Fork the repository on GitHub.
+    1.  Find the repository on [lab.civicrm.org](https://lab.civicrm.org) *(see the "Lab" link on the top right of screen of the documentation you are reading)*
+    1.  Fork the repository on lab.civicrm.org.
     1.  Clone *your fork* of the repository to your computer
-				
+
         ```bash
-        git clone https://github.com/YourGitHubUserName/civicrm-dev-docs.git
+        git clone https://lab.civicrm.org/YourUserName/civicrm-dev-docs.git
         cd civicrm-dev-docs
         ```
-        
-1. *(optional)* If you have [Docker](https://www.docker.com/) installed, then at this point you can run one of the following commands and then skip to the "view the guide locally ..." step below.
+
+1. *(optional)* If you have [Docker](https://www.docker.com/) installed, then at this point you can run one of the following commands and then skip to the "View the guide locally ..." step below.
 	1. For folks who have a full Docker for Windows / Mac / Linux environment, run this command:
 
 		```
-		docker run --rm -v "$PWD":/docs -p 8000:8000 -w /docs seanmadsen/civicrm-docker-mkdocs serve --dirtyreload -a 0.0.0.0:8000
+		docker run --rm -v "$PWD:/docs" -p 8000:8000 -w /docs "mjcoltd/civicrm-docker-mkdocs" serve --dirtyreload -a 0.0.0.0:8000
 		```
-		
-		and skip to the "view the guide" step below.
-		
-	1. For folks who have a legacy or "Home" operating system (Windows 7, 8.1, 10 Home Premium), the situation is a bit more complex.  Follow these steps:
+
+		and skip to the "View the guide" step below. To update this docker image periodically, run the following before the command above.
+
+    ```
+    docker rmi mjcoltd/civicrm-docker-mkdocs
+    ```
+
+	1. For folks who have a legacy or "Home" operating system (Windows 7, 8.1, 10 Home Premium), the situation is a bit more complex.  The same is true if you have implemented virtual machines on your system using Oracle VM VirtualBox or VMWare tools.  These tools don't play well with native Windows HyperV virtualization.  In any case, follow these steps:
 		1.  Check that GitHub folder is in the path:  ```c:\Users\<username>\Documents\...```.  If it is, all is good; if not, move it there, and edit your GitHub configuration to reflect the changed location.
-		1.  Set up a Docker-Toolbox environment (which depends on Oracle VM Box), and check that it is functioning properly (Hello-world container works). 
+		1.  Set up a Docker-Toolbox environment (which depends on Oracle VM VirtualBox), and check that it is functioning properly (Hello-world container works).
+		1.  Review the Docker-Toolbox instance in Oracle VM VirtualBox to ensure that it has the necessary port-forwarding configuration in place. If there is no HTTP port forwarding rule, add one that specifies: Name: HTTP, Protocol: TCP, Host IP: 127.0.0.1, Host Port: 8000, Guest IP (empty), Guest Port: 8000. If this configuration is not present, all attempts to open a browser session will receive a "connection refused" error.  
 		1.  Run this command:
-		
+
 		```
-		docker run --rm -v "/c/Users/<username>/Documents/GitHub/civicrm-user-guide:/docs" -p 8000:8000 -w /docs seanmadsen/civicrm-docker-mkdocs serve --dirtyreload -a 0.0.0.0:8000
+		docker run --rm -v "/c/Users/<username>/Documents/GitHub/civicrm-user-guide:/docs" -p 8000:8000 -w /docs mjcoltd/civicrm-docker-mkdocs serve --dirtyreload -a 0.0.0.0:8000
 		```
-		and skip to the "view the guide locally ..." step below.
-	
+		and skip to the "View the guide locally ..." step below.
+
 1. Install [pip](https://pypi.python.org/pypi/pip) (python package manager)
 
-    - OS X: `brew install python`
-    - Debian/Ubuntu: `sudo apt-get install python-pip python-wheel`
+    - OS X: `brew install python3`
+    - Debian/Ubuntu: `sudo apt-get install python3-pip`
 
 1.  Install MkDocs, plus the [Material theme](http://squidfunk.github.io/mkdocs-material/) and the [Pygments syntax highlighter](http://pygments.org/).
 
     ```bash
-    sudo pip install mkdocs mkdocs-material pygments pymdown-extensions
+    sudo pip install mkdocs==1.0.4 mkdocs-material==4.6.3
     ```
 
 1. Serve a local copy of the guide with MkDocs
@@ -121,11 +121,13 @@ The most advanced way to work on a guide is to use git to download all the markd
 
 1. View the guide locally in your browser at `http://localhost:8000`.
 
-1.  Edit the [markdown](/documentation/markdown.md) with an editor of your choice.  As you
+1.  Edit the [markdown](markdown.md) with an editor of your choice.  As you
     save your changes `mkdocs` will automatically reprocess the page and
     refresh your browser.
 
-1.  When you are happy with your edits, use git to commit and push your changes up to your fork.  Then submit a  pull request on GitHub.
+1.  When you are happy with your edits, use git to commit and push your changes up to your fork.  Then submit a  pull request on lab.civicrm.org.
+
+1.  `Ctrl`-`C` will stop the MkDocs server.
 
 
 ### Adding a new page {:#new-page}
@@ -166,7 +168,7 @@ Some guides may have auto-generated content, which is summarized here.
 
 ### In the Developer Guide {:#auto-gen-dev}
 
-This Developer Guide has an automatically-generated [list of all hooks](/hooks/list.md). To re-create this list, run the following command from the root level of the repository:
+This Developer Guide has an automatically-generated [list of all hooks](../hooks/list.md). To re-create this list, run the following command from the root level of the repository:
 
 ```
 ./bin/tools generate:hooks-list
@@ -176,14 +178,14 @@ Our editing workflow currently requires someone to manually run this command aft
 
 ## Content attribution guidelines {:#attribution}
 
-All CiviCRM documentation content is licensed [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/). This means that if you want to copy content out of our docs and use it elsewhere, you're welcome to do so as long as your give attribution to the author. 
+All CiviCRM documentation content is licensed [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/). This means that if you want to copy content out of our docs and use it elsewhere, you're welcome to do so as long as your give attribution to the author.
 
 ### How to obtain author information for content within our guides {:#attributing-exports}
 
 This is relevant when you want to copy content *out of* our documentation books.
 
-1. Find the GitHub repository for the book that contains the content you'd like to use. (There will usually be a link to this repository at the top right of ever page.)
-2. Navigate to the corresponding markdown file within GitHub (it will match the URL path of the published content).
+1. Find the [lab.civicrm.org](https://lab.civicrm.org/) repository for the book that contains the content you'd like to use. (There will usually be a link to this repository at the top right of ever page.)
+2. Navigate to the corresponding markdown file within lab.civicrm.org (it will match the URL path of the published content).
 3. Click on "Blame" to see detailed information about content authors, line, by line.
 
 ### How to display attribution for content migrated *into* our books {:#attributing-imports}
@@ -196,7 +198,7 @@ When migrating content into our docs guides which requires attribution, display
 ## Credits
 
 Some content from this page was migrated from other sources
-and contributed by the following authors: 
+and contributed by the following authors:
 
 * Mickey Mouse
 * Lisa Simpson
@@ -204,4 +206,3 @@ and contributed by the following authors:
 ```
 
 Commit messages should also reference the URL of the original content.
-

docs/documentation/markdown.md

@@ -33,36 +33,35 @@ To maintain some consistency and peace of mind for documentation content editors
 * **Unordered lists:** use `*` to delimiters.
 * **Headings:** use hashes like `## Heading 2`.
 
-### Internal URL standards {:#internal-url-standards}
+### Internal link standards {:#internal-url-standards}
 
 !!! note
-    These standards only apply to *internal* hyperlinks and images (which should be internal anyway). There are no markdown standards for external links (which point outside of the current guide).
+    These standards only apply to *internal* links and images (which should be internal anyway). There are no markdown standards for external links (which point outside of the current guide).
 
 Valid examples:
 
-1. `[Buildkit](/tools/buildkit.md)`
-1. `[the API](/api/index.md)`
-1. `[extension review process](/extensions/lifefycle.md#formal-review)`
+1. `[Buildkit](../tools/buildkit.md)`
+1. `[the API](../api/index.md)`
+1. `[extension review process](../extensions/lifefycle.md#formal-review)`
 1. `[section within this page](#that-section)`
-1. `![awesome alt text](/images/awesome-screenshot.png)`
+1. `![awesome alt text](../../images/awesome-screenshot.png)`
 
 
 Rules:
 
-* Use absolute URLs which begin with a forward slash. (The root directory is the `docs` folder.)
-    * Exception: when you are linking to a section within the current page, use only the fragment which corresponds to that heading (beginning with `#`, as in example 4 above.). (Also consider [specifying a custom heading ID](#custom-heading-ids) to prevent broken links if the heading is later renamed.)
+* Your link should point directly to the markdown file in the folder tree, using `..` and/or `filename.md` as appropriate.
+    * When you are linking to a section within the current page, use only the fragment which corresponds to that heading (beginning with `#`, as in example 4 above.). (Also consider [specifying a custom heading ID](#custom-heading-ids) to prevent broken links if the heading is later renamed.)
 * Append `.md` when linking to a page.
-* If you are linking to a page which is named `index.md`, then include `index.md` in the URL (even though your link will technically still work if you don't).
+* If you are linking to a page which is named `index.md`, then include `index.md` in the path (even though your link will technically still work if you don't).
 * If you're linking to a section within a page (other than the current one), then do it as shown in example 3 above (even though some some other variants will also work).
-* Do not use syntax like `[Link Text][url]` which defines the URL in a separate part of the document (even though it will technically work).
+* Do not use syntax like `[Link Text][path]` which defines the path in a separate part of the document (even though it will technically work).
 
-Reasons for these internal URL standards:
+Reasons for these internal link standards:
 
 * Following the rules above helps us avoid broken links.
 * MkDocs will detect broken links when building books, but only if the links are absolute and end with `.md`.
 * Using consistent syntax helps us to more easily find-and-replace links when moving pages.
 
-
 ## Basic inline formatting
 
 | Code | Result | Extension required |
@@ -80,7 +79,7 @@ platforms.
 
 ## Internal hyperlinks
 
-See the [internal URL standards](#internal-url-standards) above for examples of internal hyperlinks.
+See the [internal link standards](#internal-url-standards) above for examples of internal hyperlinks.
 
 !!! warning
     Several different syntax variants will produce functionally identical hyperlinks, but it's important you follow our [standards](#internal-url-standards) so that we can avoid broken links when re-organizing pages in the future.
@@ -90,65 +89,92 @@ See the [internal URL standards](#internal-url-standards) above for examples of
 
 A basic external hyperlink in a sentence:
 
-```
+``` md
 Try [CiviCRM](https://civicrm.org) for your database.
 ```
 
+***Result:***
+
+> Try [CiviCRM](https://civicrm.org) for your database.
+
 ### Named hyperlinks
 
 If you're using a one external link in many places throughout a page, you can define the URL in one place as follows
 
-```
-See [CRM-1234] for more details.
+``` md
+See [#123] for more details.
 
-My favorite issue is [CRM-1234].
+My favorite issue is [#123].
 
-[CRM-1234]: https://issues.civicrm.org/jira/browse/CRM-1234
+[#123]: https://lab.civicrm.org/dev/core/issues/123
 ```
 
+***Result:***
+
+> See [#123] for more details.
+>
+> My favorite issue is [#123].
+>
+> [#123]: https://lab.civicrm.org/dev/core/issues/123
+
 (The third line can be placed anywhere in the file.)
 
 You can also use custom text for a named hyperlink, as shown below:
 
-```
+``` md
 After learning [how to foo a bar][foobar], then you can party!
 
 [foobar]: https://example.com/foobar
 ```
 
-!!! caution "For external links only"
-    Per our [standards](#internal-url-standards), named hyperlinks should only be used for *external* links
+***Result:***
 
+> After learning [how to foo a bar][foobar], then you can party!
+>
+> [foobar]: https://example.com/foobar
 
+!!! caution "For external links only"
+    Per our [standards](#internal-url-standards), named hyperlinks should only be used for *external* links
 
 ## Line breaks and whitespace
 
 **Single line breaks** in markdown code are eliminated in display:
 
-```
+``` md
 This text will all show up
 on the
 same
 line.
 ```
 
-This makes it easy to avoid very long lines in markdown code. As a rule of
-thumb, keep your markdown code free of lines longer than 80 characters
-where possible.
+***Result:***
+
+>This text will all show up
+>on the
+>same
+>line.
+
+This makes it easy to avoid very long lines in markdown code however text wrapping is the job of editors and you should not insert non-paragraph line breaks to artificially shorten lines of text. Instead write your text naturally, without regard for line lengths and allow editors to handle text wrapping according to the device and display preferences of their user.
 
 **Double line breaks** create separate paragraphs:
 
-```
+``` md
 This is
 one paragraph.
 
 This is a second.
 ```
 
+***Result:***
+
+>This is
+>one paragraph.
+>
+>This is a second.
 
 ## Headings
 
-```md
+``` md
 # Heading 1
 
 ## Heading 2
@@ -158,13 +184,23 @@ This is a second.
 #### Heading 4
 ```
 
+***Result:***
+
+> # Heading 1
+>
+> ## Heading 2
+>
+> ### Heading 3
+>
+> #### Heading 4
+
 The above syntax is [called](http://pandoc.org/MANUAL.html#headers)
 "ATX style headers" in markdown terminology, and is the [preferred](#standards)
 syntax within the CiviCRM community.
 An alternate syntax called "setext style headers" works for h1 and h2 as
 follows (but please avoid creating new content with this syntax).
 
-```
+``` md
 Heading 1
 =========
 
@@ -172,12 +208,20 @@ Heading 2
 ---------
 ```
 
+***Result:***
+
+> Heading 1
+> =========
+>
+> Heading 2
+> ---------
+
 ### Custom heading IDs
 
 !!! tip "Extension required"
     To use custom heading IDs in MkDocs, insert the following code in `mkdocs.yml` to enable the [Attribute Lists](https://pythonhosted.org/Markdown/extensions/attr_list.html) extension:
 
-    ```yml
+    ``` yml
     markdown_extensions:
       - markdown.extensions.attr_list
     ```
@@ -186,22 +230,25 @@ Custom heading IDs allow you to link to specific sections in a page by appending
 
 Setting a custom ID:
 
-```
+``` md
 ## How to foo a bar {:#foo}
 ```
 
+***Result:***
+
+> ## How to foo a bar {:#foo}
+
 This is helpful when you think that readers are likely to frequently link
 to this section in the future.
 
 * Custom heading IDs will remain the same (thus preserving incoming links) even after the text of the heading is edited.
 * Custom heading IDs create shorter URLs.
 
-
 ## Lists
 
 ### Unordered lists
 
-```text
+``` md
 Here is my paragraph (with a blank line after).
 
 * My first item is here.
@@ -210,33 +257,46 @@ Here is my paragraph (with a blank line after).
 * Then, a third.
 ```
 
+***Result:***
+
+> Here is my paragraph (with a blank line after).
+>
+> * My first item is here.
+> * My second item is here and a
+> bit longer than the first.
+> * Then, a third.
+
 !!! note
     If you don't **include a blank line before your first list item**, then the list will become part of the previous element (paragraph, heading, etc).
 
-Alternate syntax:
+Alternate syntaxes:
 
 * Unordered lists also recognize `-` and `+` as item delimiters.
 * Markdown is somewhat flexible with the quantity and position of spaces when making lists.
 
-
 ### Ordered lists
 
-```
+``` md
 1. Item
 1. Item
 1. Item
 ```
 
-Alternate syntax:
+***Result:***
 
-* Ordered lists items are automatically re-numbered sequentially upon display which means all items can begin with `1`, or they can be ordered sequentially in code.
+> 1. Item
+> 1. Item
+> 1. Item
 
+Alternate syntaxes:
+
+* Ordered lists items are automatically re-numbered sequentially upon display which means all items can begin with `1`, or they can be ordered sequentially in code.
 
 ### Nested lists
 
 List sub-items must be indented 4 spaces:
 
-```
+``` md
 1.  Item
     1.  Item
     1.  Item
@@ -247,6 +307,16 @@ List sub-items must be indented 4 spaces:
 1. Item
 ```
 
+***Result:***
+
+> 1.  Item
+>     1.  Item
+>     1.  Item
+> 1.  Item
+>     * Item
+>     * Item
+>     * Item
+> 1. Item
 
 ## Code
 
@@ -254,67 +324,91 @@ List sub-items must be indented 4 spaces:
 
 Use backticks to create inline monospace text:
 
-```
+``` md
 Some `monospace text` amid a paragraph.
 ```
 
+***Result:***
+
+> Some `monospace text` amid a paragraph.
+
 And if you need to put a backtick inside your monospace text, begin and end
 with two backticks:
 
-```
+``` md
 Some ``monospace text with `backticks` inside``, and all amid a paragraph.
 ```
 
+***Result:***
+
+> Some ``monospace text with `backticks` inside``, and all amid a paragraph.
 
 ### Code blocks
 
 A block of **"fenced code"** with three or more backticks on their own line.
 
-````
+```` md
 ```
 CODE
 BLOCK
 ```
 ````
 
+***Result:***
+
+> ```
+> CODE
+> BLOCK
+> ```
+
 *Fenced code can use more than three backticks when necessary to represent code that contains 3 backticks (which is what you'd see in the source for this page).*
 
 Alternate syntax: For fenced code, the tilde `~` character also works
 in place of the backtick character but should be avoided for consistency.
 
-
 A block of **"indented code"** with four spaces at the start of each line:
 
+```` md
 ```
     CODE
     BLOCK
 ```
+````
+
+***Result:***
 
+> ```
+>     CODE
+>     BLOCK
+> ```
 
 ### Syntax highlighting for code
+For code blocks, some platforms (e.g. GitHub) will guess the language of the code and automatically apply syntax highlighting to the display.
 
-*   For code blocks, some platforms (e.g. GitHub) will guess the language of the code and automatically apply syntax highlighting to the display.
-*   To force a particular type of syntax highlighting, use fenced code with a keyword (like `javascript` in this case) as follows:
+To force a particular type of syntax highlighting, use fenced code with a keyword (like `javascript` in this case) as follows:
 
-    ````
-    ```javascript
-    var cj = CRM.$ = jQuery;
-    ```
-    ````
+```` md
+```javascript
+var cj = CRM.$ = jQuery;
+```
+````
+
+***Result:***
 
-*   Available language keywords:
-    *   Differ slightly by markdown platform
-    *   Common language keywords that work on most platforms: `bash`, `css`, `docker`, `html`, `javascript`, `js`, `json`, `markdown`, `md`, `perl`, `php`, `python`, `ruby`, `scss`, `sh`, `smarty`, `sql`, `xhtml`, `xml`, `yaml`
-    *   The Material theme for MkDocs will use the Pygments python library when possible, and in this case provide syntax highlighting for [over 300 languages](http://pygments.org/docs/lexers).
+> ```javascript
+> var cj = CRM.$ = jQuery;
+> ```
 
-*   Syntax highlighting cannot be forced for indented code.
-*   Syntax highlighting for inline code is possible with [InlineHilite](http://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/) but not recommended.
-*   [Stack Exchange syntax highlighting][stack exchange syntax highlighting] is
-    done differently.
+Available language keywords:
+ *   Differ slightly by markdown platform
+ *   Common language keywords that work on most platforms: `bash`, `css`, `docker`, `html`, `javascript`, `js`, `json`, `markdown`, `md`, `perl`, `php`, `python`, `ruby`, `scss`, `sh`, `smarty`, `sql`, `xhtml`, `xml`, `yaml`
+ *   The Material theme for MkDocs will use the Pygments python library when possible, and in this case provide syntax highlighting for [over 300 languages](http://pygments.org/docs/lexers).
 
-[stack exchange syntax highlighting]: http://stackoverflow.com/editing-help#syntax-highlighting
+Syntax highlighting cannot be forced for indented code.
 
+Syntax highlighting for inline code is possible with [InlineHilite](http://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/) but not recommended.
 
+[Stack Exchange syntax highlighting](http://stackoverflow.com/editing-help#syntax-highlighting) is done differently.
 
 ### Code blocks within lists
 
@@ -323,14 +417,14 @@ A block of **"indented code"** with four spaces at the start of each line:
 !!! tip "Extension required"
     To use fenced code within lists in MkDocs, install [PyMdown Extensions](http://facelessuser.github.io/pymdown-extensions) and then insert the following code in `mkdocs.yml` to enable the [Superfences](http://facelessuser.github.io/pymdown-extensions/extensions/superfences/) extension:
 
-    ```yml
+    ``` yml
     markdown_extensions:
       - pymdownx.superfences
     ```
 
 Then insert fenced code into a list as follows:
 
-````md
+```` md
 *   First item
 *   Look at this code:
 
@@ -342,11 +436,23 @@ Then insert fenced code into a list as follows:
 *   More list items
 ````
 
+***Result:***
+
+> * First item
+> * Look at this code:
+>
+>     ```
+>     code
+>     block
+>     ```
+>
+> *   More list items
+
 #### Indented code within lists
 
 You can use indented code within lists without needing any markdown extensions. Keep a blank line above and below the code and indent the code *4 spaces more than your list content*, like this:
 
-```md
+``` md
 *   First item
 *   Look at this code:
 
@@ -366,14 +472,32 @@ You can use indented code within lists without needing any markdown extensions.
 *   Fun, right?
 ```
 
-
+***Result:***
+
+> *   First item
+> *   Look at this code:
+>
+>         CODE BLOCK WITHIN
+>         TOP LEVEL LIST ITEM
+> 
+> *   More list items
+> *   A nested list is here:
+>     1.  Alpha
+>     1.  Beta, with some code
+>
+>             CODE BLOCK WITHIN
+>             SUB-LIST ITEM
+> 
+>     1. Gamma
+>
+> *   Fun, right?
 
 ## Admonitions
 
 !!! tip "Extension required"
     To use admonitions in MkDocs, insert the following code in `mkdocs.yml` to enable the [Admonitions](https://pythonhosted.org/Markdown/extensions/admonition.html) extension:
 
-    ```yml
+    ``` yml
     markdown_extensions:
       - markdown.extensions.admonition
     ```
@@ -382,18 +506,28 @@ You can use indented code within lists without needing any markdown extensions.
 
 Simple example:
 
-```md
+``` md
 !!! note
     Here is a note for you.
 ```
 
+***Result:***
+
+> !!! note
+>     Here is a note for you.
+
 Add a custom title (make sure to quote the title):
 
-```md
+``` md
 !!! danger "Don't try this at home!"
     Stand back. I'm about to try science!
 ```
 
+***Result:***
+
+> !!! danger "Don't try this at home!"
+>     Stand back. I'm about to try science!
+
 (You can also add an admonition *without* a title by passing an empty string `""` in place of the title.)
 
 ### Types {:#admonition-types}
@@ -431,23 +565,35 @@ Images function mostly the same as hyperlinks, but preceded by an exclamation
 point and with alt text in place of the link text.
 
 ```
-![Alt text](/directory/image.png)
+![Alt text](../img/CiviCRM.png)
 ```
 
+***Result:***
+
+> ![Alt text](../img/CiviCRM.png)
+
 Note:
 
 * The image files should be committed into git and stored in the `docs/img` directory within the project.
-* The URL to the image should follow out [internal URL standards](#internal-url-standards)  
+* The path to the image should follow our [internal link standards](#internal-url-standards)  
 
 ## Other markdown syntax
 
 *   [Tables] (to be avoided when possible)
 *   [Emojis] (great for Mattermost)
 *   Blockquotes
-
+    
+    ``` md
         > This text is a blockquote, typically used
-          to represent prose written by a person. It
-          will be displayed slightly indented.
+        >  to represent prose written by a person. It
+        >  will be displayed slightly indented.
+    ```
+    
+    ***Result:***
+    
+    > This text is a blockquote, typically used
+    >  to represent prose written by a person. It
+    >  will be displayed slightly indented.
 
 [Emojis]: http://www.webpagefx.com/tools/emoji-cheat-sheet/
 [Tables]: https://help.github.com/articles/organizing-information-with-tables

docs/documentation/style-guide.md

 # Documentation style guide
 
 All CiviCRM guides *(like this Developer Guide)* are intended to provide
-high-quality "finished" [documentation](/documentation/index.md)
+high-quality "finished" [documentation](index.md)
 about CiviCRM. This Style Guide page documents the standards we wish to
 uphold to ensure all guides maintain this high level of quality.
 
-## Parts, chapters, sections
+## General guidelines
 
-Similar to most text books and manuals, we divide our guides into "parts",
-"chapters", and "sections". In mkdocs, these blocks translate as follows:
+### Docs nomenclature {:#nomenclature}
 
--   "part" - folder
--   "chapter" - file (in markdown), also one web page with a given URL
--   "section" - heading within the page
+To streamline communication about documentation issues, we define the following terms:
+
+-   "Chapter" - folder
+-   "Sub-chapter" - a folder within a folder
+-   "Page" - file (in markdown)
+-   "Section" - heading within the page
+
+### Page names
 
 In the navigation menu (as stored in `mkdocs.yml`):
 
--   Keep the page hierarchy to the depth described above
-    (i.e. do not put folders within other folders).
--   Each chapter name should be short enough to fit nicely in the menu,
+-   Each page name should be short enough to fit nicely in the menu,
     but also long enough to stand on its own to a reasonable extent.
     The titles set here are used in the navigation menu *and* the page title
     that displays in the browser tab. The guide will be more usable if the
     reader sees two tabs titled "Using Hooks" and "API Usage" instead of
     "Usage" and "Usage".
+    
+### Introductory paragraphs
 
-Each chapter should start with a paragraph that explains what will be
-covered in the chapter.
+Each page should start with a paragraph that explains what will be
+covered in the page.
+
+### Cumulative concepts
 
 Effort should be given to arrange all content within a guide so that skills and
 concepts which build upon one another are presented sequentially.
 Although guides should not require start-to-finish reading, providing the
 option (when possible) is helpful to some readers.
 
+### Cross-references
+
 Don't use terms like "previous chapter", etc. because we may add or re-arrange
-chapters in the future. Instead, use a hyperlink to the chapter.
+pages in the future. Instead, use a hyperlink to the page, or ideally to the specific section within the page.
 
 ### Hackable URLs
 
@@ -42,19 +50,19 @@ When you organize several markdown files into one folder, it's good practice to
 
 ### Headings
 
-The first heading in a chapter should be Heading 1. All others should be
+The first heading in a page should be Heading 1. All others should be
 in H2 and H3, only where necessary.  If you find yourself wanting to use
-H4, consider if it's truly necessary and whether the chapter should
+H4, consider if it's truly necessary and whether the page should
 instead be refactored.
 
-### Capitalization
+### Title capitalization
 
-Titles for parts, chapters, and sections should all be in sentence case
+Titles for chapters, pages, and sections should all be in sentence case
 (first word capitalized), not headline case (each word capitalized).
 
-## Formatting conventions
+## Describing the CiviCRM user interface
 
-### Describing the CiviCRM user interface
+### Bold for things you click
 
 Menu selections, buttons, tabs (basically, things that the reader is
 being told to click) should be in bold.
@@ -66,6 +74,8 @@ For example:
 -   Modify event type labels by clicking **Edit** on any row.
 -   Click **Add Event Type** to create a new category for your events.
 
+### UI element capitalization
+
 Elements of the system and interface should be capitalized (e.g. the
 Events component, the Template Title field).
 
@@ -78,13 +88,19 @@ thing or technical definition (e.g. scheduled reminders, plain text).
 Use your best judgment as to what serves the reader; trying to enforce
 consistency in this arena will slow us down or drive us crazy.
 
+### Quotes
+
 Quotes should be avoided as much as possible; however, do use them when
 they seem necessary for clarity (e.g. if you are talking about setting
 or field labels that are long phrases).
 
+### Types of CiviCRM pages
+
 You can divide the CiviCRM interface into administration pages and
 public-facing pages.
 
+## Formatting conventions
+
 ### Bullets and numbered lists
 
 Bulleted lists should be used to convey short snippets of information.
@@ -113,7 +129,7 @@ Alternative Text  (ALT Tags) should be included for every image.
 
 ### Machine-readable symbols
 
-Machine-readable symbols (e.g. files names, classes, functions, variables, database tables, database columns, commands, etc.) should be formatted either with inline monospace or preformatted code blocks (also in monospace). See the [markdown syntax](/documentation/markdown.md#code) to use for such formatting.
+Machine-readable symbols (e.g. files names, classes, functions, variables, database tables, database columns, commands, etc.) should be formatted either with inline monospace or preformatted code blocks (also in monospace). See the [markdown syntax](markdown.md#code) to use for such formatting.
 
 ### URLs
 
@@ -160,7 +176,7 @@ Below are our preferred spellings of CiviCRM-specific words:
 -   **developer** - a computer programmer who writes code to improve or extend the functionality, stability or security of CiviCRM
 -   **core team**
     -   in the User Guide - *should be avoided* - use "CiviCRM" or "the CiviCRM community"
-    -   in other guides - refers to the  [core team](https://civicrm.org/teams/core-team)
+    -   in other guides - refers to the  [core team](https://civicrm.org/about/core-team)
 
 ### Gender neutrality
 
@@ -226,25 +242,7 @@ them in the right direction when they want to know about those tasks.
 
 ### Shell Commands in documentation.
 
-When writing shell commands in documentation as examples, for any commands that are expected to be typed out by the user a `$` should be put in front of the command. e.g.
-
-```shell
-$ cd ~/buildkit/build/drupal-demo/sites/all/modules/civicrm
-$ civibuild create drupal-demo --civi-ver master --url http://localhost:8001
-$ hub fork
-```
-
-When your putting in any content that would be outputted by a shell command this should not have a `$` appended to it e.g.
-
-```shell
-$ git remote -v
-origin  https://github.com/civicrm/civicrm-core.git (fetch)
-origin  https://github.com/civicrm/civicrm-core.git (push)
-yourusername      git@github.com:yourusername/civicrm-core.git (fetch)
-yourusername      git@github.com:yourusername/civicrm-core.git (push)
-```
-
-Authors should also not put any comments within the examples themselves, whereas any comments should go outside of the code block in regular paragraphs. Where possible each command should be its own comment block. When it is crucial for the user to understand the directory in which to run the command, include a separate code block before hand with a `cd` command.
+Authors should not put any comments within code examples, any comments should go outside of the code block in regular paragraphs. Where possible each command should be its own block. When it is crucial for the user to understand the directory in which to run the command, include a separate code block before hand with a `cd` command.
 
 !!! tip "Write portable shell commands"
 

docs/extensions/advanced.md

@@ -8,8 +8,8 @@
 There are three options to create an ajax or web-service callback:
 
 -    **Full control:** Add a basic page. Remove the parent::run() call from the run() function, and at the bottom of the run() function, perform your own output (eg "*echo json\_encode($data)*") and then short-circuit processing (eg "*CRM\_Utils\_System::civiExit()*") so that neither Smarty nor the CMS modify the output.
--    **Using ajax helpers (CiviCRM 4.5 and above):** Generate a page with civix as above. Build your data in the run() function. If the client-side request includes *snippet=json* in the url, just append your data to *$this-\>ajaxResponse* array and the rest will happen automatically. If not, you can directly call CRM\_Core\_Page\_AJAX::returnJsonResponse() at the bottom of the run function. See [Ajax Pages and Forms](/framework/ajax.md) documentation.
--    **Using the API:** Add an API function using `civix`. The API function can be called with the API's [AJAX Interface](/api/interfaces.md#ajax). This automatically handles issues like encoding and decoding the request/response.
+-    **Using ajax helpers (CiviCRM 4.5 and above):** Generate a page with civix as above. Build your data in the run() function. If the client-side request includes *snippet=json* in the url, just append your data to *$this-\>ajaxResponse* array and the rest will happen automatically. If not, you can directly call CRM\_Core\_Page\_AJAX::returnJsonResponse() at the bottom of the run function. See [Ajax Pages and Forms](../framework/ajax.md) documentation.
+-    **Using the API:** Add an API function using `civix`. The API function can be called with the API's [AJAX Interface](../api/v3/interfaces.md#ajax). This automatically handles issues like encoding and decoding the request/response.
 
 ## Standalone PHP scripts
 
@@ -30,7 +30,7 @@ If you really need to do it, it's theoretically possibly to emulate an example l
 
 ## Cron jobs
 
-One can add an API function (using the instructions above) and create a schedule record. In CiviCRM 4.3, the schedule record can be automatically created; to do this, call "civix [generate:api](http://generateapi)" with the option "–schedule Daily" (or "-schedule Hourly", etc). CiviCRM will make a best-effort to meet the stated schedule.
+One can add an API function (using the instructions above) and create a schedule record. In CiviCRM 4.3, the schedule record can be automatically created; to do this, call "civix [generate:api](civix.md#generate-api)" with the option "–schedule Daily" (or "-schedule Hourly", etc). CiviCRM will make a best-effort to meet the stated schedule.
 
-In CiviCRM 4.2, one can use APIs as cron jobs, but the schedule record won't be created automatically. The site administrator must manually insert a scheduling record by navigating to "Administer =\> System Settings =\> Scheduled Jobs".
+In CiviCRM 4.2, one can use APIs as cron jobs, but the schedule record won't be created automatically. The site administrator must manually insert a scheduling record by navigating to **Administer > System Settings > Scheduled Jobs**.
 

docs/extensions/helptext.md

+# Adding pop-up help text in your extension
+
+In addition to simply adding help text for form fields that you have added in your extension as usual, you can also add to or replace help text for existing form fields in core. To do so, simply add a file in the same directory as the hlp file is found in core, with the name `helpfilename.extra.hlp`.
+
+If you want to append your help text to the existing text, add the htxt to your extra help file as normal. If you want to replace the existing text with your own text, add `override=1` to your htxt, for example: `{htxt id="field_name_id" override=1}...`. This works for both the content of the help text and the title.
\ No newline at end of file