Improve comments, naming and descriptions

locales/en.json

@@ -274,8 +274,8 @@
     "migration_description_0004_php5_to_php7_pools": "Reconfigure the PHP pools to use PHP 7 instead of 5",
     "migration_description_0005_postgresql_9p4_to_9p6": "Migrate databases from postgresql 9.4 to 9.6",
     "migration_description_0006_sync_admin_and_root_passwords": "Synchronize admin and root passwords",
-    "migration_description_0006_manage_sshd_config": "Manage SSH conf in a better way",
+    "migration_description_0006_ssh_conf_managed_by_yunohost_step1": "Let the SSH configuration be managed by YunoHost (step 1, automatic)",
-    "migration_description_0007_reset_sshd_config": "Reset SSH conf to the YunoHost default conf",
+    "migration_description_0007_ssh_conf_managed_by_yunohost_step2": "Let the SSH configuration be managed by YunoHost (step 2, manual)",
     "migration_0003_backward_impossible": "The stretch migration cannot be reverted.",
     "migration_0003_start": "Starting migration to Stretch. The logs will be available in {logfile}.",
     "migration_0003_patching_sources_list": "Patching the sources.lists ...",

src/yunohost/data_migrations/0006_ssh_conf_managed_by_yunohost_step1.py

@@ -20,14 +20,18 @@ SSHD_CONF = '/etc/ssh/sshd_config'
 
 class MyMigration(Migration):
     """
-    This is an automatic migration, that ensure SSH conf is managed by YunoHost
+    This is the first step of a couple of migrations that ensure SSH conf is
-    (even if the "from_script" flag is present)
+    managed by YunoHost (even if the "from_script" flag is present, which was
+    previously preventing it from being managed by YunoHost)
+    
+    The goal of this first (automatic) migration is to make sure that the
+    sshd_config is managed by the regen-conf mechanism.
 
     If the from_script flag exists, then we keep the current SSH conf such that it
     will appear as "manually modified" to the regenconf.
     
-    The admin can then choose in the next migration (manual, thi time) wether or 
+    In step 2 (manual), the admin will be able to choose wether or not to actually
-    not to actually use the recommended configuration.
+    use the recommended configuration, with an appropriate disclaimer.
     """
 
     def migrate(self):

src/yunohost/data_migrations/0007_ssh_conf_managed_by_yunohost_step2.py

@@ -13,7 +13,18 @@ logger = getActionLogger('yunohost.migration')
 
 
 class MyMigration(Migration):
-    "Reset SSH conf to the YunoHost one"
+    """
+    In this second step, the admin is asked if it's okay to use
+    the recommended SSH configuration - which also implies
+    disabling deprecated DSA key.
+
+    This has important implications in the way the user may connect
+    to its server (key change, and a spooky warning might be given
+    by SSH later)
+
+    A disclaimer explaining the various things to be aware of is
+    shown - and the user may also choose to skip this migration.
+    """
 
     def migrate(self):
         settings_set("service.ssh._deprecated_dsa_hostkey", False)
@@ -26,7 +37,10 @@ class MyMigration(Migration):
     @property
     def mode(self):
 
-        # Avoid having a super long disclaimer
+        # If the conf is already up to date
+        # and no DSA key is used, then we're good to go
+        # and the migration can be done automatically
+        # (basically nothing shall change)
         ynh_hash = _get_conf_hashes('ssh')
         if '/etc/ssh/sshd_config' in ynh_hash:
             ynh_hash = ynh_hash['/etc/ssh/sshd_config']
@@ -43,7 +57,8 @@ class MyMigration(Migration):
         if self.mode == "auto":
             return None
 
-        # Detect major risk to migrate to the new configuration
+        # Detect key things to be aware of before enabling the
+        # recommended configuration
         dsa = False
         ports = []
         root_login = []