<commit_before># Ilios 3 Upgrade Notes

These instructions pertain to upgrades within the "Version 3"-branch of Ilios.

For upgrade instructions from Ilios 2 see the "Upgrading Ilios 2.x to Ilios 3" section below.

## General steps

_NOTE:_ The steps below assume that file ownership of the deployed codebase belongs to the user account that
 runs your web server. Therefore, commands that affect the file system should also be performed as this user.
 In this example, this account is `apache`, but it could also be `www`, `www-data`, or something else - depending on the
 flavour of Linux (or alternate operating system) running on your server.

1. Back up your database. _Always._

2. Upgrade you codebase via composer.

 ```bash
cd YOUR_ILIOS_APPLICATION_ROOT
sudo -u apache composer install --no-dev
```

3. Execute any pending database migrations.

 ```bash
cd YOUR_ILIOS_APPLICATION_ROOT
sudo -u apache bin/console doctrine:migrations:migrate --env=prod --append --no-interaction
```

4. Clear your application cache.

 ```bash
cd YOUR_ILIOS_APPLICATION_ROOT
sudo -u apache bin/console cache:clear --env=prod
```

## Version-specific steps

### Upgrading to Ilios 3.12.0

This version adds the "AAMC Resource Type" as a new entity to the application.

Please execute the following console command _after_ running migrations 
in order to load the default resource-types data set.

```bash
cd YOUR_ILIOS_APPLICATION_ROOT
sudo -u apache bin/console doctrine:fixtures:load --env=prod --fixtures=src/Ilios/CoreBundle/DataFixtures/ORM/LoadAamcResourceTypeData.php
```

# Upgrading Ilios 2.x to Ilios 3

As Ilios 3 uses an entirely different codebase from Ilios 2.x, only the database needs to be updated when upgrading to version 3 from version 2.x.  With the exception of the folder that contains your Ilios learning materials, which should be backed-up before performing this process, the new Ilios 3 codebase entirely replaces the Ilios 2.x codebase, so you should follow the instructions in [INSTALL.md](https://github.com/ilios/ilios/blob/master/INSTALL.md) to bring the codebase up-to-date.

###*NOTE:* These steps cover upgrading your Ilios database from an Ilios *2.4.8* installation ONLY.###

####*If you are running a version of Ilios earlier than v2.4.8 and would like to upgrade to Ilios 3, you MUST upgrade your Ilios software to release version 2.4.8 BEFORE running these steps! If you do not update to version 2.4.8 before upgrading, your database schema will be incorrect and unusable!*####

Before upgrading your system, you will want to bring down your webserver or redirect users to some kind of 503 maintenance page, so that they will not be making changes to the Ilios database while the upgrade is in-process. We recommend trying this on a development server to test everything out before trying to do it on your production machine.

To upgrade from an already-existing Ilios 2.4.8 installation, perform the following steps in order:

### Steps:

1. Backup all of your learning materials or move them to a location where they will be accessible by the new Ilios 3 installation. *WARNING:* If your learning materials are stored in the default location, be careful to not accidentally delete them when you change your codebase.
2. Backup your current database completely, and do not forget to add the '-R' or'--routines' flags to ensure that your stored procedures and triggers are included in the back up. The command would probably look something like this:

 ```bash
mysqldump -u YOUR_ILIOS_DATABASE_USERNAME -h YOUR_ILIOS_HOSTNAME -R -p YOUR_ILIOS_DATABASE_NAME -r YOUR_DATABASE_BACKUP_FILENAME.sql
```

3. Backup your current database completely! (Yes, this was just mentioned, but it's extremely important that you do not run this update on your production database without a backup!) 
4. Check your current Ilios installation's 'version.php' file to verify that you are currently running version 2.4.8 of the Ilios software.  If you are not running version *2.4.8* specifically , you will need to upgrade to 2.4.8 *BEFORE* continuing with these steps!
5. Checkout the most current release of the Ilios 3 codebase from https://github.com/ilios/ilios/releases (using '/web/ilios3/ilios' for this example)
6. In the newly-checked out directory, navigate to the 'app/Resources' folder where you will find the [updateSchemaFromIlios2toIlios3.sql](https://github.com/ilios/ilios/blob/master/app/Resources/updateSchemaFromIlios2toIlios3.sql) file.
7. Backup your current database completely! (<= That's the 3rd time we've said it! It's probably pretty important!)
8. Apply the sql changes from updateSchemaFromIlios2toIlios3.sql to your database by using the mysql command line client as follows:
<commit_msg>moved the --append flag to the right place.<commit_after># Ilios 3 Upgrade Notes

These instructions pertain to upgrades within the "Version 3"-branch of Ilios.

For upgrade instructions from Ilios 2 see the "Upgrading Ilios 2.x to Ilios 3" section below.

## General steps

_NOTE:_ The steps below assume that file ownership of the deployed codebase belongs to the user account that
 runs your web server. Therefore, commands that affect the file system should also be performed as this user.
 In this example, this account is `apache`, but it could also be `www`, `www-data`, or something else - depending on the
 flavour of Linux (or alternate operating system) running on your server.

1. Back up your database. _Always._

2. Upgrade you codebase via composer.

 ```bash
cd YOUR_ILIOS_APPLICATION_ROOT
sudo -u apache composer install --no-dev
```

3. Execute any pending database migrations.

 ```bash
cd YOUR_ILIOS_APPLICATION_ROOT
sudo -u apache bin/console doctrine:migrations:migrate --env=prod --no-interaction
```

4. Clear your application cache.

 ```bash
cd YOUR_ILIOS_APPLICATION_ROOT
sudo -u apache bin/console cache:clear --env=prod
```

## Version-specific steps

### Upgrading to Ilios 3.12.0

This version adds the "AAMC Resource Type" as a new entity to the application.

Please execute the following console command _after_ running migrations 
in order to load the default resource-types data set.

```bash
cd YOUR_ILIOS_APPLICATION_ROOT
sudo -u apache bin/console doctrine:fixtures:load --env=prod --append --fixtures=src/Ilios/CoreBundle/DataFixtures/ORM/LoadAamcResourceTypeData.php
```

# Upgrading Ilios 2.x to Ilios 3

As Ilios 3 uses an entirely different codebase from Ilios 2.x, only the database needs to be updated when upgrading to version 3 from version 2.x.  With the exception of the folder that contains your Ilios learning materials, which should be backed-up before performing this process, the new Ilios 3 codebase entirely replaces the Ilios 2.x codebase, so you should follow the instructions in [INSTALL.md](https://github.com/ilios/ilios/blob/master/INSTALL.md) to bring the codebase up-to-date.

###*NOTE:* These steps cover upgrading your Ilios database from an Ilios *2.4.8* installation ONLY.###

####*If you are running a version of Ilios earlier than v2.4.8 and would like to upgrade to Ilios 3, you MUST upgrade your Ilios software to release version 2.4.8 BEFORE running these steps! If you do not update to version 2.4.8 before upgrading, your database schema will be incorrect and unusable!*####

Before upgrading your system, you will want to bring down your webserver or redirect users to some kind of 503 maintenance page, so that they will not be making changes to the Ilios database while the upgrade is in-process. We recommend trying this on a development server to test everything out before trying to do it on your production machine.

To upgrade from an already-existing Ilios 2.4.8 installation, perform the following steps in order:

### Steps:

1. Backup all of your learning materials or move them to a location where they will be accessible by the new Ilios 3 installation. *WARNING:* If your learning materials are stored in the default location, be careful to not accidentally delete them when you change your codebase.
2. Backup your current database completely, and do not forget to add the '-R' or'--routines' flags to ensure that your stored procedures and triggers are included in the back up. The command would probably look something like this:

 ```bash
mysqldump -u YOUR_ILIOS_DATABASE_USERNAME -h YOUR_ILIOS_HOSTNAME -R -p YOUR_ILIOS_DATABASE_NAME -r YOUR_DATABASE_BACKUP_FILENAME.sql
```

3. Backup your current database completely! (Yes, this was just mentioned, but it's extremely important that you do not run this update on your production database without a backup!) 
4. Check your current Ilios installation's 'version.php' file to verify that you are currently running version 2.4.8 of the Ilios software.  If you are not running version *2.4.8* specifically , you will need to upgrade to 2.4.8 *BEFORE* continuing with these steps!
5. Checkout the most current release of the Ilios 3 codebase from https://github.com/ilios/ilios/releases (using '/web/ilios3/ilios' for this example)
6. In the newly-checked out directory, navigate to the 'app/Resources' folder where you will find the [updateSchemaFromIlios2toIlios3.sql](https://github.com/ilios/ilios/blob/master/app/Resources/updateSchemaFromIlios2toIlios3.sql) file.
7. Backup your current database completely! (<= That's the 3rd time we've said it! It's probably pretty important!)
8. Apply the sql changes from updateSchemaFromIlios2toIlios3.sql to your database by using the mysql command line client as follows:

{'fraction_non_alphanumeric': 0.06417281348788198, 'fraction_numerical': 0.014120126448893572, 'mean_word_length': 4.579659024103469, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 3, 'https://': 6, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '162303', 'n_tokens_mistral': 2740, 'n_tokens_neox': 2589, 'n_words': 1317}