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,89 +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 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 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.
+
+## 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
 
-**Use Git and [GitHub](https://github.com/)** for revision control.
-The official CiviCRM [repositories](https://github.com/civicrm)
-are housed 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.
+**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/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.
+**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/general)** 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.
+**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. 
 
-**Follow the
-[Coding Standards](https://wiki.civicrm.org/confluence/display/CRMDOC/Coding+Standards)**
-for uniform structure that will make everyone's development work easier.
+**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/basics/skills.md

-# Prerequisite skills
+# Useful skills
 
 ## Learn how to *use* CiviCRM
 
-Before diving into CiviCRM development, it's worth mentioning that a solid
-understanding of CiviCRM from the *user's* perspective can really help. You
-pick up the standard user interface patterns that you can re-use in your work,
-and you might even realise that the UI already provides the functionality you
-wish to develop. To that end, please see the
-[User Guide](https://docs.civicrm.org/user/en/stable/).
-
+Before diving into CiviCRM development, it's worth mentioning that a solid understanding of CiviCRM from the *user's* perspective can really help. You pick up the standard user interface patterns that you can re-use in your work, and you might even realise that the UI already provides the functionality you wish to develop. To that end, please see the [User Guide](https://docs.civicrm.org/user/en/stable/).
 
 ## Learn these developer skills
 
-Below we've outlined the major technologies that CiviCRM is built with.
-You don't need to be a pro at everything listed here to get started, but it's
-useful to understand at least of couple of them well, and have a basic
-understanding of how they fit together to create CiviCRM.
+Below we've outlined the major technologies that CiviCRM is built with. You don't need to be a pro at everything listed here to get started, but it's useful to understand at least of couple of them well, and have a basic understanding of how they fit together to create CiviCRM.
 
-Technologies which are contained within the CiviCRM project
-(e.g. civix, buildkit) are covered in detail within this guide, but
-other technologies (such as PHP and Git, which are not CiviCRM-specific) are
-outside its scope. As such, this guide assumes that readers
-arrive with a baseline understanding of these developer skills. This page lists
-these prerequisite skills, along with pointers to usher the reader towards
-appropriate resources for closing skills gaps, wherever necessary.
-Items listed towards the top of this list are, generally-speaking, more
-important skills for CiviCRM development, but the specific skills needed to
-accomplishing a particular development goal, certainly vary.
+Technologies which are contained within the CiviCRM project (e.g. civix, buildkit) are covered in detail within this guide, but
+other technologies (such as PHP and Git, which are not CiviCRM-specific) are outside its scope. As such, this guide assumes that readers arrive with a baseline understanding of these developer skills. This page lists these prerequisite skills, along with pointers to usher the reader towards appropriate resources for closing skills gaps, wherever necessary. Items listed towards the top of this list are, generally-speaking, more important skills for CiviCRM development, but the specific skills needed to accomplishing a particular development goal, certainly vary.
 
--   **PHP** - the main programming language in which CiviCRM is written
+-   **PHP** - the main programming language in which CiviCRM is written.
     -   [Language reference](http://php.net/manual/en/langref.php)
--   **Git** - a version control system for tracking changes to source code
-    -   [Official documentation](https://git-scm.com/documentation)
-    -   [15 minute interactive tutorial](https://try.github.io/levels/1/challenges/1)
--   **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).
+-   **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)
+-   **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.*
--   **Javascript** - another programing language used in CiviCRM, especially
-    for any logic that happens within the web browser. *(Note that "javascript"
-    and "java" are entirely different technologies and should not be confused.)*
+    -   *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.*
+-   **Javascript** - another programing language used in CiviCRM, especially for any logic that happens within the web browser. *(Note that "javascript" and "java" are entirely different technologies and should not be confused.)*
     -   [Javascript tutorial](http://www.w3schools.com/js/default.asp)
--   **jQuery** - a javascript library that makes manipulating elements on a web
-    page easy
+-   **jQuery** - a javascript library that makes manipulating elements on a web page easy.
     -   [jQuery documentation](http://api.jquery.com/)
+-   **AngularJS** - a front-end javascript/html library providing a client-side framework for creating one-page MVC (model-view-controller) and MVVM (model-view-viewmodel) apps.
+    -   [angularJS documentation](https://docs.angularjs.org/)
 -   **HTML** - the markup used so transmit page content to a web browser.
     -   [HTML tutorial](http://www.w3schools.com/html/default.asp)
--   **Smarty** - a "template engine" which allows developers to write an HTML
-    file for one web page, while easily including content dynamically generated
-    from PHP
+-   **Smarty** - a "template engine" which allows developers to write an HTML file for one web page, while easily including content dynamically generated from PHP.
     -   [Smarty documentation](http://www.smarty.net/docs/en/)
--   **CSS** - a programming language used to specify consistent visual style to
-    be applied to many different elements within a web page. Different web
-    browsers interpret the CSS code in slightly different ways.
+-   **CSS** - a programming language used to specify consistent visual style to be applied to many different elements within a web page. Different web browsers interpret the CSS code in slightly different ways.
     -   [CSS tutorial](http://www.w3schools.com/css/default.asp)
-    -   [Can I use](http://caniuse.com/) - good for seeing which web browsers
-        have implemented certain CSS features
-    -   [Comparison of layout engines](https://en.wikipedia.org/wiki/Comparison_of_layout_engines_\(Cascading_Style_Sheets\))
-        another helpful comparison of the differences between web browsers
--   **Drupal / Wordpress / Joomla!** - CiviCRM must be installed within one of
-    these content management systems, and learning more about the underlying
-    CMS will aid CiviCRM development. Drupal is favored by most CiviCRM
-    developers and CiviCRM actually borrows many development practices from
-    the project, so learning Drupal is a good place to start if you are unsure.
+    -   [Can I use](http://caniuse.com/) - good for seeing which web browsers have implemented certain CSS features.
+    -   [Comparison of layout engines](https://en.wikipedia.org/wiki/Comparison_of_layout_engines_\(Cascading_Style_Sheets\)) another helpful comparison of the differences between web browsers.
+-   **Drupal / WordPress / Joomla!** - CiviCRM must be installed within one of these content management systems, and learning more about the underlying CMS will aid CiviCRM development. Drupal is favored by most CiviCRM developers and CiviCRM actually borrows many development practices from the project, so learning Drupal is a good place to start if you are unsure. That said, WordPress is the most popular CMS and it has been so for several years now. 
     -   [Drupal documentation](https://www.drupal.org/docs/)
-    -   [Wordpress documentation]()
-    -   [Joomla documentation]()
--   **SQL / MySQL** - "SQL" is a standardized language used by many different
-    kinds of databases to manipulate data in the database. "MySQL" is one kind
-    of database which CiviCRM uses to store all its data. The query syntax
-    that MySQL uses conforms [almost](http://troels.arvin.dk/db/rdbms/)
-    entirely to the SQL standard, so learning SQL is basically synonymous to
-    learning MySQL.
+    -   [WordPress documentation](https://codex.wordpress.org/Main_Page)
+    -   [Joomla documentation](https://docs.joomla.org/)
+-   **SQL / MySQL** - "SQL" is a standardized language used by many different types of database management systems to manipulate data in the database. "MySQL" is one specific database management system which, by default, CiviCRM uses to store all its data. The query syntax that MySQL uses conforms [almost](http://troels.arvin.dk/db/rdbms/) entirely to the SQL standard, so learning SQL is basically synonymous to learning MySQL.
     -   [SQL tutorial](http://www.w3schools.com/sql/default.asp)
     -   [MySQL statement syntax](http://dev.mysql.com/doc/refman/en/sql-syntax.html)
-    -   [MySQL Workbench](http://www.mysql.com/products/workbench/) -
-        an intuitively designed GUI tool for inspecting and interacting with a
-        MySQL database (great for learning more about the CiviCRM data model).
-
-
+    -   [MySQL Workbench](http://www.mysql.com/products/workbench/) - an intuitively designed GUI tool for inspecting and interacting with a MySQL database (great for learning more about the CiviCRM data model).

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/architecture.md

-# The codebase
-
-This chapter provides a general overview of the codebase organisation.
-
-In order to explore the directories inside the CiviCRM repository it is
-generally quickest to to make a local clone of the CiviCRM from GitHub.
-
-!!! tip
-    The CiviCRM codebase is object oriented. If you aren't familiar with object
-    oriented programming, spend a little time reading some beginner tutorials on
-    the net.
-
-## Namespaces
-Classes in CiviCRM must be placed in one of two folders:
-
-***`CRM`*** (e.g.: `CRM_Core_Invoke`)
-classes use PEAR-style class-naming conventions that were common up until
-PHP 5.2. Class names include underscores and MUST NOT use the PHP
-"[namespace](http://php.net/namespace)"
-directive. Use `CRM` style when creating classes that plug into existing `CRM`
-subsystems such
-as payment processors (CRM_Core_Payment) and reports (CRM_Report).
-
-***`Civi`*** (e.g.: `\Civi\API\Kernel`)
-"Civi" classes use PHP 5.3 namespaces. They MUST use the
-"[namespace](http://php.net/namespace)" directive.
-Namespaces are designated with "\".
-
-!!! note
-    At time of writing (May 2014, before Civi 4.5), some classes may not load
-    properly if they are in `Civi` – for example, the payment system will only load
-    payment-processor classes in `CRM_Core_Payment`. If you encounter problems like
-    this, please submit an issue or patch.
-
-!!! tip
-    The `Civi` namespace uses composer's PSR-0 autoloader. This autoloader does not
-    support custom PHP overrides.
-    Use `Civi` when creating new object-oriented subsystems (like `\Civi\API`).
-
-## Business logic
-Most of the business logic of CiviCRM, is found in the CRM directory (`CIVICRM_ROOT/CRM`).
-This logic is the part of CiviCRM that
-defines what it does and how it behaves
-(e.g. that allows people to register on events)
-In this directory, you will find directories for core CiviCRM functions like
-contacts, groups, profiles, deduping, importing, and the CiviCRM components
-like CiviCampaign, CiviMail, Pledges, etc.
-
-Each of these directories is slightly different depending on what they do but
-there are some common subdirectories: BAO, DAO, Form and Page.
-
-### DAO
-DAO stands for data access object.  Code in this directory exposes the contents
-of the database.  The DAOs are automatically generated for each release based
-on the data schema.  DAO objects tend to be instantiated in BAO classes.
-
-The DAO has a property for each field (using the actual field name, not the
-unique name).  They also have standard CRUD (create retrieve update delete) type
-functions, etc. <!--fixme why the etc? what else?? -->
-
-### BAO
-BAO stands for business access object.  BAOs map to DAOs and extend them with
-the business logic of CiviCRM.  A lot of the meat of CiviCRM is found in the
-BAOs, for example they have the code that creates follow up activities when an
-activity is created, or create activities and populating custom fields when a
-pledge is created.
-
-### Form
-In general each form page in CiviCRM maps to a file in one of
-the form directories.  Form files contain a class that extends CRM_Core_Form.
-This class has different methods that the core calls before display to
-check permissions, retrieve information (`preProcess`), display
-the form (`buildForm`), validate the form (`formRule`) and carry out tasks once the
-form is submitted (`postProcess`).  Forms can diplay information from the BAO
-to users and then call the BAO on submission. Generaly each form has an
-associated template (see below) which defines the form's html.
-
-!!! tip
-    Perhaps the best way to get to grips with the Forms is by experience and
-    experimentation.
-
-### Page
-If a CiviCRM screen is not a Form, it is probably a page.  Pages files contain a
-class that extend CRM_Core_Page.  Similar to the form class, Pages have methods
-that are called before the page is displayed to control access, set the title,
-etc. (`preProcess`), and when the page is displayed (`run`). Pages tend to
-take information from the BAO to be displayed to users. In general, each
-page has an associated template (see below) which is used to create the
-html of the page.
-
-### xml
-This directory contains a menu directory which maps urls to CRM form or page
-classes and controls access to these URLs using permissions.
-
-## Templates
-The templates directory contains all the HTML for pages and forms.  Directly
-inside the templates directory is a CRM directory.  In general, all templates
-map to a form or page class.  CiviCRM chooses a template for the form or page
-based on the class name.
-
-For example, the class CRM_Member_Form_MembershipRenewal looks for a template
-in `templates/CRM/Member/Form/MembershipRenewal.tpl`.
-
-Templates are written in smarty, a common PHP template engine.  Variables can
-be passed to smarty using the assign() method which is available to all Form
-and Page classes.
-
-Customising templates is discussed in more detail in 'Techniques'
-
-## The API
-The application programming interface (API) is stored in the api root
-directory.  Best practice for using the API is discussed in more detail in
-'Techniques'
-
-## bin scripts
-The bin directory contains a variety of scripts that can be run to carry out
-specific functions.  Some of these scripts are run on a regular basis, for
-example the CiviMail 'send' and 'process' scripts.  Others are run on a one of
-or occasional basis, e.g. update geo-coding.
-
-## SQL
-The SQL directory is automatically generated as part of a release.  It contains
-useful files like the SQL to create the database and insert demo data. Most
-developers won't need to edit files in this directory.
-
-## l10n
-This directory contains lots of automatically generated localisation files.
-You should not need to edit this directory directly.  You should instead use
-CiviCRM's online translation tool transifex.
-
-## packages
-CiviCRM makes use of a lot of 3rd party packages for things like the database,
-        form, javascript and pdf libraries, wysiwyg editors and so on.  You
-        shouldn't need to edit these packages directory.
-
-## Database structure
-The database structure is defined in a series of XML files.  These files are
-not packaged in the releases but are available in the Github repository. They
-are located in Civicrm/xml/Schema. All the folders within this directory also
-have folders in the main CRM folder which contain a DAO folder and generally a
-BAO folder too.
-
-Looking in `CiviCRM/xml/Schema/Pledge` we see 4 files:
-
-- files.xml
-- Pledge.xml
-- PledgePayment.xml
-- PledgeBlock.xml
-
-The files.xml is just a list of the other files. Each of the others represents a
-table in the Database. The XML files describe the database and are used to
-build both the DAO files and the new database SQL generation script.
-
-The XML describes fields, foreign keys and indexes, an example of a field definition is:
-
-```
-  <field>
-    <name>amount</name>
-    <uniqueName>pledge_amount</uniqueName>
-    <title>Total Pledged</title>
-    <type>decimal</type>
-    <required>true</required>
-    <import>true</import>
-    <comment>Total pledged amount.</comment>
-    <add>2.1</add>
-  </field>
-```

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