Merge pull request #1690 from jim-parry/docs/install

Rework install docs

user_guide_src/source/incoming/incomingrequest.rst

@@ -1,6 +1,5 @@
-=====================
 IncomingRequest Class
-=====================
+*********************
 
 The IncomingRequest class provides an object-oriented representation of an HTTP request from a client, like a browser.
 It extends from, and has access to all the methods of the :doc:`Request </incoming/request>` and :doc:`Message </incoming/message>`
@@ -270,7 +269,6 @@ You can easily negotiate content types with the request through the ``negotiate(
 
 See the :doc:`Content Negotiation </incoming/content_negotiation>` page for more details.
 
-***************
 Class Reference
 ***************
 

user_guide_src/source/installation/index.rst

@@ -2,14 +2,31 @@
 Installation
 ############
 
-There are a number of ways to download, install and run a
+CodeIgniter4 can be installed in a number of different ways: manually,
+using `Composer <https://getcomposer.org>`_, or using
+`Git <https://git-scm.com/>`_. If you are not sure which is most
+appropriate for you, read the introduction for
+each technique, and consider their pros and cons.
+
+Once installed, there are several ways to run a
 CodeIgniter4 app. Read on :)
 
 .. toctree::
     :titlesonly:
 
-    downloads
-    installing
+    installing_manual
+    installing_composer
+    installing_git
     running
     upgrading
     troubleshooting
+    repositories
+
+However you choose to install and run CodeIgniter4, the 
+`user guide <https://codeigniter4.github.io/userguide/>`_ is accessible online.
+
+.. note:: Before using CodeIgniter 4, make sure that your server meets the
+          :doc:`requirements </intro/requirements>`, in particular the PHP
+          version and the PHP extensions that are needed.
+          You may find that you have to uncomment the ``php.ini`` "extension"
+          lines to enable "curl" and "intl", for instance.

user_guide_src/source/installation/installing_composer.rst

@@ -0,0 +1,191 @@
+Composer Installation
+###############################################################################
+
+Composer can be used in several ways to install CodeIgniter4 on your system.
+
+The first two techniques describe creating a skeleton project
+using CodeIgniter4, that you would then use as the base for a new webapp.
+The third technique described below lets you add CodeIgniter4 to an existing
+webapp, 
+
+**Note**: if you are using a Git repository to store your code, or for
+collaboration with others, then the ``vendor`` folder would normally
+be "git ignored". In such a case, you will need to do a ``composer udpate``
+when you clone the repository to a new system.
+
+App Starter
+============================================================
+
+The `CodeIgniter 4 app starter <https://github.com/codeigniter4/appstarter>`_ 
+repository holds a skeleton application, with a composer dependency on
+the latest released version of the framework.
+
+This installation technique would suit a developer who wishes to start
+a new CodeIgniter4 based project.
+
+Installation
+-------------------------------------------------------
+
+In the folder above your project root::
+
+    composer create-project codeigniter4/appstarter -s alpha
+
+Setup
+-------------------------------------------------------
+
+The command above will create an "appstarter" folder.
+Feel free to rename that for your project.
+
+Upgrading
+-------------------------------------------------------
+
+Whenever there is a new release, then from the command line in your project root::
+
+    composer update 
+
+Read the upgrade instructions, and check designated  ``app/Config`` folders for affected changes.
+
+Pros
+-------------------------------------------------------
+
+Simple installation; easy to update
+
+Cons
+-------------------------------------------------------
+
+You still need to check for ``app/Config`` changes after updating
+
+Structure
+-------------------------------------------------------
+
+Folders in your project after setup:
+
+- app, public, writable 
+- vendor/codeigniter4/framework/system
+- vendor/codeigniter4/codeigniter4/app & public (compare with yours after updating)
+
+Dev Starter
+============================================================
+
+Installation
+-------------------------------------------------------
+
+The `CodeIgniter 4 dev starter <https://github.com/codeigniter4/devstarter>`_ 
+repository holds a skeleton application, just like the appstarter above,
+but with a composer dependency on
+the develop branch (unreleased) of the framework.
+It can be composer-installed as described here.
+
+This installation technique would suit a developer who wishes to start
+a new CodeIgniter4 based project, and who is willing to live with the
+latest unreleased changes, which may be unstable.
+
+The `development user guide <https://codeigniter4.github.io/CodeIgniter4/>`_ is accessible online.
+Note that this differs from the released user guide, and will pertain to the
+develop branch explicitly.
+
+In the folder above your project root::
+
+    composer create-project codeigniter4/devstarter -s dev
+
+Setup
+-------------------------------------------------------
+
+The command above will create an "devstarter" folder.
+Feel free to rename that for your project.
+
+Upgrading
+-------------------------------------------------------
+
+``composer update`` whenever you are ready for the latest changes.
+
+Check the changelog to see if any recent changes affect your app,
+bearing in mind that the most recent changes may not have made it
+into the changelog!
+
+Pros
+-------------------------------------------------------
+
+Simple installation; easy to update; bleeding edge version
+
+Cons
+-------------------------------------------------------
+
+This is not guaranteed to be stable; the onus is on you to upgrade.
+You still need to check for ``app/Config`` changes after updating.
+
+Structure
+-------------------------------------------------------
+
+Folders in your project after setup:
+
+- app, public, writable 
+- vendor/codeigniter4/codeigniter4/system
+- vendor/codeigniter4/codeigniter4/app & public (compare with yours after updating)
+
+Adding CodeIgniter4 to an Existing Project
+============================================================
+
+The same `CodeIgniter 4 framework <https://github.com/codeigniter4/framework>`_ 
+repository described in "Manual Installation" can also be added to an
+existing project using Composer.
+
+Develop your app inside the ``app`` folder, and the ``public`` folder 
+will be your document root. 
+
+In your project root::
+
+    composer require codeigniter4/framework @alpha
+
+Setup
+-------------------------------------------------------
+
+Copy the app, public and writable folders from ``vendor/codeigniter4/framework`` 
+to your project root
+
+Copy the ``env``, ``phpunit.xml.dist`` and ``spark`` files, from
+``vendor/codeigniter4/framework`` to your project root
+
+You will have to adjust paths to refer to vendor/codeigniter/framework``, 
+- the $systemDirectory variable in ``app/Config/Paths.php``
+
+Upgrading
+-------------------------------------------------------
+
+Whenever there is a new release, then from the command line in your project root::
+
+    composer update 
+
+Read the upgrade instructions, and check designated 
+``app/Config`` folders for affected changes.
+
+Pros
+-------------------------------------------------------
+
+Relatively simple installation; easy to update
+
+Cons
+-------------------------------------------------------
+
+You still need to check for ``app/Config`` changes after updating
+
+Structure
+-------------------------------------------------------
+
+Folders in your project after setup:
+
+- app, public, writable 
+- vendor/codeigniter4/framework/system
+
+
+Translations Installation
+============================================================
+
+If you want to take advantage of the system message translations,
+they can be added to your project in a similar fashion. 
+
+From the command line inside your project root::
+
+    composer require codeigniter4/translations
+
+These will be updated along with the framework whenever you do a ``composer update``.

user_guide_src/source/installation/installing_git.rst

@@ -0,0 +1,83 @@
+Git Installation
+###############################################################################
+
+This would *not* be suitable for app development, but *is* suitable
+for contributing to the framework.
+
+Installation
+-------------------------------------------------------
+
+Install the latest version of the codebase by
+
+- forking the `codebase  <https://github.com/codeigniter4/CodeIgniter4>`_ to your github account
+- cloning **your** forked repository locally
+
+Setup
+-------------------------------------------------------
+
+The command above will create a "CodeIgniter4" folder.
+Feel free to rename that as you see fit.
+
+You will want to setup a remote repository alias, so you can synchronize
+your repository with the main one::
+
+    git remote add upstream https://github.com/codeigniter4/CodeIgniter4.git
+
+Copy the provided ``env`` file to ``.env``, and use that for your git-ignored configuration settings,
+
+Copy the provided ``phpunit.xml.dist`` to ``phpunit.xml`` and tailor it as needed,
+if you want custom unit testing for the framework.
+
+Upgrading
+-------------------------------------------------------
+
+Update your code anytime::
+
+    git checkout develop
+    git pull upstream develop
+    git push origin develop
+
+Merge conflicts may arise when you pull from "upstream". 
+You will need to resolve them locally.
+
+Pros
+-------------------------------------------------------
+
+- You have the latest version of the codebase (unreleased)
+- You can propose contributions to the framework, by creating a 
+    feature branch and submitting a pull request for it to the main repo
+- a pre-commit hook is installed for your repo, that binds it to the
+    coding-standard we use
+
+Cons
+-------------------------------------------------------
+
+You need to resolve merge conflicts when you synch with the repo.
+
+You would not use this technique for app development.
+
+Structure
+-------------------------------------------------------
+
+Folders in your project after setup:
+
+- app, public, system, tests, user_guide_src, writable
+
+
+Translations Installation
+============================================================
+
+If you wish to contribute to the system message translations,
+then fork and clone the `translations repository
+<https://github.com/codeigniter4/translations>`_ separately from the codebase. 
+These are two independent repositories!
+
+
+Coding Standards Installation
+============================================================
+
+This is bound and installed automatically as part of the
+codebase installation.
+
+If you wish to use it inside your project too,
+``composer require codeigniter4/translations @alpha``

user_guide_src/source/installation/installing_manual.rst

@@ -0,0 +1,63 @@
+Manual Installation
+###############################################################################
+
+The `CodeIgniter 4 framework <https://github.com/codeigniter4/framework>`_ 
+repository holds the released versions of the framework.
+It is intended for developers who do not wish to use Composer.
+
+Develop your app inside the ``app`` folder, and the ``public`` folder 
+will be your public-facing document root.  Do not change anything inside the ``system``
+folder!
+
+**Note**: This is the installation technique closest to that described 
+for `CodeIgniter 3 <https://www.codeigniter.com/user_guide/installation/index.html>`_.
+
+Installation
+============================================================
+
+Download the `latest version <https://github.com/CodeIgniter4/codeigniter4/releases/latest>`_,
+and extract it to become your project root.
+
+Setup
+-------------------------------------------------------
+
+None
+
+Upgrading
+-------------------------------------------------------
+
+Download a new copy of the framework, and then follow the upgrade
+instructions in the release notice or changelog to merge that with your project.
+
+Typically, you replace the ``system`` folder, and check designated
+``app/Config`` folders for affected changes.
+
+Pros
+-------------------------------------------------------
+
+Download and run
+
+Cons
+-------------------------------------------------------
+
+You are responsible for merge conflicts when updating
+
+Structure
+-------------------------------------------------------
+
+Folders in your project after setup:
+app, public, system, writable 
+
+
+Translations Installation
+============================================================
+
+If you want to take advantage of the system message translations,
+they can be added to your project in a similar fashion.
+
+Download the `latest version of them <https://github.com/codeigniter4/translations/releases/latest>`_.
+Extract the downloaded zip, and copy the ``Language`` folder contents in it
+to your ``PROJECT_ROOT/app/Languages`` folder.
+
+This would need to be repeated to incorporate any updates
+to the translations.