diff --git a/docs/api/usage.md b/docs/api/usage.md
index b873169e491b8c4d6b80cf261a1d91a5451532fb..a037ce9454b0223fd823c41e74d9bd2efbe89da0 100644
--- a/docs/api/usage.md
+++ b/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
diff --git a/docs/basics/community.md b/docs/basics/community.md
index 8b3e4f5dcfc42324a4b5609dfdec610011d4e016..0bfae3ce1fcb4eff067fc3c1e32d3966429de44a 100644
--- a/docs/basics/community.md
+++ b/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
diff --git a/docs/basics/planning.md b/docs/basics/planning.md
new file mode 100644
index 0000000000000000000000000000000000000000..41433e95ba386cd855ffc75eb5d671a690f9cd99
--- /dev/null
+++ b/docs/basics/planning.md
@@ -0,0 +1,90 @@
+# 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.
+
diff --git a/docs/basics/skills.md b/docs/basics/skills.md
new file mode 100644
index 0000000000000000000000000000000000000000..dd560e20c424fb28e0bbcef63ed904eb7dfda6c4
--- /dev/null
+++ b/docs/basics/skills.md
@@ -0,0 +1,85 @@
+# 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).
+
+
diff --git a/docs/best-practices/documentation-style-guide.md b/docs/best-practices/documentation-style-guide.md
new file mode 100644
index 0000000000000000000000000000000000000000..8a5e5855b4c56e1199dcb11604a04d1cacdc813d
--- /dev/null
+++ b/docs/best-practices/documentation-style-guide.md
@@ -0,0 +1,222 @@
+# 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.
+
+
+
diff --git a/docs/core/architecture.md b/docs/core/architecture.md
new file mode 100644
index 0000000000000000000000000000000000000000..9993d6edf53ff9c7abfdebb19228c696406a6270
--- /dev/null
+++ b/docs/core/architecture.md
@@ -0,0 +1,167 @@
+# 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>
+```
diff --git a/docs/core/hacking.md b/docs/core/hacking.md
new file mode 100644
index 0000000000000000000000000000000000000000..3335f7945c1d6f9b8cd8ef7401d2ed21e969c995
--- /dev/null
+++ b/docs/core/hacking.md
@@ -0,0 +1,19 @@
+## 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.
diff --git a/docs/dev-tools/debugging.md b/docs/dev-tools/debugging.md
new file mode 100644
index 0000000000000000000000000000000000000000..3c0295a84de973890a84aa5fe59bee7eb05accc6
--- /dev/null
+++ b/docs/dev-tools/debugging.md
@@ -0,0 +1,260 @@
+# 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.
diff --git a/docs/documentation.md b/docs/documentation.md
index 5e048be7150ee567328a322390c8514868bae3a0..ba961afb403ac576d8a87b1a8bcc7cf736cb376c 100644
--- a/docs/documentation.md
+++ b/docs/documentation.md
@@ -1,68 +1,120 @@
# 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
diff --git a/docs/extensions/basics.md b/docs/extensions/basics.md
index 602feca9c06106e2d5b4b3a94c72e7cef3ff863a..de6f002333a6b96f5f8ba8f9a1d1bfb129ee82d5 100644
--- a/docs/extensions/basics.md
+++ b/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)
diff --git a/docs/extensions/civix.md b/docs/extensions/civix.md
index b46ce38030cf62e277c1aa2fa519edfd87ff3ce2..dbfe0bc0c2742d06f618d1adffb3f3f3e8e0e6db 100644
--- a/docs/extensions/civix.md
+++ b/docs/extensions/civix.md
@@ -1,11 +1,5 @@
# Civix
->> 
-Note: This page started
-[here in the wiki](https://wiki.civicrm.org/confluence/display/CRMDOC/Create+a+Module+Extension).
-We have not yet transferred all of the script snipets, so you may wish to
-peruse this page as well.
-
## Introduction
The [`civix`](https://github.com/totten/civix/) command-line tool is the
@@ -37,7 +31,7 @@ civix help civicrm:ping
## Generating a skeletal extension
To generate a skeletal extension module, we will use `civix generate:module`
-and pass in the name for our extension. See [here](./basics/#extension-names)
+and pass in the name for our extension. See [here](/basics/#extension-names)
for details of naming conventions.
Start with:
@@ -54,9 +48,9 @@ civix generate:module com.example.myextension --license=AGPL-3.0
```
This command will report that it has created three files, following the
-[standard extension structure](./files).
+[standard extension structure](/extensions/files).
-The command attempts to autodetect authorship information (your name and
+The command attempts to auto-detect authorship information (your name and
email address) by reading your
[`git`](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup)
configuration. If this fails or is
@@ -90,7 +84,7 @@ at your discretion. A few possibilities:
CiviCRM uses a typical web-MVC architecture. To implement a basic web
page, you must create a PHP controller class, create a Smarty template
file, and create a routing rule. You can create the appropriate files by
-calling "civix generate:page"
+calling `civix generate:page`
Once again you can review the output of this command to see the available options:
@@ -108,8 +102,8 @@ civix generate:page MyPage civicrm/my-page
This creates three files:
- `xml/Menu/myextension.xml` defines request-routing rules and
- associates the controller ("CRM\_Myextension\_Page\_Greeter") with
- the web path ("civicrm/my-page")
+ associates the controller ("CRM_Myextension_Page_Greeter") with
+ the web path `civicrm/my-page`.
- `CRM/Myextension/Page/MyPage.php` is the controller which
coordinates any parsing, validation, business-logic, or database
operations.
@@ -122,32 +116,32 @@ This creates three files:
The auto-generated code for the controller and view demonstrate a few
basic operations, such as passing data from the controller to the view.
->> 
-After adding or modifying a route in the XML file, you must reset
-CiviCRMs "menu cache". Do this in a web browser by visiting
-"/civicrm/menu/rebuild?reset=1" or by running
-`drush cc civicrm` if using Drupal & Drush.
+!!! note
+ After adding or modifying a route in the XML file, you must reset
+ CiviCRMs "menu cache". Do this in a web browser by visiting
+ `/civicrm/menu/rebuild?reset=1` or by running
+ `drush cc civicrm` if using Drupal & Drush.
**Edit In Place**
If the data on the page is read and updated through the API, then you
-may want to consider using the [in-place
-editing](/confluence/display/CRMDOC/In-Place+Field+Editing) API.
+may want to consider using the
+[in-place editing](https://wiki.civicrm.org/confluence/display/CRMDOC/In-Place+Field+Editing) API.
### Add a basic web form
->> 
-The form system is not well documented and may undergo significant
-revision after the CiviCRM 4.x series. In general, migrating basic pages
-will be easier than migrating basic forms, so you may want
-to consider building your data-input interface using basic pages, the AJAX API,
-and the
-[in-place editing](/confluence/display/CRMDOC/In-Place+Field+Editing) API.
+!!! caution
+ The form system is not well documented and may undergo significant
+ revision after the CiviCRM 4.x series. In general, migrating basic pages
+ will be easier than migrating basic forms, so you may want
+ to consider building your data-input interface using basic pages, the AJAX
+ API, and the
+ [in-place editing](https://wiki.civicrm.org/confluence/display/CRMDOC/In-Place+Field+Editing) API.
CiviCRM uses a typical web-MVC architecture. To implement a basic web
form, you must create a PHP controller class, create a Smarty template
file, and create a routing rule. You can create the appropriate files by
-calling "civix generate:form".
+calling `civix generate:form`.
The form generation command has similar arguments to `civix generate:page`,
requiring a class name and a web route:
@@ -159,8 +153,8 @@ civix generate:form FavoriteColor civicrm/favcolor
This creates three files:
- `xml/Menu/myextension.xml` defines request-routing rules and
- associates the controller ("CRM\_Myextension\_Form\_FavoriteColor")
- with the web path ("civicrm/favcolor")
+ associates the controller `CRM_Myextension_Form_FavoriteColor`
+ with the web path `civicrm/favcolor`.
- `CRM/Myextension/Form/FavoriteColor.php` is the controller which
coordinates any parsing, validation, business-logic, or database
operations. For more details on how this class works, see [QuickForm
@@ -172,12 +166,12 @@ This creates three files:
[the smarty guide](http://www.smarty.net/docsv2/en/).
The auto-generated code for the controller and view demonstrate a few
-basic operations, such as adding a <SELECT\> element to the form.
+basic operations, such as adding a `<select>` element to the form.
->> 
-After adding or modifying a route in the XML file, you must reset
-CiviCRMs "menu cache". This can be done in a web browser by visiting
-"/civicrm/menu/rebuild?reset=1"
+!!! note
+ After adding or modifying a route in the XML file, you must reset
+ CiviCRMs "menu cache". This can be done in a web browser by visiting
+ `/civicrm/menu/rebuild?reset=1`
### Add a database upgrader, installer and uninstaller
@@ -188,7 +182,7 @@ comment out the various upgrade and uninstall functions
to make it work. Generally your install script belongs in an `sql/` folder
in the root of your extension with a name like 'install'
-This `civix` command does not require arguements:
+This `civix` command does not require arguments:
```bash
civix generate:upgrader
@@ -199,7 +193,7 @@ This creates two files and one directory:
- `CRM/Myextension/Upgrader.php` stores a series of upgrade
functions based on a function naming pattern similar to
Drupal's
- [hook\_update\_N](http://api.drupal.org/api/drupal/modules%21system%21system.api.php/function/hook_update_N/7).
+ [hook_update_N](http://api.drupal.org/api/drupal/modules%21system%21system.api.php/function/hook_update_N/7).
After examining the file's comments for example upgrade functions
you can then write your own.
- `CRM/Myextension/Upgrader/Base.php` contains helper functions
@@ -213,19 +207,19 @@ you can execute the upgrades through the web interface by visiting the
"Manage Extensions" screen. This screen will display an alert with an
action-link to perform the upgrades.
->> 
-The "upgrader" class is a wrapper for
-[hook\_civicrm\_upgrade](/confluence/display/CRMDOC43/Hook+Reference)
-which aims to be easy-to-use for developers with Drupal experience. If
-you need to organize the upgrade logic differently, then consider
-providing your own implementation of hook\_civicrm\_upgrade.
+!!! note
+ The "upgrader" class is a wrapper for
+ [hook_civicrm_upgrade](https://wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference)
+ which aims to be easy-to-use for developers with Drupal experience. If
+ you need to organize the upgrade logic differently, then consider
+ providing your own implementation of hook_civicrm_upgrade.
->> 
-Only use the upgrade system to manage new SQL
-tables. Do not manipulate core schema.
+!!! caution
+ Only use the upgrade system to manage new SQL
+ tables. Do not manipulate core schema.
If you need to create triggers on core SQL tables, use
-[hook\_civicrm\_triggerInfo](http://wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference).
+[hook_civicrm_triggerInfo](http://wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference).
This allows your triggers to coexist with triggers from other modules.
### Add a case type
@@ -241,7 +235,7 @@ command:
civix help generate:case-type
```
-This reports that civix expects a <Label> argurment and an optional name:
+This reports that civix expects a label argument and an optional name:
```bash
civix generate:case-type "Volunteer Training" Training
@@ -251,10 +245,10 @@ This creates two files:
- `xml/case/Training.xml` defines the roles, activity types, and
timelines associated with the new case type. For more in depth
- discussion of CiviCase XML, see [CiviCase
- Configuration](/confluence/display/CRMDOC/CiviCase+Configuration).
+ discussion of CiviCase XML, see
+ [CiviCase Configuration](https://wiki.civicrm.org/confluence/display/CRMDOC/CiviCase+Configuration).
- `alltypes.civix.php`(which may already exist) defines
- implementations of various hooks (notably hook\_civicrm\_caseTypes).
+ implementations of various hooks (notably hook_civicrm_caseTypes).
### Add custom fields
*(from CiviCRM v4.4+)*
@@ -263,7 +257,7 @@ Your extension can create one or more sets of custom
fields at installation. There are two
methods depending on whether the custom data set extends an entity
(e.g. "Individual" – without any specific subtype)
-or exends a specific subtype of an entity.
+or extends a specific subtype of an entity.
(e.g. Activities of type 'Volunteer')
#### Extending a base entity
@@ -272,13 +266,14 @@ This is the simplest scenario.
Start by creating a custom fields using the web interface and then export
them for use with the extension:
->> 
-Before you begin verify that civix is connected to your instance of CiviCRM by running `civix civicrm:ping`.
+!!! note
+ Before you begin verify that civix is connected to your instance of
+ CiviCRM by running `civix civicrm:ping`.
- On your development instance of CiviCRM, create the new custom
fields using the web interface. Note the unique ID of the custom data
group (also known as the "Custom Fieldset", "CustomGroup" or
- "civicrm\_custom\_group")
+ "civicrm_custom_group")
- Create an XML file with `civix generate:custom-xml`
specifying the custom-data group ID.
- Create an upgrader file with `civix generate:upgrader` to
@@ -298,11 +293,11 @@ civix generate:custom-xml --data=7
Most of the [CiviHR](https://github.com/civicrm/civihr/tree/master) modules rely on the first approach (e.g.:
[Upgrader/Base.php](https://github.com/civicrm/civihr/blob/master/hrqual/CRM/HRQual/Upgrader/Base.php#L244) and
-[auto\_install.xml](https://github.com/civicrm/civihr/blob/master/hrqual/xml/auto_install.xml)).
+[auto_install.xml](https://github.com/civicrm/civihr/blob/master/hrqual/xml/auto_install.xml)).
#### Extending an subtype
-<!-- This section still is not really clear to me.
+<!-- This section still is not really clear to me. (Erich Schulz)
Is this really about sub-types in an OO sense?? or subtypes in as a base
entity of a particular type as defined by its properties?
-->
@@ -321,9 +316,9 @@ and
To create this extension, the author used `civix generate:custom-data` and
then:
-1. Renamed the `xml/auto\_install.xml` to
+1. Renamed the `xml/auto_install.xml` to
`templates/hremerg-customdata.xml.tpl`
-2. Changed the value of `<extends\_entity\_column\_value\>` in the
+2. Changed the value of `<extends_entity_column_value>` in the
`.tpl file` using a variable instead of a hard-coded type ID.
3. Added logic in the upgrader to create the relationship type
4. Added logic in the upgrader to evaluate the Smarty template
@@ -334,8 +329,8 @@ CiviCRM
[hook functions](http://wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference)
allow extensions to run extra logic as
part of the normal CiviCRM processing. For example,
-`hook\_civicrm\_buildForm()` allows a module to run logic whenever a
-web-form is displayed, and `hook\_civicrm\_post()` allows a module to
+`hook_civicrm_buildForm()` allows a module to run logic whenever a
+web-form is displayed, and `hook_civicrm_post()` allows a module to
run logic after any entity is saved.
Hook function names follow the Drupal convention of being
@@ -343,7 +338,7 @@ the module's short-name concatenated to the hook name. This strict but simple
naming convention is what allows the CiviCRM core to locate your hook
functions and call them at the appropriate times.
For example, if our module's main file is
-`myextension.php` and we want to use `hook\_civicrm\_post()`
+`myextension.php` and we want to use `hook_civicrm_post()`
to write to a log file every time a contribution is saved, then our function must be called `myextension_civicrm_post()`:
To implement a hook, add a function to the module's main `.php`
@@ -370,14 +365,14 @@ function myextension_civicrm_post($op, $objectName, $objectId, &$objectRef) {
}
```
->> 
-When you first created the skeletal project, several hook functions were
-auto-generated in `myextension.php`. These functions are usually about
-one line long – they simply delegate the work to another function. For
-example `myextension\_civicrm\_config()` delegates work to
-`\_myextension\_civix\_civicrm\_config()`. You should feel free to add
-more code to `myextension\_civicrm\_config()`, but you should preserve
-the call to `\_myextension\_civix\_civicrm\_config()`. <!-- fixme! why?? -->
+!!! note
+ When you first created the skeletal project, several hook functions were
+ auto-generated in `myextension.php`. These functions are usually about
+ one line long – they simply delegate the work to another function. For
+ example `myextension_civicrm_config()` delegates work to
+ `_myextension_civix_civicrm_config()`. You should feel free to add
+ more code to `myextension_civicrm_config()`, but you should preserve
+ the call to `_myextension_civix_civicrm_config()`. <!-- fixme! why?? -->
### Add a resource file
@@ -392,7 +387,7 @@ CiviReport enables developers to define new business reports using
customizable SQL logic and form layouts.
If another existing report is close to your needs you may copy and modify it.
-To to see the available report generation options acitivate the `civix` help:
+To to see the available report generation options activate the `civix` help:
```bash
civix generate:report --help
@@ -408,7 +403,7 @@ This creates three files:
- `CRM/Myextension/Form/Report/MyReport.mgd.php` stores metadata
about the report in a format based on
- [hook\_civicrm\_managed](http://wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference)
+ [hook_civicrm_managed](http://wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference)
and the
[API](http://wiki.civicrm.org/confluence/display/CRMDOC/API+Reference).
- `CRM/Myextension/Form/Report/MyReport.php` contains the
@@ -428,7 +423,7 @@ Then run the `civix generate:report` command using the copy option
from with your extension directory.
For example, this command will copy the activity report in the class
-`CRM\_Report\_Form\_Activity` to a new report within your extension:
+`CRM_Report_Form_Activity` to a new report within your extension:
```bash
civix generate:report --copy CRM_Report_Form_Activity MyActivity Contact
@@ -453,7 +448,7 @@ This command will create two files:
- `CRM/Myextension/Form/Search/MySearch.mgd.php` stores metadata
about the custom search. The format of the file is based on
- [hook\_civicrm\_managed](http://wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference)
+ [hook_civicrm_managed](http://wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference)
and the
[API](http://wiki.civicrm.org/confluence/display/CRMDOC/API+Reference).
- `CRM/Myextension/Form/Search/MySearch.php` contains the
@@ -466,11 +461,11 @@ PHP, SQL and templates.
To make a new search based on an existing search first determine the name of
the original search class within the `civicrm/CRM/Contact/Form/Search/Custom`
-directory of CiviCRM source tree. Then run the "generate:search" command from
+directory of CiviCRM source tree. Then run the `generate:search` command from
within your module directory.
For example, the zipcode search is in the class
-`CRM\_Contact\_Form\_Search\_Custom\_ZipCodeRange`, so you can copy it with:
+`CRM_Contact_Form_Search_Custom_ZipCodeRange`, so you can copy it with:
```bash
civix generate:search --copy CRM_Contact_Form_Search_Custom_ZipCodeRange MySearch
@@ -481,7 +476,7 @@ on whether the original search screen defines its own Smarty template.
### Add an API function
-The [CiviCRM API](../api/general)
+The [CiviCRM API](/api/general)
provides a way to expose functions for use by other developers. API
functions allow implementing AJAX interfaces (using the
cj().crmAPI() helper), and they can also be called via REST, PHP,
@@ -495,11 +490,11 @@ Get started by accessing the `civix` help:
civix help generate:api
```
->> 
-Action names must be lowercase. The javascript helpers `CRM.api()` and
-`CRM.api3()` force actions to be lowercase. This issues does not present
-itself in the API Explorer or when the api action is called via PHP,
-REST, or SMARTY.
+!!! note
+ Action names must be lowercase. The javascript helpers `CRM.api()` and
+ `CRM.api3()` force actions to be lowercase. This issues does not present
+ itself in the API Explorer or when the api action is called via PHP,
+ REST, or SMARTY.
You can make your API code with a command in this pattern:
@@ -514,22 +509,22 @@ This creates one file:
particular way (as demonstrated by the auto-generated file).
<!-- fixme - clarify is this 4.3 and later? -->
-For use with CiviCRM 4.3, you can also add the "–schedule" option (e.g.
-"–schedule Hourly"). This will create another file:
+For use with CiviCRM 4.3, you can also add the `–schedule` option (e.g.
+`–schedule Hourly`). This will create another file:
- `api/v3/NewEntity/NewAction.mgd.php` provides the scheduling
record that will appear in the CiviCRM's job-manager.
### Add a new entity
->> 
-This functionality is considered "experimental and incomplete".
+!!! caution
+ This functionality is considered "experimental and incomplete".
You may have a need to create a new entity that does not exist in
CiviCRM. For this, you can use the command `civix generate:entity`
- Pick a name for your entity. In some places, CiviCRM expects a
- *FirstLetterCapitalizedName*, in others, an *underscore\_name*. Be
+ *FirstLetterCapitalizedName*, in others, an *underscore_name*. Be
absolutely consistent in your naming, because CiviCRM needs to
translate between those two naming conventions.
@@ -537,7 +532,7 @@ CiviCRM. For this, you can use the command `civix generate:entity`
FirstLetterCapitalized here). This creates a skeletal file for your
XML schema, your BAO, and your API. It does NOT create a skeletal
SQL file to create your table or DAO files at this time.
-- Edit the XML schema in the "xml" folder to match the fields you
+- Edit the XML schema in the `xml` folder to match the fields you
want. Minimal documentation is available
[here](https://wiki.civicrm.org/confluence/display/CRMDOC/Database+Reference),
but you are better off looking at the [existing XML
@@ -550,7 +545,7 @@ CiviCRM. For this, you can use the command `civix generate:entity`
`php ./GenCode.php` (In CiviCRM 4.7.12+, run
`<civiroot>/bin/setup.sh -g` instead). This will generate a DAO file
for you in the CiviCRM core code; copy it into the
- CRM/<Entityname\>/DAO folder of your extension.
+ `CRM/<Entityname>/DAO` folder of your extension.
- Currently, `civix` does not generate the SQL to create and
drop your table(s). You can create these by hand, or, if
you used the `<civiroot>/bin/setup.sh -g` technique to create your
@@ -566,7 +561,7 @@ CiviCRM. For this, you can use the command `civix generate:entity`
<!-- fixme update and clarify -->
- Run `civix generate:upgrader` from within your extension.
- Define your entity using
- [hook\_civicrm\_entityTypes](https://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_entityTypes).
+ [hook_civicrm_entityTypes](https://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_entityTypes).
### Add a unit-test class
@@ -578,9 +573,9 @@ long as you follow a few basic conventions.
The following steps will create and run a test in your extension.
->> 
-Before preparing unit-tests with extensions, you must first
-[configure you personal testing sandbox](/confluence/display/CRM/Setting+up+your+personal+testing+sandbox+HOWTO) and enable your extension on the sandbox.
+!!! note
+ Before preparing unit-tests with extensions, you must first
+ [configure you personal testing sandbox](https://wiki.civicrm.org/confluence/display/CRM/Setting+up+your+personal+testing+sandbox+HOWTO) and enable your extension on the sandbox.
Explore the full options with:
@@ -589,7 +584,7 @@ civix help generate:test
```
To create a skeletal test-class choose a class name in
-your extension's namespace (*CRM\_Myextension*) that ends with the
+your extension's namespace (*CRM_Myextension*) that ends with the
word *Test*:
```bash
@@ -614,8 +609,8 @@ how to write a test class:
- Review the example code in
[org.civicrm.exampletests](https://github.com/totten/org.civicrm.exampletests)
->> 
-The following instructions are deprecated. Updated instructions coming soon.
+!!! caution
+ The following instructions are deprecated. Updated instructions coming soon.
```bash
# Check if civix can connect to the civi api
@@ -627,8 +622,7 @@ civix config:get
civix config:set civicrm_api3_conf_path /your/path/to/sites/default
```
-To run this test-class, change to your extension folder and call "civix
-test":
+To run this test-class, change to your extension folder and run the following:
```bash
civix test CRM_Myextension_MyTest
diff --git a/docs/extensions/publish.md b/docs/extensions/publish.md
new file mode 100644
index 0000000000000000000000000000000000000000..7ef3d29e2850ab8e1525665166d2b958952dc179
--- /dev/null
+++ b/docs/extensions/publish.md
@@ -0,0 +1,128 @@
+# 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
diff --git a/docs/img/check.png b/docs/img/check.png
deleted file mode 100644
index 09335f512b0f25297089d982f7c96dd13be3d73d..0000000000000000000000000000000000000000
Binary files a/docs/img/check.png and /dev/null differ
diff --git a/docs/img/danger.png b/docs/img/danger.png
deleted file mode 100644
index 84c54be0bf8aa30fae0c75c2cc9ab53084d7f456..0000000000000000000000000000000000000000
Binary files a/docs/img/danger.png and /dev/null differ
diff --git a/docs/img/info.png b/docs/img/info.png
deleted file mode 100644
index 87a4d2681f2bf86086c089a158b506922cd030e7..0000000000000000000000000000000000000000
Binary files a/docs/img/info.png and /dev/null differ
diff --git a/docs/markdownrules.md b/docs/markdownrules.md
index ca7f1986b951667bc512392a64236d4727009427..50325a938521982e04bf0927bc9620b4d0d3c09c 100644
--- a/docs/markdownrules.md
+++ b/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.
diff --git a/mkdocs.yml b/mkdocs.yml
index 2fae3557745881987069e39e67b8830437901195..b9c956dd26cb66da58000389e566a8e187e1f75b 100644
--- a/mkdocs.yml
+++ b/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
diff --git a/redirects/wiki-crm.txt b/redirects/wiki-crm.txt
new file mode 100644
index 0000000000000000000000000000000000000000..a6b25714a8f12e83aec25b7417fd3d14ff602370
--- /dev/null
+++ b/redirects/wiki-crm.txt
@@ -0,0 +1,2 @@
+Documentation+Infrastructure+Canary develop
+Book+style+guide best-practices/documentation-style-guide
diff --git a/redirects/wiki-crmdoc.txt b/redirects/wiki-crmdoc.txt
index 65ceb22dfbb6b8a224bfd65089dde699d241954b..339b3498336bd10e9ee0119124fa98022d04312b 100644
--- a/redirects/wiki-crmdoc.txt
+++ b/redirects/wiki-crmdoc.txt
@@ -1,3 +1,10 @@
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
+