Merge pull request #5 from civicrm/master

update from core

docs/api/usage.md

@@ -91,19 +91,21 @@ before using the API.  See the examples in [Bootstrap Reference].
 ## PHP (class.api.php)
 
 CiviCRM v3.4 introduced an object-oriented API client, `class.api.php`.
-This class be used locally or remotely to invoke APIs, as in:
+This class can be used locally or remotely to invoke APIs, as in:
 
 ```php
 require_once 'your/civicrm/folder/api/class.api.php';
-$api = new civicrm_api3();
+$api = new civicrm_api3(array(
+  // Specify location of "civicrm.settings.php".
+  'conf_path' => 'your/sites/default',
+));
 $apiParams = array(
   'first_name' => 'Alice',
-  'last_name' => 'Roberts'
+  'last_name' => 'Roberts',
 );
 if ($api->Contact->Get($apiParams)) {
   //each key of the result array is an attribute of the api
   echo "\n contacts found ".$api->count;
-  'contact_type'=>'Individual','return'=>'sort_name,current_employer')) {
 }
 else {
   echo $api->errorMsg();
@@ -111,8 +113,11 @@ else {
 ```
 
 If you call the API in the object oriented fashion, you do not have to
-specify 'version' as a parameter
+specify 'version' as a parameter.
 
+The object-oriented client can connect to a local or remote CiviCRM
+instance. For details about connection parameters, see the docblock in
+[class.api.php](https://github.com/civicrm/civicrm-core/blob/master/api/class.api.php).
 
 ## REST
 

docs/basics/community.md

@@ -5,7 +5,7 @@ collaborate:
 
 -   [CiviCRM.org](https://civicrm.org)
     -   [Extensions](https://civicrm.org/extensions) publishing
-    -   [Blog posts](https://civicrm.org/blog/) by community members
+    -   [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
     -   [Job Board](https://civicrm.org/jobs) - Post and find paid work
@@ -13,10 +13,10 @@ collaborate:
     -   [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) - Live discussion
+-   [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
--   [GitHub](https://github.com/civicrm) - Hosted git repositories
--   [StackExchange](http://civicrm.stackexchange.com/) - Question & answer
+-   [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

docs/basics/planning.md

+# Planning your project
+
+## 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.
+
+
+## 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.
+
+## 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.
+
+**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)** 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.
+
+
+## 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.
+

docs/basics/skills.md

+# Prerequisite 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/).
+
+
+## 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.
+
+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
+    -   [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).
+    -   [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.)*
+    -   [Javascript tutorial](http://www.w3schools.com/js/default.asp)
+-   **jQuery** - a javascript library that makes manipulating elements on a web
+    page easy
+    -   [jQuery documentation](http://api.jquery.com/)
+-   **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 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 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.
+    -   [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.
+    -   [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).
+
+

docs/best-practices/documentation-style-guide.md

+# Documentation style guide
+
+All CiviCRM guides *(like this Developer Guide)* are intended to provide
+high-quality "finished" [documentation] (documentation.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
+
+Similar to most text books and manuals, we divide our guides into "parts",
+"chapters", and "sections". In mkdocs, these blocks translate as follows:
+
+-   "part" - folder
+-   "chapter" - file (in markdown), also one web page with a given URL
+-   "section" - heading within the page
+
+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,
+    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".
+
+Each chapter should start with a paragraph that explains what will be
+covered in the chapter.
+
+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.
+
+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.
+
+### Headings
+
+The first heading in a chapter 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
+instead be refactored.
+
+### Capitalization
+
+Titles for parts, chapters, and sections should all be in sentence case
+(first word capitalized), not headline case (each word capitalized).
+
+## Formatting conventions
+
+### Describing the CiviCRM user interface
+
+Menu selections, buttons, tabs (basically, things that the reader is
+being told to click) should be in bold.
+
+-   Navigate to **Administer > CiviEvent > Event Types** to review the
+    default list of event types.
+-   Modify event type labels by clicking **Edit** on any row.
+-   Click **Add Event Type** to create a new category for your events.
+
+Elements of the system and interface should be capitalized (e.g., the
+Events component, the Template Title field).
+
+It is also sometimes helpful for clarity when discussing concepts to use
+capitalization to distinguish between a specific activity within CiviCRM
+and a generic activity (e.g., the Send Email activity versus sending an
+email). However, sometimes it is too cumbersome or just plain weird to
+capitalize every instance of a term even if it refers to a specific CiviCRM
+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 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).
+
+You can divide the CiviCRM interface into administration pages and
+public-facing pages.
+
+### Bullets and numbered lists
+
+Bulleted lists should be used to convey short snippets of information.
+Numbered lists should be used to describe specific steps in a process
+that must be done in order.
+
+Numbered lists should always be made up of full sentences (since they
+are instructions) and thus should include terminal punctuation.
+
+Bulleted lists may or may not need to be full sentences. Full sentence
+bullets need terminal punctuation. Bullets that are not full sentences
+should not have terminal punctuation. However, if any particular list
+contains one or more full-sentence bullets, all bullets (even those that
+are not full sentences) should have terminal punctuation.
+
+Sections that are over 50% bullets look really bad and not like a book.
+If you see a section which is 'all bullets', consider rewriting it
+removing them.
+
+### Images
+
+Images should be in png format and a maximum of 690px wide. Please use
+descriptive names for images.
+
+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](/markdownrules/#code) to use for such formatting.
+
+### URLs
+
+Sample links to specific CiviCRM URL paths should use `example.org` as the
+domain.
+
+```text
+http://example.org/civicrm/mailing/queue&reset=1
+```
+
+## Language
+
+### Spelling and punctuation
+
+Both U.K. and U.S. English spellings are acceptable; we actually welcome
+inconsistency around this. CiviCRM is an international project, so its
+mixing it up is a benefit.
+
+Double quotes are preferred over single quotes.
+
+Avoid abbreviations. For example, write "organisation" instead of "org".
+
+Below are our preferred spellings of CiviCRM-specific words:
+
+-   "autoresponder" *(not auto-responder)*
+-   "CiviCRM" *(not "Civi")*
+-   "deduplicate", "dedupe" *(not "de-duplicate" or "de-dupe")*
+-   "dropdown", "dropdown menu" *(not "drop-down")*
+-   "meetup" (noun)
+-   "non-profit" *(not "nonprofit")*
+-   "set up" (verb), "set-up" (noun)
+-   "unsubscribe" *(not "un-subscribe")*
+
+### Terminology
+
+-   **contact** - a contact record within CiviCRM
+-   **organisation/organization** - a non-profit (or other community group,
+    etc) who is (or could be) using CiviCRM
+-   **user** - a person who interacts with CiviCRM via the front end
+-   **site admin** - a staff member (of an organisation) who regularly
+    administers CiviCRM from the front end. (By definition these people are
+    also "users".)
+-   **system administrator** - a technical person who administers CiviCRM from
+    the back end
+-   **hosting provider**
+    -   In the User Guide - synonymous with *"system administrator"*
+    -   In other guides - a person or company that owns and/or maintains the
+        server upon which CiviCRM runs
+-   **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)
+
+### Gender neutrality
+
+When describing people in examples, avoid using pronouns that assign specific
+genders to them.
+
+Example of gendered language to avoid:
+
+> *When a supporter wishes to fundraise on behalf of an organization, **he** can
+> create a fundraising page **himself**, called a Personal Campaign Page, and
+> then solicit donations from **his** friends and family. After a donation
+> arrives, CiviCRM can even send **him** a notification email.*
+
+Option 1 - fix by using [singular they] *(which is
+[rapidly](https://www.washingtonpost.com/news/wonk/wp/2016/01/08/donald-trump-may-win-this-years-word-of-the-year/)
+[gaining](http://www.americandialect.org/2015-word-of-the-year-is-singular-they)
+[popularity](http://www.npr.org/2016/01/13/462906419/everyone-uses-singular-they-whether-they-realize-it-or-not)
+)*:
+
+> *When a supporter wishes to fundraise on behalf of an organization, **they**
+> can create a fundraising page **themself**, called a Personal Campaign Page,
+> and then solicit donations from **their** friends and family. After a donation
+> arrives, CiviCRM can even send **them** a notification email.*
+
+Option 2 - fix by avoiding pronouns entirely:
+
+> *A supporter wishing to fundraise on behalf of an organization can
+> autonomously create a fundraising page, called a Personal Campaign Page, and
+> then solicit donations from friends and family. After a donation arrives,
+> CiviCRM can even send **the supporter** a notification email.*
+
+Avoid fixing gendered language by replacing "he" with phrases such as:
+"he/she", "he or she", "she", or "s/he". Such replacements (a) become more
+awkward when sentences include multiple pronouns, (b) do not intuitively offer
+a consistent choice among them, and (c) fail to acknowledge that some people
+identify with genders outside of a binary framework.
+
+[singular they]: https://en.wikipedia.org/wiki/Singular_they
+
+### Tone and vocabulary
+
+Try to avoid constructions that tell people what they *should* do when multiple
+options exists. We want to recognize and respect that there is more than one
+way to approach being a user or developer. Preferring constructions that
+suggest ways that people can do things. We would like to to avoid language that
+gets proscriptive or feels intimidating from a reader's perspective, and we
+like having a guide that can be consumed by people in different ways.
+
+**For the *User* and *Administrator* Guides only:** We try and limit the
+content to tasks that the user can perform from the front end. This means that
+we don't go into detailed steps about installation or system administration
+tasks.  We do however let people know that there are system administrator tasks
+out there (setting up an SSL certificate, configuring CiviMail etc.) and point
+them in the right direction when they want to know about those tasks.
+
+
+

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/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.
+
+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.

docs/dev-tools/debugging.md

+# Debugging
+
+When your code isn't doing what you want it to do, it's time to debug.
+There are lots of options for debugging and there is lots you can do
+without setting up a sophisticated debugging environment.  This chapter
+contains some simple debugging tips and tricks to get you started and
+also instructions on setting up XDebug, which is the recommended
+debugging tool for CiviCRM when you have bugs which are really hard to squish.
+
+!!! danger "Security Alert"
+    None of these debugging should be performed on production sites, as they can expose system configuration and authentication information being to unauthorized visitors.
+
+The debugging methods presented here are ordered with the easiest ones first, but you may find the more challenging methods near the end to be more rewarding.
+
+
+
+## Changing settings in the UI
+
+CiviCRM has a debug mode which can be enabled via the UI to give you quick
+access to a couple of useful diagnostic tools, including all the
+Smarty variables that make up a page. It also provides shortcut methods
+to empty the file-based cache and session variables.
+
+To use debugging via the UI, first go to **Administer > System Settings > Debugging and Error Handling** to enable these options, and find out more about them.
+
+### Using URL parameters
+
+After enabling debugging, append any of the following name-value pairs to the URL for the page you visit.
+
+-   `&smartyDebug=1` opens the Smarty Debug Window which loads all variables available to the current page template into a pop-up window *(make sure you have pop-up blocking disabled)*.
+-   `&sessionReset=2` resets all values in your client session.
+-   `&directoryCleanup=1` empties template cache in `civicrm/templates_c`.
+-   `&directoryCleanup=2` removes temporary upload files in `civicrm/upload`.
+-   `&directoryCleanup=3` performs both of the above actions.
+-   `&backtrace=1` displays a stack trace listing at the top of a page.
+-   `&sessionDebug=1` displays the current users session variables in the browser.
+-   `&angularDebug=1` displays live variable updates on certain Angular-based pages
+
+!!! tip "Caveats"
+    - Sometimes using `&smartyDebug=1` to inspect variables available to a template will not work as expected.  An example of this is looking at the Contact Summary page, when using this method will display the variables available only to the summary tab and you might want to see the variables available to one of the other tabs. To do this you will need to debug via code, as explained below.
+    - If the page you are debugging does not already have a key-value parameter before debugging, you will need to begin the first parameter with a question mark instead of a ampersand.
+
+### Displaying a backtrace
+
+The backtrace can be enabled independently of debugging. If this option is selected, a backtrace will be displayed even if debugging is disabled.
+
+A backtrace is a list of all the functions that were run in the execution of the page, and the PHP files that contain these functions. It can be really useful in understanding the path that was taken through code, what gets executed where, etc.
+
+
+
+## Viewing log files
+
+CiviCRM's log files are stored in the `civicrm/ConfigAndLog` directory
+(below the `files` directory in Drupal sites, and below the `media`
+directory in Joomla sites and under `wp-content/plugins/files/` directory
+in Wordpress). Most runtime errors are logged here, as well as data that
+you explicitly write to log using the `CRM_Core_Error::debug log=true`
+parameter.
+
+
+
+## Changing file-based settings
+
+The following values can be added to your site's settings file `civicrm.settings.php` to assist in debugging:
+
+- `define('CIVICRM_MAIL_LOG', 1);` causes all outbound CiviCRM email to be written to a log file. No real emails are sent.
+
+- `define('CIVICRM_MAIL_LOG', '/dev/null');` causes all outbound emails to be discarded. No email is sent and emails are not written to disk.
+
+- `define('CIVICRM_DEBUG_LOG_QUERY', 1);` outputs all SQL queries to a log file.
+
+- `define('CIVICRM_DEBUG_LOG_QUERY', 'backtrace');` will include a backtrace of the PHP functions that led to the query.
+
+- `define('CIVICRM_DAO_DEBUG', 1);` writes out various data layer queries to your browser screen.
+
+- `define('CIVICRM_CONTAINER_CACHE', 'never');` causes Civi to rebuild the [container](http://symfony.com/doc/current/service_container.html) from the latest data on every page-load
+
+!!! tip
+    When any sort of "logging stuff to a file" is enabled by one of the above settings, check the following directories for the resulting file:
+
+    - Drupal: `files/civicrm/ConfigAndLog/`
+    - Joomla: `media/civicrm/ConfigAndLog/`
+
+
+## Viewing a query log from MySQL
+
+Outside of CiviCRM, the MySQL database software has features to enable the logging of all queries it receives.
+
+*TODO: how do we enable?*
+
+
+
+## Changing source code
+
+### In Smarty template files
+
+Add  `{debug}` to any part of the `.tpl` file and the Smarty Debug Window (described above) will display all variables in the same scope as the `{debug}` statement.
+
+### Printing PHP variables
+
+Show the contents of a variable:
+
+```php
+print_r($variable);
+```
+
+Show the contents of a variable, also with information regarding data types and lengths:
+
+```php
+var_dump($variable);
+```
+
+Another way to show the contents of a variable:
+
+```php
+CRM_Core_Error::debug($name, $variable = null, $log = true, $html= true);
+```
+
+Stop the script execution at that point.
+
+```php
+exit;
+```
+
+Print a backtrace:
+
+```php
+CRM_Core_Error::backtrace();
+```
+
+### In AngularJS HTML templates
+
+```html
+<div crm-ui-debug="myData"></div>
+```
+
+Then, be sure to add the parameter `angularDebug=1` to the URL.
+
+## Clearing the cache
+
+Clearing the cache is not a debugging technique, specifically. But sometimes it helps, and so is mentioned here for the sake of completeness.
+
+Using a web browser, either:
+
+-   Navigate directly to `civicrm/clearcache`
+-   Navigate to "Administer => System Settings => Cleanup Caches"
+
+Using the command line, you can clear all caches with one of these commands:
+
+-   `cv flush` (requires [`cv`](https://github.com/civicrm/cv))
+-   `drush cc civicrm` (requires [`drush`](https://github.com/drush-ops/drush))
+
+Alternatively, you can call the following methods in PHP code:
+
+-   `civicrm_api3('System', 'flush', array());` clears many different caches
+-   `CRM_Core_Config::clearDBCache();` clears the database cache
+-   `CRM_Core_Config::cleanup();` clears the file cache
+
+
+
+## Running a debugger program
+
+### What is a debugger?
+
+A debugger is a software program that watches your code while it
+executes and allows you to inspect, interrupt, and step through the
+code. That means you can stop the execution right before a critical
+juncture (for example, where something is crashing or producing bad
+data) and look at the values of all the variables and objects to make
+sure they are what you expect them to be. You can then step through the
+execution one line at a time and see exactly where and why things break
+down. It's no exaggeration to say that a debugger is a developer's best
+friend. It will save you countless hours of beating your head against
+your desk while you insert print statements everywhere to track down an
+elusive bug.
+
+Debugging in PHP is a bit tricky because your code is actually running
+inside the PHP interpreter, which is itself (usually) running inside a
+web server. This web server may or may not be on the same machine where
+you're writing your code. If you're running your CiviCRM development
+instance on a separate server, you need a debugger that can communicate
+with you over the network. Luckily such a clever creature already
+exists: XDebug.
+
+XDebug isn't the only PHP debugger, but it's the one we recommend for
+CiviCRM debugging.
+
+
+### Installing XDebug
+
+#### Debian / Ubuntu Linux (System Packages)
+
+```bash
+sudo apt-get install php5-xdebug
+```
+
+#### Red Hat / CentOS Linux (System Packages)
+
+```bash
+sudo yum install php-pecl* php-devel php-pear
+sudo pecl install Xdebug
+```
+
+#### Mac OS X, Windows, and others
+
+Generic instructions are provided with [XDebug's documentation](http://xdebug.org/docs/install).
+
+Specific installation steps vary due to the diversity of PHP installation sources -- Apple's built-in PHP, brew, MAMP, XAMPP, AMPP, WAMP, Vagrant, Bitnami, and MacPorts are all a bit different. The best way to install XDebug is to identify your specific PHP runtime and then search Google, e.g. ["mamp xdebug"](https://www.google.com/#q=mamp+xdebug) or ["macports xdebug"](https://www.google.com/#q=macports+xdebug).
+
+### Setting up PHP to talk to XDebug
+
+Tell XDebug to start automatically (don't do this on a production
+server!) by adding the following two lines to your `php.ini` file (your
+`php.ini` file is a php configuration file which is found somewhere on
+your server.  Calling the `phpinfo()` function is probably the  easiest
+way to tell you where this file is in your case.
+
+```php
+xdebug.remote_enable = On
+xdebug.remote_autostart = 1
+```
+
+Once XDebug is installed and enabled in your PHP configuration, you'll
+need to restart your web server.
+
+### Installing an XDebug Front-End
+
+After you have XDebug running on your PHP web server, you need to
+install a front-end to actually see what it is telling you about your
+code. There are a few different options available depending on what
+operating system you use.
+
+#### NetBeans
+
+[NetBeans](http://www.netbeans.org/) is a cross platform heavyweight Java IDE
+(Integrated Development Environment).
+It offers lots of features, but isn't exactly small
+or fast. However, it is very good at interactive debugging with XDebug. And
+since it's written in  Java, it should run on any operating system you want
+to run it on.
+
+After installing NetBeans, open your local CiviCRM installation in
+NetBeans and click the Debug button on the toolbar. It will fire up your
+web browser and start the debugger on CiviCRM. You may went to set a
+breakpoint in `CRM/Core/Invoke.php` to make the debugger pause there. For
+more information, see the NetBeans debugging documentation.
+
+#### MacGDBp
+
+[MacGDBp](http://www.bluestatic.org/software/macgdbp/)
+is a lighter-weight option, only available for OS X. After installing MacGDBp,
+launch it and make sure it says "Connecting"
+at the bottom in the status bar. If it doesn't, click the green "On"
+button in the upper-right corner to enable it. The next time you access
+CiviCRM, the web browser will appear to hang. If you click on MacGDBp,
+you'll see that it has stopped on the first line of code in CiviCRM.
+From there you can step through the code to the part you're interested
+in. But it's probably a better idea to set a breakpoint in the part of
+the code you're interested in stopping at. See the MacGDBp documentation
+for more information.

docs/documentation.md

 # Writing Documentation
 
-[CiviCRM.org/documentation](https://civicrm.org/documentation) has a nice
-high-level list of all active documentation.
+To *read* documentation, go to [CiviCRM.org/documentation](https://civicrm.org/documentation) for the most high-level list of all active documentation.
 
-## Wiki migration
+This page describes the documentation systems within CiviCRM and how to contribute.
 
-As of early 2017, developer documentation on the [wiki] is under
-active migration to mkdocs. If you are helping to migrate wiki pages, please
-read about the [migration process][migration] to ensure that you understand the
-workflow including the process of redirecting wiki pages to mkdocs.
+!!! note "Note: the wiki is not covered here"
+    The [wiki] has historically been CiviCRM's documentation system but is currently being phased out. As of early 2017, documentation is still somewhat split between the wiki the the guide books described below, but we are working to eventually consolidate *all* documentation into guide books. A [migration process][migration] is currently underway for this Developer Guide, and a process will [likely](https://github.com/civicrm/civicrm-docs/issues/17) follow for a dedicated Administrator Guide, as well as [extension guides](https://github.com/civicrm/civicrm-docs/issues/14).
+
+    The rest of **this page describes guide books only** and does *not* cover documentation processes that involve the wiki.
 
 [migration]: https://wiki.civicrm.org/confluence/display/CRMDOC/Content+migration+from+wiki+to+Developer+Guide
 [wiki]: https://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Documentation
 
-## Guides in mkdocs
+## Guide books in MkDocs
 
-We are using [mkdocs](http://www.mkdocs.org) to produce guides, and currently
-have the following two:
+We are using [MkDocs](http://www.mkdocs.org) to produce guides, and have the following:
 
--   [User Guide](https://docs.civicrm.org/user/en/stable/)
-    ([repository](https://github.com/civicrm/civicrm-docs))
--   [Developer Guide](https://docs.civicrm.org/dev/en/master/)
-    ([repository](https://github.com/civicrm/civicrm-dev-docs))
-    *(which you are reading now!)*
+| Book | English | French
+| ---- | ------- | ------ |
+| User Guide | **[latest][u-en-l]**,<br>[stable][u-en-s],<br>[4.7][u-en-47], [4.6][u-en-46]<br><br>*[repository][u-r-en]* | **[latest][u-fr-l]**, [stable][u-fr-s]<br><br>*[repository][u-r-fr]* |
+| Administrator Guide *([planned](https://github.com/civicrm/civicrm-docs/issues/17))* | | |
+| Developer Guide | **[latest][d-l]**<br><br>*[repository][d-r]* | |
+| Extension Guides *(planned)* | | |
 
-The content for each of these guides is written in [markdown], stored in text
-files, and hosted on GitHub.
 
-### How to edit
+[u-en-s]: https://docs.civicrm.org/user/en/stable/
+[u-en-l]: https://docs.civicrm.org/dev/en/latest/
+[u-en-47]: https://docs.civicrm.org/user/en/4.7/
+[u-en-46]: https://docs.civicrm.org/user/en/4.6/
+[u-fr-l]: https://docs.civicrm.org/user/fr/latest/
+[u-fr-s]: https://docs.civicrm.org/user/fr/stable/
+[d-l]: https://docs.civicrm.org/dev/en/latest/
 
-For minor changes you can simply edit the [markdown] online using GitHub.
-However, for a better editing experience we highly recommend installing
-`mkdocs` as follows.
+[u-r-en]: https://github.com/civicrm/civicrm-docs
+[u-r-fr]: https://github.com/civicrm-french/civicrm-user-guide
+[d-r]: https://github.com/civicrm/civicrm-dev-docs
+
+The content for each of these guides is written in [markdown](/markdownrules.md), stored in text files, and hosted in a repository on GitHub. Then, the books are automatically published to **docs.civicrm.org** using our custom [documentation infrastructure](https://github.com/civicrm/civicrm-docs).
+
+### Languages
+
+As shown above, a book can have multiple languages, and we use separate repositories for different languages.
+
+### Versions
+
+In an effort to maintain documentation anchored to specific versions of CiviCRM, some books store separate versions of the documentation in different *branches* within the repository.
+
+<!-- TODO: clarify "latest" vs "stable" vs "master" -->
+
+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.
+
+
+## Contributing to documentation
+
+We welcome contributions, small and large, to documentation!
+
+### Resources:
+
+Before diving into editing, you may find helpful information within the following resources:
+
+- [Markdown syntax](/markdownrules.md) - necessary (but simple) syntax to format content
+- Markdown coding standards - *[coming soon](https://github.com/civicrm/civicrm-dev-docs/issues/43)*
+- [Style guide](/best-practices/documentation-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
 
-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 and clone locally.
-1.  Install mkdocs on your machine.
-    1.  For Ubuntu
 
-            sudo apt-get install python-pip python-wheel
-            sudo pip install mkdocs
+### Submitting issues
 
-    1.  For other platforms, follow instructions on
-        [mkdocs.org](http://www.mkdocs.org)
+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 guide book you are reading. Then someone will see your issue and act on it, hopefully fast. Each guide book has its own issue queue. First find the GitHub repository for the book (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.
+
+### Editing through GitHub
+
+A slightly more helpful way to plug in is to suggest specific changes by making the changes within the text editor on GitHub. To do this, you would go to the repository, find the markdown file for the page you'd like to change (look at the page's URL in your browser to help figure out where the file is within the repository), then click on the pencil icon at the top right of the page on GitHub. When you make a change, you are essentially forking (i.e. copying) the entire guide into your personal account on GitHub, changing that fork and then requesting to merge your fork into the main guide.
+
+### Editing locally with MkDocs
+
+The most advanced way to work on a guide book 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. 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`
+
+1.  Install MkDocs.
+
+        sudo pip install mkdocs
+
+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.  Clone *your fork* of the repository to your computer
+
+            git clone https://github.com/YourGitHubUserName/civicrm-dev-docs.git
+            cd civicrm-dev-docs
 
 1. Launch a local copy of the guide
     1. Run:
 
-            cd civicrm-dev-docs
             mkdocs serve
 
         -   If you get `[Errno 98] Address already in use` then try using a
             different port with `mkdocs serve -a localhost:8001`
 
-    1. Go to `http://localhost:8000` to view
+    1. View through your browser at `http://localhost:8000`.
 
-1.  Edit the [markdown] with an editor of your choice. As you
+1.  Edit the [markdown](/markdownrules.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.
-    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 GitHub.
+
+
+## Documenting your extension
 
+TODO
 
-[Markdown]: markdownrules.md

docs/extensions/basics.md

@@ -10,9 +10,7 @@ Todo:
 **CiviCRM Extensions** are packaged pieces of functionality that extend
 CiviCRM's out-of-the-box functionality, independent of CMS plaform.
 
-This section covers how to write extensions. See the [extension life cycle
-page](/extend-stages) for background on the publishing and review process for
-[published extensions](https://civicrm.org/extensions).
+This section covers how to write extensions.
 
 ## Extension Names
 
@@ -45,17 +43,6 @@ different short-name, but that requires extra work.
     by the www-data user. You will need to make this file readable by
     your development user account for civix to work.
 
-## General overview
-
-[]( fixme paragraph this section into above notes )
-
-If you haven't already, you need to configure a local directory to store
-extensions.
-For instructions, see
-[Extensions](https://wiki.civicrm.org/confluence/display/CRMDOC/Extensions)
-You may also want to review the
-[Extension Reference](https://wiki.civicrm.org/confluence/display/CRMDOC/Extension+Reference) page for technical details.
-
 ### 0. Decide
 Writing an extension is a great way to implement a new feature – but it may be
 unnecessary if someone else has already implemented that feature. If you're not
@@ -70,14 +57,18 @@ plugins. If you're considering another way, look at the
 to help decide.
 
 ### 1. Install civix
-Some tasks in the process of writing an extension require boiler-plate code. To
+Some tasks in the process of writing an extension require boilerplate code. To
 reduce the amount of work required to find, understand, and adapt the
-boiler-plate code, one should install the CiviCRM extension builder, civix.
+boilerplate code, one should install the CiviCRM extension builder, civix.
 Civix is a command-line tool which generates code for some common development
 tasks.
 
 >> See [https://github.com/totten/civix/](https://github.com/totten/civix/)
 
+>> For more information on the boilerplate civix generates for you, in
+   particular the extension manifest file (info.xml), see the [Extension
+   Reference](https://wiki.civicrm.org/confluence/display/CRMDOC/Extension+Reference).
+
 ### 2. Develop
 To get started with development, one should usually follow the steps in
 "[Create a Module
@@ -89,7 +80,18 @@ conventions closely resemble those of CiviCRM Core and of CiviCRM-Drupal
 modules. Module extensions are fully supported in CiviCRM 4.2+.
 
 ### 3. Publish
-The CiviCRM Extensions Directory provides a way to publicize your extension –
-and it even provides easy, in-app distribution.
-
-See: [Publish](http://wiki.civicrm.org/confluence/display/CRMDOC/Publish+an+Extension),
+The CiviCRM ecosystem is built on the belief that non-profit organizations can
+serve themselves best by collaborating in development of their data-management
+applications. As staff, volunteers, and consultants for non-profit organizations,
+we can share our new enhancements and extensions -- and build a richer whole for
+the entire ecosystem.
+
+Extension authors may make their extensions available to the larger CiviCRM
+community by publishing them in the [Extensions Directory](https://civicrm.org/extensions).
+>> See: [Publish](/extensions/publish)
+
+Extensions which undergo a [formal review](/extend-stages#formal-review) may be
+distributed in-app. Approved extensions can be [installed
+directly](https://docs.civicrm.org/user/en/master/introduction/extensions/#installing-extensions)
+into CiviCRM via the user interface, lowering the barrier to entry for many users.
+>> See: [Automated Distribution](/extensions/publish#automated-distribution)

docs/extensions/publish.md

+# Publishing Extensions
+
+Publishing an extension is an easy way to:
+
+-   recruit collaborators for a project
+-   increase your user base and, along with it, the potential for:
+    -   contributed bug fixes
+    -   new use cases
+    -   feature requests and project funding
+-   bring positive attention to your organization
+-   share a useful feature or set of configurations with worthy nonprofit and
+    community organizations
+
+While you could simply publish your extension to a web-based code repository
+like GitHub, publishing through the
+[CiviCRM Extensions Directory](http://civicrm.org/extensions) makes it easy for
+others to find and download it. Moreover, CiviCRM-native extensions which undergo a
+formal review can even be distributed in-application to CiviCRM sites running
+version 4.2 or greater.
+
+The following instructions assume you will be publishing a CiviCRM-native
+extension (i.e., a CMS-agnostic extension). Instructions for CMS-specific
+extensions are similar; differences are noted in [Notes for CMS-specific
+extensions](#notes-for-cms-specific-extensions).
+
+## Publishing a CiviCRM extension
+
+CiviCRM's publishing process automates a number of tasks related to maintaining
+your extensions. Just provide some basic information about the extension, and
+the rest is taken care of for you! Subsequent releases will automatically be
+detected, published, and submitted for translation.
+
+### Prerequisites:
+
+-   The extension code is published in a public GitHub repository.
+-   The extension manifest (`info.xml`) is in the root of the repository.
+-   The extension manifest is
+    [valid](https://wiki.civicrm.org/confluence/display/CRMDOC/Extension+Reference#ExtensionReference-Tagsininfo.xml).
+-   The name of the extension repository (e.g., *https://github.com/civicrm/org.civicrm.legcase.git*)
+    matches the extension's fully qualified name (.e.g, *org.civicrm.legcase*) or
+    its short name as specified by the `file` tag in `info.xml` (e.g., *legcase*).
+-   Each release of the extension is "tagged" in the git repository with a
+    ["PHP-standardized" version number string](http://php.net/manual/en/function.version-compare.php).
+    Version number strings may optionally be prefixed with a "v."
+    -   Valid tag names: "v1.2.3", "1.2.3", "v1.2-beta3", "1.2-beta3"
+    -   Invalid (ignored) tag names: "stable", "1.2-prerelease"
+
+### Publishing an extension:
+
+-   [Register](https://civicrm.org/user/register) for an account on civicrm.org if you
+    do not already have one.
+-   [Login](https://civicrm.org/user) to civicrm.org and [create a new extension
+    node](http://civicrm.org/node/add/extension). If you see an "Access Denied"
+    message, you'll need to email [info@civicrm.org](mailto:info@civicrm.org)
+    with your user id and request permission to publish extensions.
+-   Fill out all required fields. Also provide the "Git URL" for the extension.
+-   Within a day, you will receive an email notifying you that the extension
+    was published on civicrm.org or that a problem with the extension manifest
+    (`info.xml`) prevented publication.
+
+### Publishing subsequent releases:
+
+-   Update the extension manifest and push the changes to your GitHub repository.
+    At minimum you'll need to increment the version number.
+-   Create a git "tag" which matches the version in the manifest and push it, e.g.:
+
+        git tag -a v1.2.0
+        git push origin v1.2.0
+
+-   Within a day, you will receive an email notifying you that the release
+    was published on civicrm.org or that a problem with the extension manifest
+    prevented publication.
+
+### Notes for CMS-specific extensions
+
+CMS-specific extensions are developed for a single CMS / CiviCRM environment
+(e.g. Drupal 7 + CiviCRM, Joomla 2.5 + CiviCRM, etc.), typically using the
+extension framework of the CMS in question (for example, webform_civicrm is
+packaged as a Drupal module which invokes Drupal hooks).
+
+These extensions can be published on the CiviCRM.org extensions directory, but
+CiviCRM does not provide in-application distribution for them. We recommend
+publishing them to the CiviCRM directory and to the relevant CMS extension
+directory (drupal.org, etc.) to take advantage of the distribution system
+provided by the CMS.
+
+To publish a CMS-specific extension, follow the steps outlined above for
+[publishing an extension](#publishing-an-extension). (Note that the
+[prerequisites](#prerequisites) do not apply, that the extension manifest will
+be named and formatted according to the conventions of the CMS and not CiviCRM's
+`info.xml`, and that you may choose not to supply a "Git URL.") On the resulting
+release node, you will find a link "Add Extension Release." On this screen, you
+will provide release information as well as a link from which the extension may
+be downloaded.
+
+If you develop new version(s) of your extension, you can submit additional
+releases at any time.
+
+## Automated distribution
+
+The best way to reap the benefits of publishing your extension is to make it as
+easy as possible for others to install it. With just a few clicks, CiviCRM site
+administrators can view and install CiviCRM extension releases which meet
+certain criteria. To be eligible for automated distribution:
+
+-   The extension must be published in the Extensions Directory.
+-   One of the extension's maintainers must [request an extension review
+    request](https://issues.civicrm.org/jira/secure/CreateIssue!default.jspa?selectedProjectId=10400&issuetype=10000).
+-   The extension manifest must flag the release as "stable."
+-   The extension manifest must include a link to online documentation.
+-   The extension manifest must flag the release as compatible with CiviCRM
+    version 4.2 or greater.
+-   The release must be CMS-agnostic, and it must install without errors or
+    notices from the Manage Extensions page of a site running a stable release
+    of CiviCRM. Errors installing in any of the supported CMSes are grounds for
+    holding an extension back from automated distribution.
+-   The extension must provide the promised functionality. Serious bugs and
+    errors found by a CiviCRM community extension moderator exploring the
+    functionality of the extension are grounds for holding an extension back
+    from automated distribution.
+
+It is strongly recommended that you [write unit
+tests](https://github.com/civicrm/org.civicrm.testapalooza) for the extension
+and include them in the extension's repository. For an example, see the extension
+[org.civicrm.exampletests](https://github.com/totten/org.civicrm.exampletests).
+
+Once an extension release meets these criteria, the extension will be approved
+for automated distribution by a CiviCRM community extension moderator.
\ No newline at end of file

docs/markdownrules.md

@@ -13,8 +13,8 @@ language is useful for:
 [GitHub]: https://github.com
 
 Markdown language is mostly consistent across these platforms, but some
-discrepancies do exist. The `mkdocs` specific guide for markdown, as used in 
-this book is 
+discrepancies do exist. The `mkdocs` specific guide for markdown, as used in
+this book is
 [here](http://www.mkdocs.org/user-guide/writing-your-docs).
 
 
@@ -36,12 +36,12 @@ platforms.
 
         Try [CiviCRM](https://civicrm.org) for your database.
 
--   An internal hyperlink on mkdocs (4 different ways that all work)
+-   An internal hyperlink on mkdocs. The `.md` is optional.
+    *Make sure to use an absolute path and precede the path with a slash,
+    as shown below.*
 
         [extensions](/extensions/basics)
         [extensions](/extensions/basics.md)
-        [extensions](extensions/basics)
-        [extensions](extensions/basics.md)
 
 -   With long URLs, the following syntax is better.
 

mkdocs.yml

@@ -11,13 +11,17 @@ pages:
 - Home: index.md
 - Basics:
   - Developer Community: basics/community.md
+  - Prerequisite skills: basics/skills.md
   - Requirements: requirements.md
+  - Planning your project: basics/planning.md
   - Build: build.md
   - Customize: customize.md
   - Extend: extend.md
   - Develop: develop.md
   - Testing: testing.md
   - Writing Documentation: documentation.md
+- Development Environment:
+  - Debugging: dev-tools/debugging.md
 - APIv3:
   - API Intro: api/general.md
   - API Usage: api/usage.md
@@ -43,9 +47,15 @@ pages:
   # - Custom Reports: extensions/custom-reports.md
   # - Custom Searches: extensions/custom-searches.md
   # - Payment Processors: extensions/payment-processor.md
+  - Publish: extensions/publish.md
+- Best Practices:
+  - Documentation Style Guide: best-practices/documentation-style-guide.md
+- Core code:
+  - Hacking the core: core/hacking.md
+  - Architecture: core/architecture.md
 - Miscellaneous:
    - Extension Lifecycle: extend-stages.md
    - Markdown: markdownrules.md
-   - hookref-old: hookref-old.md
+   # - hookref-old: hookref-old.md
 - Deprecated:
    - Building CiviCRM from source: develop-deprecated.md

redirects/wiki-crm.txt

+Documentation+Infrastructure+Canary develop
+Book+style+guide best-practices/documentation-style-guide

redirects/wiki-crmdoc.txt

 Documentation+Infrastructure+Canary develop
 The+developer+community basics/community
-Create+an+Extension extensions/basics
\ No newline at end of file
+Create+an+Extension extensions/basics
+Publish+an+Extension extensions/publish
+Before+you+start basics/planning
+Recommendations basics/planning
+The+codebase core/architecture
+Debugging+for+developers dev-tools/debugging
+The+developer+community extensions/civix
+