Merge branch 'develop' of github.corp.magento.com:Magento/devdocs_internal into develop

Author: Magento CICD

common/images/pdg-config-file-structure.png

@@ -0,0 +1,54 @@
+---
+layout: default
+group: arch-guide
+subgroup: Architectural Basics
+title: Extensibility and modularity
+menu_title: 
+menu_node: 
+menu_order: 
+github_link: architecture/extensibility.md
+---
+
+<h2 id="m2arch-whatis-overview">Extensibility and modularity</h2>
+
+
+Product <i>extensibility</i> describes how easy  it is to expand  a product's feature set. An extensible product has been designed from its earliest planning stages for  customization and enhancement. It is designed for ease in  augmenting your installation's feature set, enriching current features, and integrating with third-party software
+
+
+Maximizing extensibility has been our goal through all aspects of Magento development.  Core tasks such as Shipping are packaged as discrete modules, and you expand your storefront features by installing modules that you either buy from third-party vendors or create yourself. While logic specific to each shipping carrier is packaged in a discrete module, you can easily add or delete shipping providers by simply adding or deleting modules. The product framework provides common logic to control routing and other core application functions.  
+
+Explore Magento's potential for customization through these topics: 
+
+* Global product features that support extension development
+* Ease of frontend customization 
+
+
+<h3>What makes a product extensible? </h3>
+
+<i>Magento extensibility</i> describes the product's built-in ability for developers and merchants to routinely extend their storefront’s capabilities as their business grows. 
+
+
+The effort involved in extending a product is influenced by: 
+
+* <b>architectural principles that guide product structure</b>. Central to the Magento model of software development is the practice of replacing or extending core code rather than editing it. This strategy enables you to maintain the integrity of the tested code we provide while still extensively customizing your storefront.
+
+
+* <b>open-source software to create and manage extensions</b>. Magento is built on open-source technologies, built by and for the development community. It uses Composer, an open-source tool, to manage dependencies. See <a href="{{ site.gdeurl }}architecture/tech-stack.html">Technology Stack</a>  for a complete list. 
+
+* <b>coding standards</b>. Adherence to  standard best practices for PHP and JavaScript code ensures that the code base is sound. Magento has adopted most of the Zend Framework Coding Standards for PHP. See <a href="{{ site.gdeurl }}coding-standards/bk-coding-standards.html">Coding Standards</a> for more information.
+
+* <b>upgrade and versioning strategies</b>. Magento has well-defined upgrade and versioning strategies that can help you avoid any problems with software component dependencies. Add modules after confirming that the module version is compatible with the Magento Framework version. See  <a href="{{ site.gdeurl }}install-gde/bk-install-guide.html">Installation Guide</a> for more information. 
+
+
+<h3 id="m2arch-related">Related topics</h3>
+
+
+<a href="{{ site.gdeurl }}architecture/archi_perspectives/ABasics_intro.html">Architectural basics</a>
+
+<a href="{{ site.gdeurl }}architecture/global_extensibility_features.html">Global product features that support extension development</a>
+
+<a href="{{ site.gdeurl }}architecture/frontend_custom_strategies.html">Ease of frontend customization</a>
+
+
+
+

guides/v2.0/architecture/extensibility.md

@@ -0,0 +1,38 @@
+---
+layout: default
+group: arch-guide
+subgroup: 
+title: Security overview
+menu_title: Security 
+menu_order: 
+github_link: architecture/security_intro.md
+---
+
+<h2 id="security_intro">Security overview</h2>
+Magento 2.0 includes the following security enhancements: 
+
+
+
+* <b>Enhanced password management</b>. Magento has strengthened the hashing algorithms (SHA-256) used in password management. 
+
+
+* <b>Improved prevention of cross-site scripting (XSS) attacks by making escaped data the default</b>. The Magento Framework has adopted conventions that regulate the escaping of data in output. These conventions include the ability to escape  output for HTML pages (HTML, JSON, and JavaScript) and email. Where possible, escaping is transparent to client code. See <a href="{{ site.gdeurl }}frontend-dev-guide/templates/template-security.html">Security measures against XSS attacks</a> in the Frontend Developer Guide. 
+
+* <b>Restricted permissions for file access</b>. Ability to set discrete file access for production and developer  modes. This change tightens security on generated files, static files, and any files and directories created by Magento (including logs, backups, and reports). See <a href="{{ site.gdeurl }}install-gde/install/file-system-perms.html"> Set file system ownership and permissions </a> in the Installation Guide.
+
+	Magento also provides  a CLI command that switches between developer mode and production mode. When you use the command to switch mode, the system also changes file system permissions. In production mode,   directory permissions are set to 750, and file permissions are set to 640. In developer mode, directory permissions are set to 770, and file permissions are set to 660. 
+	
+	(Permissions need to vary due to user need, of course. For example, the Magento file system owner must own the file system. In contrast, the web server user needs read access only to the file system and write access to some directories (such as `pub/media`). And the web server user should not have write access to the entire Magento file system. For more information, see <a href="{{ site.gdeurl }}install-gde/prereq/apache-user.html"> Create the magento file system owner</a>.)
+
+* <b>Improved prevention of clickjacking exploits</b>. Magento safeguards your store from clickjacking attacks by using an X-Frame-Options HTTP request header. For more information, see <a href="{{ site.gdeurl }}config-guide/secy/secy-xframe.html"> X-Frame-Options header</a>.
+
+* <b>Use of non-default admin URL</b>. A default admin URL makes it easy to target attacks on specific locations using automated password guessing. To prevent against this type of attack, Magento by default creates a random Admin URI when you install the product. The CLI is provided so that you can  see the password if you forget it. You can also use the CLI change this URI.  Although the use of a non-default admin URL will not secure the site, its use will help prevent large-scale automated attacks. See <a href="{{ site.gdeurl }}install-gde/install/cli/install-cli-adminurl.html"> Display or change the Admin URI</a> in Configuration Guide for more information. 
+
+
+
+
+<h2>Related topics</h2>
+<a href="{{ site.gdeurl }}config-guide/bk-config-guide.html">Configuration Guide</a>
+
+
+

guides/v2.0/architecture/security_intro.md

@@ -0,0 +1,47 @@
+---
+layout: default
+group: arch-guide
+subgroup: Architectural Basics
+title: Storefront customization strategies
+menu_title: Storefront customization strategies
+menu_order: 
+github_link: architecture/storefront_customization.md
+
+---
+
+<h2>Storefront customization strategies</h2>
+
+We can generalize about the range of storefront customizations that the Magento supports. This range spans the simplest customizations, which involve only small additions to the default Magento storefront settings, to a complete replacement of Magento-provided HTML and CSS. 
+
+These four levels of potential storefront customization are listed in order of increasing complexity. 
+
+<h3>Extend Magento-Provided CSS</h3>
+Magento supplies a default theme and a LESS-based CSS set of styles. You can substantially change a storefront using CSS only.  This uncomplicated strategy might suit projects with a limited budget, or might interest developers who create different skins for a site. A small business enter this process of storefront customization by buying a third-party developed theme from Magento Connect to extend the default values.
+
+<h3>Replace PHTML template files</h3>
+In addition to extending the default CSS, you can generate different HTML markup. For example, you might need to add a missing CSS class name, or an add an extra `<div>` tag to achieve some visual effect. You might also need to tweak some JavaScript to cope with different HTML markup. This change is more demanding than simply extending Magento CSS, but is still within the grasp of smaller projects and leaner teams.
+
+<h3>Replace Magento-Provided CSS</h3>
+Rather than edit the default CSS provided by Magento, you might decide to replace all the default storefront CSS code with your own. This strategy avoids tying a project to the Magento-provided CSS, but puts a greater burden on project development and integration. It also allows use of different CSS tools or technologies not provided with Magento. Partners who build their own set of CSS libraries could reuse these libraries on different customer projects. (These unique CSS libraries may help differentiate a partner from others in the market.) 
+
+In addition to replacing CSS files, you might need to replace small amounts of HTML and JavaScript.
+
+
+<h3>Replace Magento-Provided CSS, HTML, and JavaScript</h3>
+Delivering a sharply different shopping experience than the default Magento installation provides is a more substantial task. However, the tradeoff might be a more complicated experience integrating additional extensions into your installation in the future. 
+
+<div class="bs-callout bs-callout-info" id="info">
+  <p>Note: Any customization of your storefront will work optimally, and provide the easiest path for later upgrades, if you follow the best practice of consistently compartmentalizing code by type. For example, keep all HTML in PHTML files; keep all JavaScript in JavaScript files.</p>
+</div>
+
+<h3>Related topics</h3>
+
+<a href="{{ site.gdeurl }}architecture/AStorefront_view.html">Magento storefront view</a>
+
+<a href="{{ site.gdeurl }}frontend-dev-guide/bk-frontend-dev-guide.html">Frontend Developer Guide</a>
+
+
+<a href="{{ site.gdeurl }}javascript-dev-guide/bk-javascript-dev-guide.html">JavaScript Developer Guide</a>
+
+
+

guides/v2.0/architecture/storefront_customization.md

@@ -2,28 +2,25 @@
 layout: default
 group: Contributor Guide
 subgroup: 
-title: Contribute to Magento DevDocs!
-menu_title: Contribute to Magento DevDocs!
+title: Contribute to Magento DevDocs
+menu_title: Contribute to Magento DevDocs
 menu_order: 100
+github_link: extension-dev-guide/Contribute_edg.md
 
 ---
 
-We encourage our community members to add content; either by writing a full topic, adding new sections to existing topic, or even just adding a few sentences about something you know on an existing topic. Don't worry about perfect grammar or form; just get your brilliance down!!
+We encourage our users to add or correct Magento DevDoc content. Write a full topic, add a new section to an existing topic, or even just add a few sentences about something you know on an existing topic. Don't worry about grammar or form; we can fix that for you!
 
-The files are mostly written in the markdown language (and HTML where needed). 
+Magento Devdocs site content is written in [Markdown](https://daringfireball.net/projects/markdown/), and is kept in Github. If you know how to use Github, you can contribute to our docs.
 
-To get started, review the <a href="{{ site.gdeurl }}contributor-guide/contributing.html">Contributor Guide</a> to learn about the process for code and doc contributions, including how to fork the repository and do a Pull Request to have your work submitted and reviewed.
+Review the Table of Contents in the left pane of the Guide, and determine which topic areas you can contribute to, or any that might be missing.
 
-Then, review the Table of Contents in the left pane of the Guide, and determine which topic areas you can contribute to, or any that might be missing.
-
-To add your knowledge to our Docs, you can:
+To add to Magento Docs:
 
 * edit your local version of an existing file
 * use the <a href="{{ site.githuburl }}template.md">generic template</a> and write a brand new topic, we will find the right home for it in the appropriate Guide.
 * use an existing, empty template to write about a topic that we know we need, but haven't yet gotten around to writing
+* Create a Pull Request to have your contribution reviewed by the DevDocs team. 
 
-
-Create a Pull Request to have your contribution reviewed by the DevDocs team. 
-
-Your contributions to our Docs and your experience with using Magento are very valued and appreciated. Let us know if you have any questions!
+Your contributions to Magento Docs informed by your experience with using Magento are highly valued and appreciated. Let us know if you have any questions!
 

guides/v2.0/extension-dev-guide/Contribute_edg.md

@@ -24,6 +24,7 @@ The following details the module building process:
 
 * [Module file structure](module-file-structure.html)
 * [Define your configuration files](required-configuration-files.html)
+* [Component registration](component-registration.html)
 * [Create your module](create_module.html)
 * [Module load order](module-load-order.html)
 * [Enable your module](enable-module.html)

guides/v2.0/extension-dev-guide/build.md

@@ -0,0 +1,91 @@
+---
+layout: default
+group: extension-dev-guide
+subgroup: 3_Build
+title: Component registration
+menu_title: Component registration
+menu_order: 4
+github_link: extension-dev-guide/composer-integration.md
+redirect_from: /guides/v1.0/extension-dev-guide/composer-integration.html
+
+---
+##{{page.menu_title}}
+
+
+Magento components, including modules, themes, and languages, must be registered in the Magento system through the Magento `ComponentRegistrar` class.
+
+Each component must have a file called `registration.php` in its root directory. For example, here is the `registration.php` file for Magento's [AdminNotification module](https://github.corp.ebay.com/magento2/magento2ce/blob/develop/app/code/Magento/AdminNotification/registration.php). Depending on the type of component, registration is performed through `registration.php` by adding to it as follows:
+
+###Modules
+
+Modules are registered with:
+
+     ComponentRegistrar::register(ComponentRegistrar::MODULE, '<VendorName_ModuleName>', __DIR__);
+
+where &lt;VendorName> is the name of the company providing the module and &lt;ModuleName> is the name of the module.
+     
+#####Example
+     ComponentRegistrar::register(ComponentRegistrar::MODULE, 'Magento_AdminNotification', __DIR__);
+<p>&nbsp;</p>
+
+
+###Themes
+
+Themes are registered with:
+
+     ComponentRegistrar::register(ComponentRegistrar::THEME, '<area>/<vendor>/<theme name>', __DIR__);
+
+where &lt;area> is the functional area of the module (frontend, controller, and so on.), &lt;vendor> is the name of the company providing the theme, and &lt;theme name> is the name of the theme.
+
+
+#####Example
+     ComponentRegistrar::register(ComponentRegistrar::THEME, 'frontend/Magento/luma', __DIR__);
+
+<p>&nbsp;</p>
+
+
+###Languages
+Languages are registered with:
+
+     ComponentRegistrar::register(ComponentRegistrar::LANGUAGE, '<VendorName>_<packageName>', __DIR__);
+
+where &lt;VendorName> is the name of the company providing the package and &lt;packageName> is the name of the package.
+
+#####Example
+     ComponentRegistrar::register(ComponentRegistrar::LANGUAGE, 'magento_de_de', __DIR__);
+
+<p>&nbsp;</p>
+
+###Invoke registration.php in composer.json
+
+After you create your `registration.php` file and you are creating [your module's composer.json file](create_module.html#add-the-module8217s-composerjson-file), remember to invoke your `registration.php` file in the autoload section of `composer.json`:
+
+     {
+    "name": "Acme-vendor/bar-component",
+    "autoload": {
+        "psr-4": { "AcmeVendor\\BarComponent\\": "" },
+        "files": [ "registration.php" ]
+    }
+}
+
+<p>&nbsp;</p>
+
+##Sample registration.php file
+
+{% highlight php startinline=true %}
+    <?php
+/**
+* Copyright © 2015 Magento. All rights reserved.
+* See COPYING.txt for license details.
+*/
+\Magento\Framework\Component\ComponentRegistrar::register(
+  \Magento\Framework\Component\ComponentRegistrar::MODULE,
+  'Magento_AdminNotification',
+  __DIR__
+);
+
+{%endhighlight %}
+
+##Next
+
+[Create a module](create_module.html)

guides/v2.0/extension-dev-guide/component-registration.md

@@ -4,13 +4,15 @@ group: extension-dev-guide
 subgroup: 3_Build
 title: Create a module
 menu_title: Create a module
-menu_order: 4
+menu_order: 5
 github_link: extension-dev-guide/create_module.md
 redirect_from: /guides/v1.0/extension-dev-guide/create_module.html
 ---
 ##{{page.menu_title}}
 
-Now that you have [determined your module’s initial file structure](module-file-structure.html) and have an idea of the [configuration files](required-configuration-files.html) you’ll need, you can create the module.
+Now that you have [determined your module’s initial file structure](module-file-structure.html), have an idea of the [configuration files](required-configuration-files.html) you’ll need, and you've [registered your module](component-registration.html), you can create the module.
+
+
 
 ##Add the module’s `module.xml` file
 Declare the module itself by adding a module.xml file in the `/etc` folder of your module.
@@ -31,7 +33,10 @@ The smallest working module.xml file would look something like this:
 
 
 	{
-    "name": "your-name/module-foobar",
+    "name": "your-name/module-Acme",
+    "autoload": {
+        "psr-4": { "AcmeVendor\\BarComponent\\": "" },
+        "files": [ "registration.php" ],
     "description": "Test module for Magento 2",
     "require": {
         "php": "~5.5.0|~5.6.0",

guides/v2.0/extension-dev-guide/create_module.md

@@ -4,7 +4,7 @@ group: extension-dev-guide
 subgroup: 3_Build
 title: Enable a module
 menu_title: Enable a module
-menu_order: 6
+menu_order: 7
 github_link: extension-dev-guide/enable-module.md
 
 ---

guides/v2.0/extension-dev-guide/enable-module.md

@@ -10,10 +10,14 @@ github_link: extension-dev-guide/module-file-structure.md
 ---
 ##{{page.menu_title}}
 
-Magento 2 looks for the files that make up a module, including configuration files, in particular places. Follow the predefined file structure to ensure that your module works as expected.
+Magento 2 looks for the files that make up a module, including configuration files, in particular places inside the module file structure. Follow the predefined file structure to ensure that your module works as expected.
 
+A module can live anywhere under the Magento root directory. Regardless of where you add it, you must [register the module's location](component-registration.html).
 
-###Magento 2 Module File Structure
+
+
+
+###Magento 2 Module File structure
 
 
 A typical file structure for a Magento 2 module:
@@ -60,7 +64,8 @@ You can add subfolders inside your module folder as you need them (Block, Contro
 
 Or, you could just add them at once:
 
-    mkdir Api && mkdir Block && mkdir Controller && mkdir etc && mkdir Helper && mkdir i18n && mkdir Model && mkdir view
+    mkdir Api Block Controller etc Helper i18n Model view
+
 
 Make sure you add the `etc` folder; it is required, and is where most of the configuration files, including `module.xml`, are kept.
 

guides/v2.0/extension-dev-guide/module-file-structure.md

@@ -4,7 +4,7 @@ group: extension-dev-guide
 subgroup: 3_Build
 title: Module load order
 menu_title: Module load order
-menu_order: 5
+menu_order: 6
 github_link: extension-dev-guide/module-load-order.md
 
 ---

guides/v2.0/extension-dev-guide/module-load-order.md

@@ -17,5 +17,6 @@ Before you start building Magento modules, make sure you’ve got Magento an
 
 * [Install Magento and any required dependencies]({{ site.gdeurl }}/install-gde/bk-install-guide.html)
 * [Composer integration](composer-integration.html)
+* [Component registration](component-resgistration.html)
 * [Set your mode to developer]({{ site.gdeurl }}/config-guide/bootstrap/magento-how-to-set.html)
 <!-- * [Determine your file structure](x) -->