Revise download & install pages in UG

Author: jim-parry

user_guide_src/source/changelogs/index.rst

@@ -9,17 +9,17 @@ Release Date: Not Released
 
 **Next alpha release of CodeIgniter4**
 
-- Numerous bug fixes
-- Many missing features implemented
+- Numerous bug fixes, across the framework
+- Many missing features implemented, across the framework
 - Code coverage is up to 72%
 - CodeIgniter4 has been promoted to its own github organization.
-    That is reflected in docs and comments.
+  That is reflected in docs and comments.
 - We have integrated a git pre-commit hook, which will apply the
-    CI4 code sniffer rules, and attempt to fix them.
-    We have run all the source files through it, and any "funny"
-    code formatting is temporary until the rules are updated.
+  CI4 code sniffer rules, and attempt to fix them.
+  We have run all the source files through it, and any "funny"
+  code formatting is temporary until the rules are updated.
 - We welcome Natan Felles, from Brazil, to the code developer team.
-    He has proved passionate, dedicated and thorough :)
+  He has proven to be passionate, dedicated and thorough :)
 
 :doc:`See all the changes. </changelogs/next>`
 

user_guide_src/source/changelogs/next.rst

@@ -9,8 +9,12 @@ Release Date: Not Released
 The list of changed files follows, with PR numbers shown.
 
 - admin/
+        - framework/* #1553
+        - starter/* #1553
+        - docbot #1553
 	- release* #1484, 
 	- pre-commit #1388
+        - README.md #1553
 	- setup.sh #1388
 
 - application /
@@ -198,7 +202,7 @@ The list of changed files follows, with PR numbers shown.
 	- CommonFunctionsTest #1180, #1486, #1496
 
 - user_guide_src /source/
-	- changelogs/ #1385, #1490
+	- changelogs/ #1385, #1490, #1553
 	- concepts/
 		- autoloader #1547
 		- security #1540
@@ -230,14 +234,15 @@ The list of changed files follows, with PR numbers shown.
 		- static_pages #1547
 
 - /
-	- composer.json #1388, #1418, #1536
-	- README.md
+	- composer.json #1388, #1418, #1536, #1553
+	- README.md #1553
 	- spark 2047b5a
 	- .travis.yml #1394
 
 PRs merged:
 -----------
 
+- #1553 Admin/scripts
 - #1550 remove commented CLI::newLine($tempFiles) at FileLocator
 - #1549 use .gitkeep instead of .gitignore in Database/Seeds directory
 - #1547 Change file exists to is file

user_guide_src/source/installation/downloads.rst

@@ -2,14 +2,51 @@
 Downloading CodeIgniter
 #######################
 
-`Git <http://git-scm.com/about>`_ is a distributed version control system.
+The CodeIgniter 4 open source project has its own 
+`Github organization <https://github.com/codeigniter4>`_.
 
-Public Git access is available at `GitHub <https://github.com/codeigniter4/CodeIgniter4>`_.
-Please note that while every effort is made to keep this code base
-functional, we cannot guarantee the functionality of code taken from
-the develop branch.
+There are a number of repositories there of interest:
 
-Stable versions are available via `GitHub Releases <https://github.com/codeigniter4/framework/releases>`_.
+- `CodeIgniter4 <https://github.com/codeigniter4/CodeIgniter4>`_ 
+    holds the codebase for the project, including unit testing
+    and the source from which the user guide is built.
+    This would be used by contributors to the project.
+- `framework <https://github.com/codeigniter4/framework>`_ 
+    holds the released versions of the framework.
+    This would be normally be used by developers.
+- `appstarter <https://github.com/codeigniter4/appstarter>`_ 
+    holds the released application starter, with application
+    and public folders, but with only a composer
+    dependency on the framework.
+    This is meant as the easy way to start a CodeIgniter 4 project.
+- `userguide <https://github.com/codeigniter4/userguide>`_ 
+    holds the pre-built user guide. It can be downloaded
+    on its own, or `viewed online <https://codeigniter4.github.io/userguide>`_.
+- `translations <https://github.com/codeigniter4/translations>`_ 
+    holds translations of the CodeIgniter 4 system messages.
+    Developers can use this for :doc:`localization </outgoing/localization>`.
+- `coding-standard <https://github.com/codeigniter4/coding-standard>`_ 
+    holds the coding conventions we use for source code that is
+    part of the framework itself. 
+    It is a dependency of the codebase repository, for contributors.
 
-You can also download a zip of the `development branch <https://codeload.github.com/codeigniter4/CodeIgniter4/zip/develop>`_,
-i.e. the upcoming version.
+In all the above, the latest version of a repository can be downloaded
+by selecting the "releases" link in the secondary navbar inside
+the "Code" tab. The current (in development) version of each can
+be cloned or downloaded by selecting the "Clone or download" dropdown
+button on the right-hand side if the repository homepage.
+
+Composer Packages
+=================
+
+We also maintain composer-installable packages on `packagist.org <https://packagist.org/search/?query=codeigniter4>`_.
+These correspond to the repositories mentioned above:
+
+- `codeigniter4/framework <https://packagist.org/packages/codeigniter4/framework>`_
+- `codeigniter4/appstarter <https://packagist.org/packages/codeigniter4/appstarter>`_
+- `codeigniter4/userguide <https://packagist.org/packages/codeigniter4/userguide>`_
+- `codeigniter4/translations <https://packagist.org/packages/codeigniter4/translations>`_
+- `codeigniter4/CodeIgniter4 <https://packagist.org/packages/codeigniter4/CodeIgniter4>`_
+- `codeigniter4/coding-standard <https://packagist.org/packages/codeigniter4/codeigniter4-standard>`_
+
+See the :doc:`Installation </installation/index>` page for more information.

user_guide_src/source/installation/index.rst

@@ -2,79 +2,14 @@
 Installation
 ############
 
-CodeIgniter4 can be installed manually, or using Composer.
-
-.. note:: Before using CodeIgniter, make sure that your server meets the
-          :doc:`requirements </intro/requirements>`.
-
-Manual Installation
-===================
-
-CodeIgniter is installed via manual download and unzip the package.
-
-Composer Installation
-=====================
-
-While not required, CodeIgniter can be installed via `composer <https://getcomposer.org>`_ create-project command.
-
-::
-
-    composer create-project codeigniter4/framework
-
-.. note:: When installing via composer, a pre-commit hook is installed for this repo that automatically runs
-     PHP Code Sniffer and fixes any fixable issues on commit.
-
-Running
-=======
-
-#. Upload the CodeIgniter folders and files to your server. The
-   **index.php** file will be in the **public** folder inside
-   your project root.
-#. Open the **application/Config/App.php** file with a text editor and
-   set your base URL. If you intend to use encryption or sessions, set
-   your encryption key. If you need more flexibility, the baseURL may
-   be set within the .env file as **app.baseURL="http://example.com"**.
-#. If you intend to use a database, open the
-   **application/Config/Database.php** file with a text editor and set your
-   database settings.
-
-For the best security, both the system and any application directories
-come placed above the web root so that they are not directly accessible
-via a browser. By default, **.htaccess** files are included in each directory
-to help prevent direct access, but it is best to remove them from public
-access entirely in case the web server configuration changes or doesn't
-abide by the **.htaccess**.
-
-If you would like to keep your views public it is also possible to move
-the **views** directory out of your **application** directory, to a
-corresponding folder inside **public**. If you do this, remember to
-open your main index.php file and set the
-``$system_path``, ``$application_folder`` and ``$view_folder`` variables,
-preferably with a full path, e.g. '*/www/MyUser/system*'.
-
-One additional measure to take in production environments is to disable
-PHP error reporting and any other development-only functionality. In
-CodeIgniter, this can be done by setting the ``ENVIRONMENT`` constant, which
-is more fully described on the :doc:`environments page </general/environments>`.
-By default, the application will run using the "production" environment. To
-take advantage of the debugging tools provided, you should set the environment
-to "develop".
-
-.. caution:: Using PHP's built-in web server is likely to cause problems,
-	as it does not process the `.htaccess` file used to properly handle requests.
-
-That's it!
-
-If you're new to CodeIgniter, please read the :doc:`Getting
-Started <../intro/index>` section of the User Guide
-to begin learning how to build dynamic PHP applications. Enjoy!
+There are a number of ways to download, install and run a
+CodeIgniter4 app. Read on :)
 
 .. toctree::
-    :hidden:
     :titlesonly:
 
     downloads
-    self
+    installing
+    running
     upgrading
     troubleshooting
-    local_server

user_guide_src/source/installation/installing.rst

@@ -0,0 +1,174 @@
+############
+Installation
+############
+
+CodeIgniter4 can be installed in a number of different ways: manually, 
+using `Composer <https://getcomposer.org>`_, or even using 
+`Git <https://git-scm.com/>`_. This section addresses how to use
+each technique, and explains some of the pros and cons of them.
+
+Once installed, read the next section, :doc:`running your app </installation/running>`.
+
+.. note:: Before using CodeIgniter 4, make sure that your server meets the
+          :doc:`requirements </intro/requirements>`.
+
+Manual Installation
+============================================================
+
+Install the framework by downloading the latest version,
+and extract it to become your project root. Your document
+root will be the ``public`` folder inside here.
+
+Pros:
+
+- download and run; this is the installation technique
+  closest to that described for `CodeIgniter 3 <https://www.codeigniter.com/user_guide/installation/index.html>`_.
+
+Cons:
+
+- upgrading the framework is done by downloading a new copy
+  of the framework, and then following the upgrade
+  directions to merge that with your project (typically
+  replace the ``system`` folder and inspect designated
+  ``application/Config`` folders for affected changes).
+
+Resulting folder structure:
+
+- application
+- public
+- system
+- writable
+
+Composer Installation
+============================================================
+
+Install the latest version of the framework with::
+
+    > composer create-project codeigniter4/framework PROJECT_ROOT
+
+Pros:
+
+- simple installation
+
+Cons:
+
+- upgrading the framework is done by::
+
+        > composer update
+
+  You would then need to resolve merge conflicts for any framework
+  changes to ``application`` files that you modified for your app.
+
+Resulting folder structure:
+
+- application
+- public
+- system
+- writable
+
+
+Codebase Installation
+============================================================
+
+Install the latest version of the codebase by
+
+- forking the codebase to your github account
+- cloning your forked repository locally
+
+Pros:
+
+- you get the latest version of the codebase
+- you can propose contributions by creating a feature branch, and then
+  submitting a pull request to the main repository once you have
+  pushed your feature branch to your repository
+- a pre-commit hook is installed for this repo that binds it to the
+  coding-standard repo, and then automatically runs
+  PHP Code Sniffer and fixes any fixable issues whenever you commit.
+
+Cons:
+
+- you need to add a git remote alias to your project, so you can
+  pull codebase changes::
+
+        > git remote add upstream https://github.com/codeigniter4/CodeIgniter4.git
+
+- upgrading the framework is done by::
+
+        > git checkout develop
+        > git pull upstream develop
+        > git push origin develop
+
+  You would then need to resolve merge conflicts for any framework
+  changes that conflict with modifications you have made.
+
+Resulting folder structure:
+
+- application
+- public
+- system
+- tests
+- user_guide_src
+- writable
+
+App Starter Installation
+============================================================
+
+Install the latest version of the framework's app starter with::
+
+    > composer create-project codeigniter4/appstarter PROJECT_ROOT
+
+Pros:
+
+- simple installation
+
+Cons:
+
+- upgrading the framework is done by::
+
+        > composer update
+
+  You would then need to resolve merge conflicts for any framework
+  changes to ``application`` files that you modified for your app.
+
+Resulting folder structure:
+
+- application
+- public
+- writable
+- vendor/codeigniter4/framework
+
+    - application
+    - public
+    - system
+
+Translations Installation
+============================================================
+
+Install the available localizations to an existing CodeIgniter 4
+project with::
+
+    > composer require codeigniter4/translations
+
+Update the translations at any time with::
+
+    > composer update
+
+When the translations are installed, they are added to the appropriate namespace.
+See the :doc:`localization page </outgoing/localization>`
+for guidance.
+
+Resulting folder structure:
+
+...
+
+- vendor
+
+    - codeigniter4
+
+        - translations
+
+Coding Standards Installation
+============================================================
+
+This is bound and installed automatically as part of the 
+codebase installation.