docs/api/v4/managed.md

+# Managed APIv4 Entities
+
+## Basics
+
+Managed Entities are used to package configuration data with extensions.
+For example, *menu items*, *custom fields* or *option values* all might be needed for the extension to function.
+
+Documentation on creating managed records for use with extensions is in the [Extensions - Managed Entities](../../extensions/managed.md) chapter.
+
+## ManagedEntity Trait
+
+In order to be managed, the API entity class must `use` the `ManagedEntity` trait. This adds the following api actions:
+
+- **[`revert`](actions.md#write-actions):** update the entity back to its original state as declared by the `.mgd.php` file or [hook_civicrm_managed](../../hooks/hook_civicrm_managed.md) data.
+
+- **[`export`](actions.md#read-actions):** outputs configuration data for this and all linked entities, suitable for placing in a `.mgd.php` file. This api is called by the [`civix export` command](../../extensions/civix.md#export).
+
+## Lifecycle
+
+Managed entities are declared via [hook_civicrm_managed](../../hooks/hook_civicrm_managed.md), although it is more typical for
+extensions to use `.mgd.php` files which are automatically loaded via mixin.
+
+Once installed, Managed instances are tracked in a table in CiviCRM called `civicrm_managed`. 
+You can use `Civi\Api4\Managed::get()` to see what is in there (or make sure your entity has been added)
+and use the APIv4 `reconcile` action to have the list of declared entities compared against what is
+present in the `civicrm_managed` table - any that are missing will be created and depending on your update mode and cleanup mode they may be updated or deleted if the declaration has changed. Note that
+you can declare Managed Entities using APIv4 or APIv3 but APIv4 is more robust as it can handle the 
+situation where a similar record already exists.

docs/api/v4/pseudoconstants.md

+# APIv4 Pseudoconstants (Option Lists)
+
+Some fields in CiviCRM are linked to an option list (aka *Pseudoconstant*). These fields are typically shown to the user
+as checkboxes, radios, or a dropdown-select of options from the pseudoconstant list.
+
+The API provides tools for working with such fields; so that downstream developers do not need to translate between database values and option properties.
+
+## Option list properties
+
+Each option in the list consists of attributes like `id`, `name`, `label`, `description`, `color` and `icon`.
+For a complete list and description of each attribute see the framework chapter: [Pseudoconstant (Option List) Reference](../../framework/pseudoconstant.md#attributes).
+
+## Which fields have option lists?
+
+To find out which fields have option lists for a particular entity, use the `getFields` action from the API or API Explorer, e.g.
+```php
+civicrm_api4('Contact', 'getFields', [
+  'where' => [['options', '!=', FALSE]],
+])
+```
+This will return a list of all fields for a given entity (in this example, "Contact") which have an option list.
+
+## Retrieving an option list {:#retrieve}
+
+If you need to retrieve the full option list for a field, use the `getFields` action and set the `loadOptions` parameter
+to an array of the above properties you would like to retrieve. Try it in the API explorer, e.g.
+
+```php
+civicrm_api4('Contact', 'getFields', [
+  'where' => [['name', '=', 'contact_type']],
+  'loadOptions' => ['name', 'label', 'description'],
+])->first();
+```
+This will load information about the `contact_type` field including the list of available options (names will be ['Individual', 'Household', 'Organization'], labels will be localized translations if the site is not in English).
+
+!!! tip
+    Unless you are building a form and need to render an option list for the user to select, in most cases
+    you will not need to query `getFields` to e.g. match option ids to labels. The syntax below can automatically
+    perform such transformations.
+
+## Option transformations
+
+When reading or writing data from the API, a special suffix tells the API to transform between option ids and other properties. For example:
+
+### Writing
+
+```php
+Activity::create()
+  ->addValue('activity_type_id:name', 'Meeting')
+  ...
+```
+
+Using this syntax saves you from needing to look up the id of an activity type.
+It also makes your code more portable, as option ids can change from one database to another, but names are consistent.
+
+### Reading
+
+Get operations use the same syntax to reverse the lookup and transform an option id to another property. 
+
+```php
+Activity::get()
+  ->addSelect('*', 'activity_type_id:label', 'activity_type_id:icon')
+  ...
+```
+
+This tells the API to return all fields (`*`) plus the label and icon of the activity type, giving the data needed for a user-facing display.
+
+!!! note "Option Lists or Joins"
+    The syntax for option transformations looks very similar to [implicit joins](implicit-joins.md) (the difference being a colon instead of a dot). Your choice of which to use depends on the field.
+    For example, the Contact `gender_id` field has an option list but not a foreign key, so you must use the option syntax (`gender_id:label`).
+    But the Event `campaign_id` field has a foreign key instead of an option list, so you would use a join (`campaign_id.title`).
\ No newline at end of file

docs/api/v4/rest.md

+# APIv4 REST
+
+## Overview
+
+<!--
+FIXME: When the explorer is updated, enable the comments about it...
+
+!!! tip "Get started with APIv4 Explorer"
+
+    CiviCRM has a built-in tool for working with APIv4 (`Support => Developer => APIv4 Explorer`). You may use
+    this to generate complete HTTP/REST examples that are tuned to your instance of CiviCRM.
+
+    This documentation provides a deeper explanation of the HTTP/REST interface.
+-->
+
+CiviCRM APIv4 provides HTTP/REST bindings, enabling remote applications to read and write data.
+
+As you may recall, the APIv4 architecture uses the triplet [(`$entity`, `$action`, `$params`)](usage.md), e.g.
+
+```php
+$result = civicrm_api4($entity, $action, $params);
+$result = civicrm_api4('Contact', 'get', ['limit' => 10]);
+```
+
+A typical APIv4 REST request includes these three elements and an authentication credential. For example:
+
+```
+https://{$website}/civicrm/ajax/api4/{$entity}/{$action}
+  ?params={$params}&_authx={$credential}
+```
+
+In the remaining sections, we will examine this formula more closesly - considering more concrete examples
+and more precise descriptions of each part.
+
+??? question "Is APIv4 a REST-ful interface?"
+
+    HTTP-based APIs are sometimes described as "REST-ful" if they closely follow certain HTTP conventions.  CiviCRM APIv4 is more REST-ful than APIv3, but it is not strictly REST-ful.
+
+    Never-the-less, it is generally used for reading and writing resource records, and (by tradition) the subsystem is referred to as "REST".
+
+## Examples
+
+As we review the structure of an APIv4 REST call, it may help to have a few examples. Here is a representative example:
+
+```
+1: GET https://www.example.org/civicrm/ajax/api4/Contact/get
+2:   ?params=%7B%22where%22%3A%5B%5B%22id%22%2C%22%3D%22%2C22%5D%5D%7D
+3:   &_authx=ABCD1234
+```
+
+In line 1, we see an *end-point (base) URL* (`https://www.example.org/civicrm/ajax/api4`) along with entity and action (`Contact/get`). Line 2 conveys the specific API data-parameters (encoded as JSON form-data). Line 3 provides the *authentication* parameters.
+
+Similar elements should appear in any API call, but the content of each can differ. Here is another example:
+
+```
+1: POST https://crm.example.org/civicrm/ajax/api4/OptionGroup/get
+2: Authorization: Basic dXNlcjpwYXNz
+3: X-Requested-With: XMLHttpRequest
+4:
+5: %7B%22where%22%3A%5B%5B%22name%22%2C%22%3D%22%2C%22activity_type%22%5D%5D%2C%22limit%22%3A25%2C%22debug%22%3Atrue%7D
+```
+
+Here, we have a different *end-point (base) URL* (line 1; `https://crm.example.org/civicrm/ajax/api4`) with a different entity and action (`OptionGroup/get`). Line 2 shows a different *authentication* style. The specific API data also differs (line 5).
+
+
+## End-Point URL
+
+All requests should be submitted to the CiviCRM route `civicrm/ajax/api4/{ENTITY}/{ACTION}`.
+
+Requests are typically submitted with HTTP POST, but read-only operations may use HTTP GET.
+
+??? info "Comparison: URLs on Backdrop, Drupal, Joomla, WordPress"
+
+    On Drupal, Backdrop, and some WordPress deployments, you may access it with a clean URL.
+
+    ```
+    https://example.org/civicrm/ajax/rest
+    ```
+
+    In other deployments, you may need a verbose URL - such as these WordPress and Joomla URLs:
+
+    ```
+    https://wordpress.example.org/wp-admin/admin.php?page=CiviCRM&q=civicrm/ajax/rest
+    https://joomla.example.org/administrator/index.php?option=com_civicrm&task=civicrm/ajax/rest
+    ```
+
+    The `civicrm/ajax/rest` end-point is frequently used for browser-based API calls ("AJAX"). In newer versions (CiviCRM v5.36+), it can also be used for remote applications.
+
+    Stylisitcally, this is similar to [APIv4 REST](../v4/rest.md) end-point.
+
+## Authentication
+
+Every request for APIv4 should include authentication details. These may be submitted in a few forms, such as:
+
+```
+/* HTTP parameter */
+?_authx=Bearer+MY_API_KEY
+?_authx=Bearer+MY_JSON_WEB_TOKEN
+?_authx=Basic+B64(USER:PASS)
+
+/* Civi HTTP header */
+X-Civi-Auth: Bearer MY_API_KEY
+X-Civi-Auth: Bearer MY_JSON_WEB_TOKEN
+X-Civi-Auth: Basic B64(USER:PASS)
+
+/* Conventional HTTP header */
+Authorization: Bearer MY_API_KEY
+Authorization: Bearer MY_JSON_WEB_TOKEN
+Authorization: Basic B64(USER:PASS)
+```
+
+!!! tip "Which authentication forms can I use?"
+
+    By default, new AuthX deployments are configured to accept:
+
+    * __[Credentials](../../framework/authx.md#credentials)__: API keys or JSON Web Tokens (*Passwords are not accepted by default.*)
+    * __[Flows](../../framework/authx.md#flows)__: `?_authx=`, `X-Civi-Auth:`, or `Authorization:`
+
+    The system administrator may enable or disable support for each credential and flow.
+
+    Some hosting environments may have compatibility issues with `Authorization:`. If you need to communicate with
+    several different CiviCRM deployments, then `?_authx=` and `X-Civi-Auth:` may be more reliable.
+
+    For API keys and passwords, the user must have the matching permission (`authenticate with api key` or
+    `authenticate with password`).
+
+## X-Requested-With
+
+To ensure broad compatibility, APIv4 REST clients should set this HTTP header:
+
+```http
+X-Requested-With: XMLHttpRequest
+```
+
+The header is not required for all requests, but sometimes it is required, and there is generally no harm to
+setting it.
+
+For more complete details, see [Cross-Site Request Forgery (CSRF)](../../security/csrf.md) and specifically
+[CSRF: APIv4/APIv4 REST](../../security/csrf.md#rest).
+
+## Parameters
+
+APIv4 `$params` are transmitted with JSON and URL encoding. Thus, if the PHP `$params` are:
+
+```php
+['limit' => 10]
+```
+
+Then the equivalent JSON will be:
+
+```javascript
+{"limit":10}
+```
+
+and the URL-encoded JSON will be:
+
+```
+%7B%22limit%22%3A10%7D
+```
+
+## Response
+
+The response will be a JSON document. A well-formed response provides a list of `values`:
+
+```javascript
+{
+    "version": 4,
+    "count": 10,
+    "values": [
+        {
+            "contact_id": "1",
+            "contact_type": "Individual",
+            "contact_sub_type": "",
+            "display_name": "Example Person",
+            ...
+```
+
+Alternatively, if there is an error, then it will be reported with `error_message` and `error_code`:
+
+```javascript
+{
+  "error_code": 0,
+  "error_message": "Api FakeEntity fakeAction version 4 does not exist.",
+}
+```
+
+## History
+
+* __CiviCRM v5.19__: Added HTTP bindings for APIv4 to `civicrm-core`.  However, these were only available for
+  browser-based AJAX applications -- not for remote REST applications.
+
+* __CiviCRM v5.36__: Added the [AuthX extension](../../framework/authx.md) to `civicrm-core`.  This enabled REST-style
+  authentication for APIv4.  However, configuring AuthX may require CLI interaction to update hidden settings.
+
+* __CiviCRM v5.47__: Added the AuthX configuration screen, making it easier for more sysadmins to setup.

docs/api/v4/set-ops.md

+# APIv4 SET Operations
+
+## Background
+
+SQL **Set Operations** are ways of combining the results of multiple queries.
+
+- **UNION ALL**: Combines the results of two or more SELECT statements into a single result set, eliminating duplicate rows.
+- **UNION DISTINCT**: A UNION which eliminates duplicate rows.
+- **INTERSECT**: Returns the common elements between two or more SELECT statements, resulting in a result set that contains only the shared rows.
+- **EXCEPT**: Retrieves the rows from the first SELECT statement that are not present in the result set of the second SELECT statement, effectively finding the difference between the two result sets.
+
+As of version 5.64, APIv4 adds support for UNION ALL and UNION DISTINCT. It does not yet support INTERSECT or EXCEPT because
+the minimum version of MySql would need to be bumped to 8.0. Once that's done in a future version, those operations can be
+supported as well.
+
+## The `EntitySet` API
+
+By calling the `EntitySet` API and adding 2 or more sets to combine, you effectively create a new entity/table which
+can be operated on as a whole (SELECT, WHERE, HAVING, ORDER BY, LIMIT).
+
+For example, you could UNION together a set of Contributions and Contribution Soft Credits,
+then apply a GROUP BY clause to the combined results.
+
+!!! warning Columns Must Match
+    Per the rules of SQL Set Operations, each set must have the same number of fields selected,
+    with matching data types.
+    They will be combined in that order (not by name) and the field names of the first set will be used for the entire EntitySet.
+
+Try it yourself in the API Explorer:
+
+![APIv4 Explorer EntitySet](../../img/api4/entityset-unions.png)
\ No newline at end of file

docs/api/v4/usage.md

+# APIv4 Usage
+
+## API Input
+
+Every API call consists of three elements: the *entity*, *action*, and *parameters*:
+
+**Entity:** The "name" of the API.
+CiviCRM entities include Contacts, Activities, Contributions, Events, etc.
+Each API entity usually (but not always) corresponds to a table in the database (e.g. the Contact entity is the `civicrm_contact` table).
+
+!!! info "Supported Entities"
+    The ongoing effort to port APIv3 entities to v4 is nearing completion.
+    For updates or to help port a new entity, see this [tracking issue](https://lab.civicrm.org/dev/core/-/issues/2486).
+
+**Action:** The "verb" of the API. The [list of available actions](actions.md) varies for each entity, but most support
+a set of CRUD actions to `create`, `get`, `update` & `delete`, etc.
+ 
+**Parameters:** Settings or data to pass to the api function. Each action accepts a different set of parameters.
+
+Consider these samples with commonly-used actions and parameters for the `Contact` entity:
+
+| Action   | Parameters                           | Description                     |
+|----------|--------------------------------------|---------------------------------|
+| `create` | `#!json {"values":{"contact_type":"Individual", "first_name":"Jane", "last_name":"Doe"}}` | Create a new contact of type "Individual" with first name "Jane" and last name "Doe" |
+| `get`    | `#!json {"where":[["last_name", "=", "Doe"]], "limit":25}`                | Fetch the first 25 contacts with the last name "Doe" |
+| `delete` | `#!json {"where":[["id", "=", 42]]}` | Delete the contact with id "42" |
+
+!!! tip "API Explorer"
+    For full, up-to-date details about specific entities, actions and parameters, use the [API Explorer](../index.md#api-explorer).
+
+## API Output
+
+The API returns an array, with each item representing one record (also an array).
+In PHP, this output is contained in an ArrayObject, which can be accessed like an array using e.g. `$result[0]` or `foreach ($result as ...)`.
+
+See the [php docs](https://www.php.net/manual/en/class.arrayobject.php) for a full list of methods ArrayObjects support
+
+It also has the following methods in addition to or overriding the base ArrayObject:
+
+- `$result->first()`: returns the first item, or NULL if not found.
+- `$result->single()`: returns a single item, or throws an exception if not exactly one item was returned.
+- `$result->last()`: returns the last item, or NULL if not found.
+- `$result->itemAt($index)`: returns the item at a given index, or NULL if not found.
+- `$result->indexBy($field)`: reindexes the array by the value of a field.
+- `$result->column($field)`: flattens the array, discarding all but a single field (call this second if using in conjunction with `indexBy` to create a key=>value array).
+- `$result->count()`: get the number of fetched (if LIMIT used) or matching results (if `row_count` included in select). See below.
+- From CiviCRM 5.50+ `$result->countFetched()`: get the number of *fetched* results. If you used LIMIT this won't exceed that number (but could be less).
+- From CiviCRM 5.50+ `$result->countMatched()`: get the total number of *matching* results. If you only fetched a subset (with LIMIT) you are required to add `row_count` to the select clause.
+
+!!! Converting ArrayObject to a Real Array
+    If you need to use functions such as `is_array` on the result you can cast it you cast it to an array, `(array) $result`, or use the [`getArrayCopy()`](https://www.php.net/manual/en/arrayobject.getarraycopy.php) method.
+
+### Counting results
+
+Prior to 5.50, there was just one count available via `count()`. From 5.50+ it is clearer to use one of the new methods instead: `countFetched()` and `countMatched()` because `count()` can return different counts based on a number of factors (see below). Note that the `rowCount` *property* should not be considered a public interface and any code using it directly should be migrated to use a method instead.
+
+**TL;DR**: If you need to know the number of *matched* rows regardless of any fetch limit, you must add `row_count` to the select. You can do this by calling `selectRowCount()` (note that this will replace any prior selects).
+
+e.g. consider the database contains 100 contacts and you're using the `Contact.get` API.
+
+`$result = $api->addSelect('display_name')->execute()` will fetch the names of all contacts.
+
+- `$result->countFetched()` will return 100.
+
+- `$result->countMatched()` will return 100 too, since this is known as there was no limit.
+
+- `$result->count()` will return 100.
+
+`$result = $api->addSelect('display_name')->setLimit(10)->execute()` will fetch the names of 10 contacts.
+- `$result->countFetched()` will return 10.
+- `$result->countMatched()` will return throw an exception because it cannot be calculated from the result.
+- `$result->count()` will return 10.
+
+`$result = $api->selectRowCount()->addSelect('display_name')->setLimit(10)->execute()` will fetch the names of 10 contacts and also calculate the total matched.
+- `$result->countFetched()` will return 10.
+- `$result->countMatched()` will return 100.
+- `$result->count()` will return 100.
+
+`$result = $api->selectRowCount()->execute()` will not fetch any records, but will make the count available:
+- `$result->countFetched()` will return 0 (since we did not fetch any data rows).
+- `$result->countMatched()` will return 100.
+- `$result->count()` will return 100.
+
+`$result = $api->selectRowCount()->setLimit(10)->execute()` is a funny thing to do (set a limit for records without asking for records anyway) but it will behave as if you had not included the `setLimit()` clause, i.e. exactly as the last example.
+
+`$result = $api->selectRowCount()->addSelect('display_name')->execute()` is strictly unnecessary since it fetches all records anyway, so the `selectRowCount()` is superfluous.
+- `$result->countFetched()` will return 10.
+- `$result->countMatched()` will return 100.
+- `$result->count()` will return 100.
+
+## Example
+
+<iframe src="https://learn.civi.be/wp-admin/admin-ajax.php?action=h5p_embed&id=6" width="680" height="480" frameborder="0" allowfullscreen="allowfullscreen"></iframe>
+
+## API Security
+
+By default, APIv4 validates every action according to the permission level of the logged-in user.
+This can be disabled only when calling via [PHP code](usage.md#php). API Permissions are also able to be altered via hook.
+
+More information on API Security can be found in the [Security Documentation](../../security/permissions.md).
+
+## API Interfaces
+
+The API is available in many environments (such as PHP, CLI, and JavaScript), and the notation differs slightly in each language.
+However, if you understand the canonical notation, then others will appear as small adaptations.
+
+!!! note "Use Outside of CiviCRM"
+    If you're writing a Drupal module, a Joomla extension, a WordPress plugin, or a standalone script, then you may need to [bootstrap](../../framework/bootstrap.md) CiviCRM before using the API.
+
+### PHP
+
+This is the canonical API; all other environments are essentially wrappers around the PHP API.
+
+There are two ways to call the api from PHP - which one you choose is a matter of convenience and personal preference.
+For example, you may prefer OOP syntax because IDE code editors provide autocompletion.
+Or if you need to work with the parameters as an array, traditional syntax will be more convenient.   
+
+![APIv4 PHP Examples](../../img/api4/Api4-PHP-Styles.svg)
+
+#### Traditional (Procedural)
+
+*The function `civicrm_api4($entity, $action, [$params], [$index])` accepts an array of parameters and returns the Result.*
+
+```php
+$result = civicrm_api4('Contact', 'get', [
+  'where' => [
+    ['last_name', '=', 'Adams'],
+    // Option transformation.
+    ['gender_id:name', '=', 'Male'],
+    // Implicit join.
+    ['employer_id.is_opt_out', '=', FALSE],
+  ],
+  'limit' => 25,
+]);
+```
+
+`$index` provides a convenient shorthand for reformatting the Result array. It has different modes depending on the variable type passed:
+
+* **Integer:** return a single result array; e.g. `$index = 0` will return the first result, 1 will return the second, and -1 will return the last.
+* **String:** index the results by a field value; e.g. `$index = "name"` will return an associative array with the field 'name' as keys.
+* **Non-associative array:** return a single value from each result; e.g. `$index = ['title']` will return a non-associative array of strings - the 'title' field from each result.
+* **Associative array:** a combination of the previous two modes; e.g. `$index = ['name' => 'title']` will return an array of strings - the 'title' field keyed by the 'name' field.
+
+#### Object-Oriented (OOP)
+
+*An `Action` class provides setter methods for each parameter. The `execute()` method returns the Result.*
+
+```php
+$result = \Civi\Api4\Contact::get()
+  ->addWhere('last_name', '=', 'Adams')
+  ->addWhere('gender_id:name', '=', 'Male')
+  ->setLimit(25)
+  ->execute();
+```
+
+!!! warning "Warning: Class names don't always match entity names!"
+    For example, the entity "Case" is a reserved word in PHP and therefore could not be the name of a class, so it had to be named something else ("CiviCase").
+    Internally, calling `civicrm_api4('Case', 'getFields')` will translate to `Civi\Api4\CiviCase::getFields`.
+    [Custom data entities](custom-data.md) are another example.
+    When writing generic functions that work with multiple entities, we strongly recommend against clever code like this: `call_user_func(['\Civi\Api4\' . $entity, 'get'], ...)`,
+    and suggest using this more reliable alternative: `civicrm_api4($entity, 'get', ...)`.
+
+
+### AJAX
+
+The AJAX interface is automatically available for web-pages generated through CiviCRM (such as standard CiviCRM web-pages, CiviCRM extensions and custom CiviCRM templates).
+
+Inputs are identical to the traditional PHP syntax:
+
+```javascript
+CRM.api4('entity', 'action', [params], [index])
+```
+
+From an Angular app, use the service `crmApi4()` which has an identical signature but works within the `$scope.digest` lifecycle.
+
+Both functions return a Promise, which resolves to a Result array.
+
+```javascript
+CRM.api4('Contact', 'get', {
+  where: [
+    ['last_name', '=', 'Adams'],
+  ],
+  limit: 25
+}).then(function(results) {
+  // do something with results array
+}, function(failure) {
+  // handle failure
+});
+```
+
+!!! note "Use on Non-CiviCRM Pages"
+    The AJAX interface could be made available to other parts of the same website (e.g. a Drupal module or WordPress widget) by calling `#!php Civi::resources()->addCoreResources()`
+    from PHP. Please note that the AJAX interface is subject to [API Security](../../security/permissions.md#api-permissions)
+    and [Same Origin Policy](http://en.wikipedia.org/wiki/Same_origin_policy).
+
+### Command line
+
+#### cv
+
+`cv` supports multiple input formats for APIv4. The API Explorer uses the JSON format in generated code:
+
+```bash
+cv api4 Contact.get '{"where":[["first_name", "=", "Alice"], ["last_name", "=", "Roberts"]]}'
+```
+
+This format may be cumbersome to enter manually, so the same API request could also be written like this:
+
+```bash
+cv api4 Contact.get +w 'first_name = "Alice"' +w 'last_name = "Roberts"'
+```
+
+For more examples, refer to the output of `cv --help api4`.
+
+#### drush
+
+Adding `version=4` to a drush command will cause v4 api to be called rather than v3.
+
+#### wp-cli
+
+APIv4 is not yet available as a wp-cli command.
+
+### Smarty
+
+Because Smarty is an older technology, there are no plans to port the APIv3 smarty function to APIv4.
+
+### Scheduled jobs
+
+APIv4 is not yet available for scheduled jobs.

docs/basics/community.md

 # CiviCRM Developer Community
 
-Developers from around the globe use the following systems to communicate and
-collaborate:
+## Collaboration tools
+
+Developers from around the globe use the following systems to communicate and collaborate:
 
 -   [CiviCRM.org](https://civicrm.org)
     -   [Extensions](https://civicrm.org/extensions) publishing
     -   [Blog posts](https://civicrm.org/blog/) are written by both the CiviCRM core team and other community members, and cover a wide range of topics. Subscribe to the [RSS feed](https://civicrm.org/blog/feed) to make sure you stay up to date.
-    -   [Events](https://civicrm.org/events) -
-        meetups, conferences, camps, sprints, webinars
+    -   [Events](https://civicrm.org/events) - meetups, conferences, camps, sprints, webinars
     -   [Job Board](https://civicrm.org/jobs) - Post and find paid work
--   [Documentation](https://civicrm.org/documentation) including:
-    -   [User Guide](https://docs.civicrm.org/user/en/stable/)
-    -   [Developer Guide](https://docs.civicrm.org/dev/en/master/)
-        *(that you're reading now!)*
--   [Mattermost](https://chat.civicrm.org) offers live discussion in chat rooms and direct messages. It's a great place to go for any technical questions. Here, with a bit of luck, you'll often find an instant answer to your question or a pointer in the right direction. Definitely go here if you feel like you are banging your head against a wall.
--   [StackExchange](http://civicrm.stackexchange.com/) - Question & answer site covering a range of topics relevant to developers and users. It is a great place to find answers to the millions of questions that have already been asked about CiviCRM, and to ask ones that haven't been asked already.
--   [Jira](https://issues.civicrm.org/jira) - Issue tracking
+-   [Documentation](https://docs.civicrm.org)
+-   [Mattermost](https://chat.civicrm.org) offers live discussion in chat rooms and direct messages. It's a great place to go for any technical questions. Here, with a bit of luck, you'll often find an instant answer to your question or a pointer in the right direction. Definitely go here if you feel like you are banging your head against a wall. New developers can check out the [dev-newcomers](https://chat.civicrm.org/civicrm/channels/dev-newcomers) channel for discussion on getting started with developing for CiviCRM.
+-   [Stack Exchange](http://civicrm.stackexchange.com/) - Question & answer site covering a range of topics relevant to developers and users. It is a great place to find answers to the millions of questions that have already been asked about CiviCRM, and to ask ones that haven't been asked already.
+-   [GitLab](https://lab.civicrm.org) - CiviCRM's tool for issue tracking community-based project management.
 -   [GitHub](https://github.com/civicrm) - Hosted git repositories for the entire CiviCRM codebase, as well as many smaller tools focused on developing CiviCRM.
--   [Discussion Mailing Lists](https://lists.civicrm.org/lists/)
--   [Newsletters](https://civicrm.org/civicrm/mailing/subscribe)
--   Falling out of use
-    -   [Wiki] - still used for specs & recipes, *but documentation
-        [is moving][migration] to the guides listed above*
-    -   [IRC](http://irc.civicrm.org/) - #civicrm on irc.freenode.net
-        *but now mostly replaced by Mattermost*
-    -   [Forum](https://forum.civicrm.org/) - *now mostly replaced by
-        StackExchange*
-
-[wiki]: https://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Documentation
-[migration]: https://wiki.civicrm.org/confluence/display/CRMDOC/Content+migration+from+wiki+to+Developer+Guide
-
-The developer community is full of friendly people, eager to welcome newcomers.
-Mattermost and in-person events are great starting points if you're looking to
-get involved!
 
+!!! tip "Before you begin"
+
+    Register for the accounts below. *All accounts require e-mail verification.*
+
+    1.  [CiviCRM.org](https://civicrm.org/user/register) - Be prepared to give your name and organizational affiliation, and explain your role in the community.
+        *Account requests must be approved by an administrator before you will be granted access.* This process may take some time.
+
+        The following communities provide a single sign-on once your CiviCRM.org account is approved.
+
+         -   GitLab
+
+    2.  [Mattermost](https://chat.civicrm.org/signup_email) - Create an account and join a team on this open-source version of Slack.
+
+    3.  [Stack Exchange](https://civicrm.stackexchange.com/users/signup?ssrc=head&returnurl=https%3a%2f%2fcivicrm.stackexchange.com%2f) - Read the user guide after joining. Write your own Q&A and vote on others'.
+
+    4.  [GitHub](https://github.com/join?source=header) - Find repositories under CiviCRM's group after confirming your account.
+    
+!!! warning "Don't include a space in your username"
+
+    CiviCRM.org allows spaces in usernames but this won't work with GitLab.  So it's best if you don't use any spaces in your CiviCRM.org username. 
+    
+    If you have already set up an account on CiviCRM.org you can easily log in and change your username.
+
+## Discussion communities
+
+Optional lists you may also want to register for:
+
+-   [Newsletters](https://civicrm.org/civicrm/mailing/subscribe) (after your CiviCRM account is active)
+
+## Falling out of use
+
+-   [CiviCRM Groups](https://lists.civicrm.org/lists/firstpasswd/) - (listservs)   *but now mostly replaced by Mattermost*
+
+## Out of use
+
+-   [IRC](http://irc.civicrm.org/) - #civicrm on irc.freenode.net *No longer officially supported by the CiviCRM organization, and functionally replaced by Mattermost*
+
+-   [Wiki](https://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Documentation) - *Archived in November 2017, but still useful for some older documentation. Developer and admin docs have been moved to [MkDocs](https://docs.civicrm.org/). Other documentation should be moved to their respective [Gitlab wiki spaces](https://lab.civicrm.org/explore/groups).*
+
+-   [Forum](https://forum.civicrm.org/) - *Archived on November 25, 2017*
+
+-   [Jira](https://issues.civicrm.org) - *Archived on December 27, 2018. You can still access old (read-only) JIRA issues if you know their issue number and you can also browse the archived issues for a specific project.*
+
+
+The developer community is full of friendly people, eager to welcome newcomers. Mattermost and in-person events are great starting points if you're looking to get involved!

docs/basics/planning.md

@@ -2,110 +2,59 @@
 
 ## Community input
 
-Before you start on any code to extend CiviCRM, it is really important
-to discuss your ideas with the community. Here are a few of the reasons
-why this is a good idea:
-
--   It may have been done already
--   You'll get suggestions and advice on suitable ways to approach the
-    problem
--   Other people will know what you are doing, and be able to contact
-    you if they want to collaborate
-
-A typical pre-development workflow will start with a discussion on
-[Mattermost](https://chat.civicrm.org/) (in the Developer channel) about what
-you want to do. Here you'll receive feedback from other members of the
-community and core team about your ideas. You might be lucky and find
-out that there is a already a way to do what you want using the user
-interface (and that no coding is necessary). Or it might be that someone
-has done something similar already and all that is required is a few
-tweaks to their code.
+Before you start on any code to extend CiviCRM, it is really important to discuss your ideas with the community. Here are a few of the reasons why this is a good idea:
 
+-   It may have been done already.
+-   You'll get suggestions and advice on suitable ways to approach the problem.
+-   Other people will know what you are doing, and be able to contact you if they want to collaborate.
+
+A typical pre-development workflow will start with a discussion on [Mattermost](https://chat.civicrm.org/) (in the Developer channel) about what you want to do. Here you'll receive feedback from other members of the community and core team about your ideas. You might be lucky and find out that there is a already a way to do what you want using the user interface (and that no coding is necessary). Or it might be that someone has done something similar already and all that is required is a few tweaks to their code.
 
 ## Requirements and specifications
 
-If and when you have confirmed that some coding is required, it is good
-practice, even for relatively small projects, to write
-
--   a requirements document which describes in detail what you want the
-    finished code to do
--   a specification that outlines how you are going to meet these
-    requirements with CiviCRM
-
-The requirements are typically written to be understandable to end
-users, and the specification can be thought of as a translation of those
-requirements into the language of CiviCRM. Both requirements and
-specification should go on the
-[wiki](http://wiki.civicrm.org/confluence/display/CRM/CiviCRM+Wiki).
-
-Once you've written the requirements and specification document, you
-should go about soliciting feedback.  Get feedback on the requirements
-from your end users and feedback on the requirements and the
-specification from anyone that is willing to comment. To encourage more
-discussion, you can write a post on CiviCRM's
-[blog](https://civicrm.org/blog/), tweet it out with
-the [#civicrm](https://twitter.com/hashtag/civicrm) hashtag, tell similar
-CiviCRM users and organisations and so on.
-The more feedback you can get the better.
+If and when you have confirmed that some coding is required, it is good practice, even for relatively small projects, to write:
+
+-   a requirements document which describes in detail what you want the finished code to do, and
+-   a specification that outlines how you are going to meet these requirements with CiviCRM.
+
+The requirements are typically written to be understandable to end users, and the specification can be thought of as a translation of those requirements into the language of CiviCRM. 
+
+Store your requirements and specifications in a public location such as:
+
+* a markdown file in your project's repository,
+* a google doc, or 
+* the [CiviCRM wiki](http://wiki.civicrm.org/confluence/display/CRM/CiviCRM+Wiki).
+
+Once you've written the requirements and specification document, you should go about soliciting feedback.  Get feedback on the requirements from your end users and feedback on the requirements and the specification from anyone that is willing to comment. To encourage more discussion, you can write a post on CiviCRM's [blog](https://civicrm.org/blog/), tweet it out with the [#civicrm](https://twitter.com/hashtag/civicrm) hashtag, tell similar CiviCRM users and organisations and so on. The more feedback you can get the better.
 
 !!!tip
-    If you get stuck writing your requirements and specification, or would
-    like to get more background, have a look at some
-    [existing requirements and specifications](https://wiki.civicrm.org/confluence/display/CRM/Requirements+and+specifications)
-    from CiviCRM developers.
+    If you get stuck writing your requirements and specification, or would like to get more background, have a look at some [existing requirements and specifications](https://wiki.civicrm.org/confluence/display/CRM/Requirements+and+specifications) from CiviCRM developers.
+
+## Bugs
+
+Before starting work on a bug, your first step should be to check the [issue tracking systems](../tools/issue-tracking.md) for any open issues before creating one yourself or working on a pull request.
+
+In order to reproduce the bug you can reproduce the issue in the appropriate [CiviCRM Sandbox](https://civicrm.org/sandboxes). Enabling debugging can help to get more details.
+
+Make sure to check [the contribution guidelines](../core/contributing.md) for more information on how to create a pull request.
 
 ## Recommendations
 
-**Open a free [GitHub](https://github.com/) account** for revision control.
-The official CiviCRM [repositories](https://github.com/civicrm)
-are housed in `git` repositories on GitHub.  If you use GitHub you will find
-it easy to access the latest source-code, to submit pull requests
-for any patches you create and to collaborate with many other
-CiviCRM developers who also use GitHub.
-
-**Install the [buildkit](https://github.com/civicrm/civicrm-buildkit)**,
-ideally as a [vagrant virtual-machine](https://github.com/civicrm/civicrm-buildkit-vagrant)
-or using one of available `docker` images ([1](https://github.com/progressivetech/docker-civicrm-buildkit),
-[2](https://github.com/ErichBSchulz/dcbk)). The buildkit is not an absolute
-requirement but it is definitely the fastest path to a good development
-experience!
-
-**From the outset, [automate testing](https://wiki.civicrm.org/confluence/display/CRMDOC/Testing)**.
-In the current climate of rapid evolution of not just CiviCRM, but
-also it's myriad of dependancies, automated testing of PHP code with `phpunit`
-and javascript with tools like `karma` and `jasmine` is essential. Start all
-your work by considering how you will provide automated testing for it.
-Starting with the buildkit will make this much simpler for you to set up.
-Getting started with unit-testing may seem daunting and onerous when you start,
-but you will soon come to love the freedom it gives you. If you are
-unsure how to proceed with testing ask the [community](/basics/community).
-
-**Create a native [extension](/extensions/basics)**.
-If you have new functionality to add to CiviCRM, it probably belongs in an
-extension. "Native" extensions will install into all CiviCRM sites
-regardless of the  underlying CMS used (Drupal or Wordpress), making it easy to
-share your extension with the CiviCRM community.
-
-**Use the [API](/api/general) and [hooks](/hook)** to access and manage CiviCRM data in any patch,
-native extension, CMS module, or external program that you
-develop. The API will function as expected with every new release
-and backwards compatibility of the API is maintained for several
-versions of CiviCRM.
-
-**Avoid [hacking the core](/core/hacking)** of CiviCRM unless you understand
-the implications.
-
-**Follow the
-[Coding Standards](https://wiki.civicrm.org/confluence/display/CRMDOC/Coding+Standards)**
-for uniform structure that will make everyone's development work easier.
+**Open a free [GitHub](https://github.com/) account** for version control. The official CiviCRM [repositories](https://github.com/civicrm) are housed in `git` repositories on GitHub.  If you use GitHub you will find it easy to access the latest source-code, to submit pull requests for any patches you create and to collaborate with many other CiviCRM developers who also use GitHub.
+
+**Install the [buildkit](https://github.com/civicrm/civicrm-buildkit)**, ideally as a [vagrant virtual-machine](https://github.com/civicrm/civicrm-buildkit-vagrant) or using one of available `docker` images ([progressivetech](https://github.com/progressivetech/docker-civicrm-buildkit) or [EricBSchulz](https://github.com/ErichBSchulz/dcbk)). The buildkit is not an absolute requirement but it is definitely the fastest path to a good development experience!
+
+**From the outset, [automate testing](../testing/index.md)**. In the current climate of rapid evolution of not just CiviCRM, but also it's myriad of dependencies, automated testing of PHP code with `phpunit` and javascript with tools like `karma` and `jasmine` is essential. Start all your work by considering how you will provide automated testing for it. Starting with the buildkit will make this much simpler for you to set up. Getting started with unit-testing may seem daunting and onerous when you start, but you will soon come to love the freedom it gives you. If you are unsure how to proceed with testing ask the [community](community.md).
+
+**Create a native [extension](../extensions/index.md)**. If you have new functionality to add to CiviCRM, it probably belongs in an extension.  "Native" extensions will install into all CiviCRM sites regardless of the  underlying CMS used (Drupal, WordPress, Joomla or Backdrop), making it easy to share your extension with the CiviCRM community.
+
+**Use the [API](../api/index.md) and [hooks](../hooks/index.md)** to access and manage CiviCRM data in any patch, native extension, CMS module, or external program that you develop. The API will function as expected with every new release and backwards compatibility of the API is maintained for several versions of CiviCRM. 
+
+**Avoid [hacking the core](../core/hacking.md)** of CiviCRM unless you understand the implications.
 
+**Follow the [Coding Standards](../standards/index.md)** for uniform structure that will make everyone's development work easier.
 
 ## Make it happen
 
-If you need or would like extra resources for your code improvement, you
-might consider a [Make It Happen](https://civicrm.org/make-it-happen)
-(aka MIH) campaign, which is a crowd-sourcing initiative for CiviCRM.
-The MIH work is carried out by the
-core team or trusted consultants, and has helped build many amazing new
-features into CiviCRM in recent years.
+If you need or would like extra resources for your code improvement, you might consider a [Make It Happen](https://civicrm.org/make-it-happen) (aka MIH) campaign, which is a crowd-sourcing initiative for CiviCRM. The MIH work is carried out by the core team or trusted consultants, and has helped build many amazing new features into CiviCRM in recent years.
 

docs/basics/requirements.md

+# Development requirements
+
+## Languages and Services
+
+* Required
+    - Unix-like environment (Linux, OS X, or a virtual machine)
+    - [PHP v7.2+](http://php.net/) including the following extensions: `bcmath curl gd gettext imap intl imagick json mbstring openssl pdo_mysql phar posix soap zip`
+    - [MySQL v5.7.5+](http://mysql.com/) or [MariaDB 10.0.2+](https://mariadb.org/), including both client and server
+    - [NodeJS v8+](https://nodejs.org/)
+    - [Git](https://git-scm.com/)
+* Recommended (for `civibuild` / `amp`):
+    - Apache HTTPD v2.2 or v2.4 including the `mod_rewrite` module and, on SUSE, possibly `mod_access_compat` (This list may not be exhaustive.)
+
+Please also see [this Installation Guide page](https://docs.civicrm.org/installation/en/latest/general/requirements/) for more details on server configuration requirements to deploy CiviCRM installations using buildkit.
+
+## Command Line
+
+There are many ways to install MySQL, PHP, and other dependencies -- for example, `apt-get` and `yum` can download packages automatically; `php.net` and `mysql.com` provide standalone installers; and MAMP/XAMPP provide bundled installers.
+
+Civi development should work with most packages -- with a priviso: ***the command-line must support standard command names*** (eg `git`, `php`, `node`, `mysql`, `mysqldump`, etc).
+
+Some environments (e.g. most Linux distributions) are configured properly out-of-the-box. Other environments (e.g. MAMP and XAMPP) may require configuring the `PATH`.
+
+<!-- FIXME: There should be a link about diagnosing/fixing paths for third-party binaries. TLDR: `find / -name php -executable` and then update `PATH` via bashrc/bash_profile/whatever -->
+
+## Buildkit
+
+The developer docs reference a large number of developer tools, such as `drush` (the Drupal command line), `civix` (the CiviCRM code-generator), and `karma` (the Javascript tester).
+
+Many of these tools are commonly used by web developers, so you may have already installed a few.  You could install all the tools individually -- but that takes a lot of work.
+
+[civicrm-buildkit](../tools/buildkit.md) provides a script which downloads the full collection.

docs/build.md

-# Building CiviCRM
-
-TODO:
-
--   Nightlies vs gitify vs civibuild
--   gitify
--   civibuild (https://github.com/civicrm/civicrm-buildkit/blob/master/doc/civibuild.md)

docs/core/hacking.md

 ## When should I edit core CiviCRM?
 
 !!! danger
-      Most of the time, editing the core codebase directly
-      is not the recommended way for developers to customise and extend CiviCRM.
-      CiviCRM has two version releases per year so direct edits to the core codebase
-      will create upgrade issues for you.
-      There are other recommended ways for the majority of scenarios:
-      extensions, the APIs and hooks.
+      Most of the time, editing the core codebase directly is not the recommended way for developers to customise and extend CiviCRM. CiviCRM has multiple releases per year so direct edits to the core codebase will create upgrade issues for you. There are other recommended ways for the majority of scenarios: extensions, the APIs, and hooks.
 
 To help you decide, here are a couple of principles:
 
-- Bug fixes should always be applied to core. Information on how to submit your
-  bug fix will be added soon. <!--fixme!! -->
-- 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.
-- 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.
+- 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).

docs/customize.md

-# Customizing CiviCRM
-
-TODO:
-
--   *(Requirements: Don't need full git install)*
--   *(When possible, link to User/Admin Guide or other existing docs instead
-    of giving details.)*
--   Custom fields, profiles, option groups, etc
--   webform_civicrm
--   Extensions (download+install; web and CLI).
--   (Maybe) CiviRules
--   (Maybe) CSS override
--   (Maybe) *.extra.tpl