Merge branch 'add-docs-app-unintall' into 'master'

Improve documentation for app removal

See merge request allianceauth/allianceauth!1508

.gitlab-ci.yml

@@ -25,7 +25,7 @@ before_script:
 pre-commit-check:
   <<: *only-default
   stage: pre-commit
-  image: python:3.8-bullseye
+  image: python:3.10-bullseye
   variables:
     PRE_COMMIT_HOME: ${CI_PROJECT_DIR}/.cache/pre-commit
   cache:

docs/maintenance/apps.md

@@ -1,15 +1,95 @@
 # App Maintenance
 
-## Adding and Removing Apps
+## Adding Apps
 
 Your auth project is just a regular Django project - you can add in [other Django apps](https://djangopackages.org/) as desired. Most come with dedicated setup guides, but here is the general procedure:
 
 1. add `'appname',` to your `INSTALLED_APPS` setting in `local.py`
 2. run `python manage.py migrate`
-3. run `python manage.py collectstatic`
+3. run `python manage.py collectstatic --noinput`
 4. restart AA with `supervisorctl restart myauth:`
 
-If you ever want to remove an app, you should first clear it from the database to avoid dangling foreign keys: `python manage.py migrate appname zero`. Then you can remove it from your auth project's `INSTALLED_APPS` list.
+## Removing Apps
+
+The following instructions will explain how you can remove an app properly fom your Alliance Auth installation.
+
+```eval_rst
+.. note::
+    We recommend following these instructions to avoid dangling foreign keys or orphaned Python packages on your system, which might cause conflicts with other apps down the road.
+
+```
+
+### Step 1 - Removing database tables
+
+First, we want to remove the app related tables from the database.
+
+#### Automatic table removal
+
+Let's first try the automatic approach by running the following command:
+
+```sh
+python manage.py migrate appname zero
+```
+
+If that worked you'll get a confirmation message.
+
+If that did not work and you got error messages, you will need to remove the tables manually. This is pretty common btw, because many apps use sophisticated table setups, which can not be removed automatically by Django.
+
+#### Manual table removal
+
+First, tell Django that these migrations are no longer in effect (note the additional `--fake`):
+
+```sh
+python manage.py migrate appname zero --fake
+```
+
+Then, open the mysql tool and connect to your Alliance Auth database:
+
+```sh
+sudo mysql -u root
+use alliance_auth;
+```
+
+Next disable foreign key check. This makes it much easier to drop tables in any order.
+
+```sh
+SET FOREIGN_KEY_CHECKS=0;
+```
+
+Then get a list of all tables. All tables belonging to the app in question will start with `appname_`.
+
+```sh
+show tables;
+```
+
+Now, drop the tables from the app one by one like so:
+
+```sh
+drop table appname_model_1;
+drop table appname_model_2;
+...
+```
+
+And finally, but very importantly, re-enable foreign key checks again and then exit:
+
+```sh
+SET FOREIGN_KEY_CHECKS=1;
+exit;
+```
+
+### Step 2 - Remove the app from Alliance Auth
+
+Once the tables have been removed, you you can remove the app from Alliance Auth. This is done by removing the applabel from the `INSTALLED_APPS` list in your local settings file.
+
+### Step 3 - Remove the Python package
+
+Finally, we want to remove the app's Python package. For that run the following command:
+
+```sh
+pip uninstall app-package-name
+```
+
+Congrats, you have now removed this app from your Alliance Auth installation.
 
 ## Permission Cleanup
 

setup.cfg

@@ -7,7 +7,7 @@ long_description_content_type = text/markdown
 author = Alliance Auth
 author_email = adarnof@gmail.com
 license = GPL-2.0
-license_file = LICENSE
+license_files = LICENSE
 classifiers =
     Environment :: Web Environment
     Framework :: Django