Restructured documents and tried to remove duplicated entries about git and drush

- Git can drush command live in separate documents to reduce duplication.
- Removed all mention about Norstore, we now longer have that infrastructure.
- Tried to give the documentation better structure and easier to read as
a single document instead of badly connected stand alone documents with with
duplicated and outdated paragraphs.

Author: steinmb

doc/contrib.md

@@ -1,20 +1,19 @@
-# Contribute changes and improvements
-Before starting make sure you [reset your local installation](reset.md).
+# Make changes to ELMCIP
 
-## Make changes to existing configuration
-You are now ready to make changes your local installation. Peform your changes through Drupal UI for views, fields and other changes.
+Before starting make sure you first [reset your local installation](reset.md) your local installation.
 
-## Work with the features module from drush
-These changes will cause the feature module to get overridden. Run `bin/site-drush fl` to confirm this. Export the changes from the database to the file system 'bin/site-drush fu <feature name>'. 
+## Make a change to the existing site
 
-For more information, read our [features module document](features.md). You should now have moved the changes you did to the Drupal database and to the file system.
+Make the wanted changes through the Drupal UI, example a view, alter fields help texts and so on. The changes are stored in your database and you need to export them by using the Features module.
 
-## work with git
+These changes will cause the feature module to get overridden. Confirm your changes by running.
 
-    git checkout -b issue_number
-This create your own branch out from the master branch that you can safely work on. Do your changes and add them to git. check out [our brief git section](../README.md).
+    bin/site-drush fl
+    
+Export the changes from the database to the file system 
 
-These changes need to pushed to github before test.elmcip.net or other developers can test them.
+    bin/site-drush fu <feature name>
 
-If the issue then is confirmed working and can be safely applied to production will the code make it into the master branch. Snapshots of the master branch is what in the end makes the production branch.
+For more information about how to use the Features module, read our [Features document](features.md).
 
+You now have exported your changes to the file system and these need to added with Git and pushed upstream allowing test.elmcip.net or other developers to test the changes. To learn more about how to work with git read the [git documentation](git.md).

doc/features.md

@@ -2,7 +2,7 @@
 
 The [Features](https://www.drupal.org/project/features) module allow us to export and import configuration that else would be locked in the database together with the content like nodes, taxonomy terms and so on.
 
-The easiest way of interacting with is by using the command line toool [Drush](https://www.drush.org). There is a UI for it inside Drupal, feel free to explore it (`/admin/structure/features`), it will not be documented here.
+The easiest way of interacting with is by using the command line tool [Drush](https://www.drush.org). There is a UI for it inside Drupal, feel free to explore it (`/admin/structure/features`), it will not be documented here. An excellent starting point to learn more about Features is the official [module documentation](https://www.drupal.org/node/580026).
 
 ## List all feature modules and their current state.
 

doc/git.md

@@ -1,5 +1,6 @@
-# how to use Git
-This document does not try to cover all you need to know about [Git](https://git-scm.com) and version control systems (VCS) but should get you started working with git.
+# How to use Git
+
+This document does not cover all you need to know about [Git](https://git-scm.com) and version control systems (VCS) in general but it should be enought to get you started. To learn more buy a book or read online resources like [Pro Git](https://git-scm.com/book) and [Git Immersion](https://gitimmersion.com).
 
 ## Best practise in a git workflow
 
@@ -21,7 +22,7 @@ See differences between the orginal state and your installation.
 
     git diff
 
-If you whant to see the changes in a single file use `git diff <filename>`
+If you want to see the changes in a single file use `git diff <filename>`
 
 Add files to be comitted (staging).
 
@@ -39,3 +40,13 @@ Push your changes to github
 
     git push
 
+
+## Getting rid of unattended local changes
+
+If your system is not clean.
+
+    git reset --hard` 
+    
+Remove all local changes to files. Make sure you use this with care and you fully understand what you do. This do not remove files that are unknown (untracked) to Git. 
+
+Run `git status` again to verify that your system are now really is clean. 

doc/install.md

@@ -1,29 +1,52 @@
-# ELMCIP Installation
+# Install ELMCIP
 
-## Requirements
+This is something you only have to do on a new machine or perhaps you want to have multiple local instances of ELMCIP running.
 
-* A working installation of Apache or another web server, MySQL/MariaDB and PHP 7.0 or newer.
-* A empty database named `elmcip`.
-* Database user name `elmcip` with full access to the elmcip database.
-* Set password for user elmcip to `elmcip`.
-* Git installed and configured.
-* Drush installed (https://github.com/drush-ops/drush).
-* A working ssh connection to Norstore application and database server. Auth should not be password based but by using your private/public SHA -key.
-* You must be in your local elmcip directory.
+## Software requirements
+
+* Webserver/service like [Apache](https://httpd.apache.org) or another web server.
+* MySQL or equivalent like MariaDB.
+* PHP 7.2.x or newer.
+* [Git](https://git-scm.com) installed. Verify by running `git --version`
+* [Composer](https://getcomposer.org) installed. Verify by running `composer --version`
+
+## Required configurations
+
+1. Create a empty Mysql database. `elmcip` is a natural name to choice with a database user name with full access to the elmcip database. In test env. we normally also name this `elmcip`.
+1. Make a directory where your ELMCIP installation can be installed and make your webserver `DocumentRoot` `<directory you just created>/elmcip/drupal`.
 
 ## Installation
 
-Get main repository and any custom modules. Run this in your web server document root.
+1. To get the ELMCIP, Drupal core and all third party and custom modules you need to clone the `elmcip` repository.
 
-    git clone git@github.com:elmcip/elmcip.git
-    cd elmcip
+    git clone git@github.com:elmcip/elmcip.git elmcip
 
-Get drupal core and all 3-part modules:
+Your webserver DocumentRoot is elmcip/drupal. Make sure your default or vhost point to this directory.
+
+1. The elmcip use git modules and to get Drupal you need to update the submodules.
 
     git submodule update --init
 
-Initialize the new site:
+1. Initialize the new site:
+
+    bin/site-init
+
+You should now have a functional copy of ELMCIP with everything except for images videos. If you locally need them is there a module named 'Stage File Proxy' that can pull on demand images directly from production.
+
+## Troubleshooting
+
+### Problems importing database
+If you are unable to restore (import) the database your database server resource might be too low. Try upping this by adding `max_allowed_packet = 100M` to your database configuration. Often called my.cnf or server.cnf and then restart the database service.
+
+### Problem loading large Drupal pages
+
+Example if you load pages like '/admin/people/permissions' and your are unable to change and save configuration. Please check your apache or php-error log. You might then see warnings like:
+
+        PHP Warning:  Unknown: Input variables exceeded 1000. To increase the limit change max_input_vars in php.ini. in Unknown on line 0, referer: http://elmcip.local/admin/people/permissions
+
+To fix this you need to change the site php.ini. Not sure where your php.ini files are run `php --ini` in the command line. Search for this line with `max_input_vars` and change it to something like this. Make sure you also uncomment the line.
 
-    bin/site-init <norstore username>
+        ; How many GET/POST/COOKIE input variables may be accepted
+        max_input_vars = 1500
 
-You should now have a fully functional site, with all content, except files and images. [Reset and upgrade local installation](reset.md) explain how to get images and media to your local site if needed.
+Save and restart your PHP service.

doc/offline.md

@@ -1,12 +1,11 @@
-# ELMCIP Offline mode
+# ELMCIP offline mode
 
- This does attempt to do any network connections.
+ Allow you to work locally without any network connections, aka flight mode.
 
-  * Enable you to work while traveling.
-  * Speeds up working with ELMCIP.
-  * Allow you to reset while traveling.
+  * Work while traveling.
+  * Speeds up your local work flow without needing to create new database copies.
 
-## What does this mean
+## What does all this mean
 
 Any changes to the development branch (master) will never pulled from github. No attempt to sync with Norstore getting files and databse. Are your local copy more and less up to date is this not a big problem.
 
@@ -16,33 +15,31 @@ Any changes to the development branch (master) will never pulled from github. No
 
 ### Getting clean 
 
-Make sure you don't have any local changes applied to your file system before continuing. GIT will tell you if you have.
+Make sure you don't have any local changes applied to your file system before continuing. Git will tell you if you so have.
 
     git status
- 
-If your system is clean, run: `git reset --hard`. This remove any local changes to files. Note this will not remove files GIT do not know. Rerun `git status` to verify that your system are really clean. Want to learn more about GIt, try reading [Pro Git](http://progit.org) or any git book available.
+
+For more read our [Git documentation](git.md)
 
 ### Reset
 
 This reset you back to production and grabbing the latest local database copy.
 
     bin/offline_reset2production
      
-## Going to Ludicrous Speed
+## Optimising your local work flow
 
-This remove all cache tables, search index and other from system, greatly reducing time spent restoring database and working with in general.
+Written to speed up your local workflow though as usual you need to know what your are doing and is normally only used by more experienced users. This utility removes all database caching tables not needed. This greatly reduces the size and time spent restoring the database.
 
     bin/make-fast
 
-Changes are made to the running database but also leave a uncompressed copy of the optimized databse in the `site` directory.
+It perform these changes your running database but also create a uncompressed copy of the optimized database in `site/latest.elmcip.sql`.
 
-### Using optimized database copy
+To use this datbase copy run `offline_reset2production` with the `fast` option.
 
     bin/offline_reset2production fast
 
-### How fast is fast
-
- Benchmarks done when your local site is warm, aka there was no new files to sync. Meaning the online sync might be slower for your system.
+### How fast is make-fast
 
 * online reset (bin/reset2production): 7m
 * Offline (bin/offline_reset2production): 6m 48sec

doc/reset.md

@@ -1,36 +1,24 @@
-# Reset local installation to production
-It will take a while the very first time you run it. You minimum need a copy of the database. Syncing media files with production is optional and not really needed to work with your local copy. There is also a offline mode allowing you to work even with no network connection. Read about [working offline](offline.md), note that running offline mode also have a time saver option restoring the database.
-
-    bin/reset2production <norestore username> <all | none>
-    
-`reset2production` takes two optional parameters. Omit these to use your local username and skip large files during sync.
+# Reset a local installation to production state
 
-1. Your norstore username.
-2. Sync modes: `all` sync all files and takes a long time to run. `none` transfare no files, only the needed database.
+It will take a while the very first time you run it. You minimum need a copy of the database. Syncing media files with production is optional and not really needed to work with your local copy. There is also a offline mode allowing you to work even with no network connection. Read about [working offline](offline.md), note that running offline mode also have a time saver option restoring the database.
 
-Typical use is:
+    bin/reset2production
 
-  bin/reset2production username none
+## Make sure your local installation is clean
 
-## Get clean
 Make sure you don't have any local changes applied to your file system before continuing. GIT will tell you if you have.
 
     git status
 
 If your system is not clean, run: `git reset --hard`. This remove any local changes to files. Note this will not remove files unknown to GIT. Rerun `git status` to verify that your system are really clean. Want to learn more about GIT, try reading [Pro Git](http://progit.org) or any git book available.
 
-## Grab a copy of production (elmcip.net)
+## Get a copy of the production database
 This will automagically update your local installation. It grabs copy of the database and any if wanted newly added files added since last time you did this.
 
-    bin/reset2production <norestore username>
+    bin/reset2production
 
 You are now identical to the production site.
 
-### Problem syncing with production
-
-* Might could be caused by your network connection. Norstore firewalls only open up certain IP addressed. UiB IP-range is one of the allowed ranges that can do ssh into elmcip1 and elmcip2. By using a VPN connection to UiB will your machine use the allowed IP-range. This also work if you are traveling and hacking out from your favorite cafe.
-* If your local username and your norstore are not identical make sure you are running `bin/reset2production <norestore username>`.
-* Tired of typing passwords? Adding your ssh public key to your norstore home area remove this need. 
 
 ## Upgrade from production to development (master)
 

doc/test_verify.md

@@ -1,7 +1,9 @@
-# Test and verify an issue
-Before continuing [reset](reset.md) your local installation.
+# How to locally test and verify a issue
+
+Before continuing make sure your have read and performed a [reset](reset.md) of your local installation.
 
 ## Test a issue
+
 This grab an existing issue and try upgrade and deploy the changes to your local installation. The general rule is that we use the issue number created by github. In this example we will test issue 666.
 
 #### Upgrade your site to test issue 666
@@ -11,29 +13,26 @@ This grab an existing issue and try upgrade and deploy the changes to your local
 Make sure your site turned up clean after the upgrade. If not, the issue is not OK and you should stop testing. It should look something like this:
 
     Name                        Feature                 Status    Version         State
-    Date Migration Example      date_migrate_example    Disabled  7.x-2.8
-    Development settings        development_settings    Enabled
     ELMCIP content types        elmcip_content_types    Enabled
     ELMCIP Views                elmcip_data_export      Enabled
     ELMCIP field instances      elmcip_field_instances  Enabled
     ELMCIP layout               elmcip_layout           Enabled
     ELMCIP permissions          elmcip_permissions      Enabled
-    Setup ELMCIP                elmcip_setup            Enabled
-    Features Tests              features_test           Disabled  7.x-2.3
-    Schema.org example: Event   schemaorg_event         Disabled  7.x-1.0-beta4
-    Schema.org example: Person  schemaorg_person        Disabled  7.x-1.0-beta4
-    Schema.org example: Recipe  schemaorg_recipe        Disabled  7.x-1.0-beta4
-    UUID Services Example       uuid_services_example   Disabled  7.x-1.0-alpha6
+    ELMCIP tests                elmcip_setup            Enabled
+    ...
 
 #### Login as user 1 without password
 
-    bin/site-drush uli -l elmcip.dev
+    bin/site-drush uli
 
 #### Enable all our development settings
 
-    bin/site-drush en development_settings
+    bin/site-drush en --yes development_settings
 
 Test the issue and if it is OK, change the status of it to `verified by community`.
 
-#### To chain commands for testing
-    bin/reset2production USERNAME; bin/site-upgrade issue_INSERT ISSUE NUMBER; bin/site-drush en -y development_settings ;     bin/site-drush uli
+#### Chain commands for quicker testing
+
+Depending on the speed of your computer this might allow you to refill your cup of your favorite brew while it run.
+
+    bin/offline_reset2production; bin/site-upgrade <issue_number>; bin/site-drush en --yes development_settings; bin/site-drush uli