From 1dc3bd91c944d3f68ad63f32b77d74888f5137c9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matja=C5=BE=20Horvat?= <matjaz.horvat@gmail.com>
Date: Thu, 1 Oct 2020 17:28:57 +0200
Subject: [PATCH] Bug 1668175: Document how permalink prefix works for projects
 with config files (#1691)

---
 docs/user/localizing-your-projects.rst        | 14 ++++++-----
 .../migrations/0011_rename_download_prefix.py | 23 +++++++++++++++++++
 pontoon/base/models.py                        |  6 +++--
 3 files changed, 35 insertions(+), 8 deletions(-)
 create mode 100644 pontoon/base/migrations/0011_rename_download_prefix.py

diff --git a/docs/user/localizing-your-projects.rst b/docs/user/localizing-your-projects.rst
index 27c86dc5b..835e7d575 100644
--- a/docs/user/localizing-your-projects.rst
+++ b/docs/user/localizing-your-projects.rst
@@ -30,7 +30,7 @@ Folder structure
 ----------------
 
 To let Pontoon discover your localizable files, you'll either need to specify
-paths in the `project config file`_ or strictly follow the file and folder
+paths in the `project configuration file`_ or strictly follow the file and folder
 structure as expected by Pontoon:
 
 #. Locale folders (including source locale) must be located at the same nesting
@@ -52,7 +52,7 @@ Incorrect pattern::
 
     locales/{locale_code}/path/to/file.{locale_code}.extension
 
-.. _project config file: https://moz-l10n-config.readthedocs.io/en/latest/fileformat.html
+.. _project configuration file: https://moz-l10n-config.readthedocs.io/en/latest/fileformat.html
 
 Adding a new project to Pontoon
 -------------------------------
@@ -68,14 +68,16 @@ following required fields:
 #. **Locales**: select at least one Localizable locale by clicking on it.
 #. **Repository URL**: enter your repository's SSH URL of the form
    ``git@github.com:user/repo.git``.
-#. **Download prefix**: used for manually downloading files. Select any
-   localizable file on GitHub, click ``Raw`` and replace locale code and the
-   following bits in the URL with {locale_code}.
+#. **Download prefix or path to TOML file**: a URL prefix for downloading localized files. For
+   GitHub repositories, select any localized file on GitHub, click ``Raw`` and
+   replace locale code and the following bits in the URL with ``{locale_code}``.
+   If you use one, you need to select the `project configuration file`_ instead
+   of a localized file.
 #. Click **SAVE PROJECT** at the bottom of the page.
 #. After the page reloads, click **SYNC** and wait for Pontoon to import
    strings. You can monitor the progress in the Sync log (``/sync/log/``).
 #. When the synchronization is finished, you should check the imported resources
-    and the entities. If everything went okay, you can proceed to the next step.
+   and the entities. If everything went okay, you can proceed to the next step.
 #. Go to the project's admin page and change the visibility option to make
    the project public. It's required because all new projects in Pontoon are private
    by default and aren't visible to localizers and locale managers.
diff --git a/pontoon/base/migrations/0011_rename_download_prefix.py b/pontoon/base/migrations/0011_rename_download_prefix.py
new file mode 100644
index 000000000..dc1e50e7a
--- /dev/null
+++ b/pontoon/base/migrations/0011_rename_download_prefix.py
@@ -0,0 +1,23 @@
+# Generated by Django 2.2.13 on 2020-09-30 11:16
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("base", "0010_comment_pinned"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="repository",
+            name="permalink_prefix",
+            field=models.CharField(
+                blank=True,
+                help_text="\n        A URL prefix for downloading localized files. For GitHub repositories,\n        select any localized file on GitHub, click Raw and replace locale code\n        and the following bits in the URL with `{locale_code}`. If you use a\n        project configuration file, you need to provide the path to the raw TOML\n        file on GitHub.\n    ",
+                max_length=2000,
+                verbose_name="Download prefix or path to TOML file",
+            ),
+        ),
+    ]
diff --git a/pontoon/base/models.py b/pontoon/base/models.py
index e103a81f7..b071d3146 100644
--- a/pontoon/base/models.py
+++ b/pontoon/base/models.py
@@ -1754,13 +1754,15 @@ class Repository(models.Model):
 
     # TODO: We should be able to remove this once we have persistent storage
     permalink_prefix = models.CharField(
-        "Download prefix",
+        "Download prefix or path to TOML file",
         blank=True,
         max_length=2000,
         help_text="""
         A URL prefix for downloading localized files. For GitHub repositories,
         select any localized file on GitHub, click Raw and replace locale code
-        and the following bits in the URL with `{locale_code}`.
+        and the following bits in the URL with `{locale_code}`. If you use a
+        project configuration file, you need to provide the path to the raw TOML
+        file on GitHub.
     """,
     )