Git backend: make defaul_branch to point to VCS' default branch

Currently, importing a project manually without setting the `default_branch`,
will make Git VCS to use `master` as the default branch. However, with the last
swap about `master` and `main` branches, repositories defaulting to `main`
branch fail when being imported on Read the Docs. Leaving the user in a blocked
state they can get out.

This commit allows `Version.identifier` to be NULL meaning that "it won't try to
guess what's the default branch of the VCS" and just leave the repository in the
immediate state after being cloned (which is already the default branch). To do
this, I'm removing the command `git checkout --force <branch>` from the steps
executed for this case.

Closes #9367

Author: humitos

readthedocs/builds/managers.py

@@ -1,7 +1,6 @@
 """Build and Version class model Managers."""
 
 import structlog
-
 from django.core.exceptions import ObjectDoesNotExist
 from django.db import models
 from polymorphic.managers import PolymorphicManager
@@ -62,7 +61,6 @@ def create_latest(self, **kwargs):
             'verbose_name': LATEST_VERBOSE_NAME,
             'machine': True,
             'active': True,
-            'identifier': LATEST,
             'type': BRANCH,
         }
         defaults.update(kwargs)

readthedocs/builds/migrations/0045_identifier_null.py

@@ -0,0 +1,20 @@
+# Generated by Django 3.2.13 on 2022-07-11 08:53
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("builds", "0044_alter_version_documentation_type"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="version",
+            name="identifier",
+            field=models.CharField(
+                blank=True, max_length=255, null=True, verbose_name="Identifier"
+            ),
+        ),
+    ]

readthedocs/builds/models.py

@@ -120,11 +120,14 @@ class Version(TimeStampedModel):
     )
     # used by the vcs backend
 
-    #: The identifier is the ID for the revision this is version is for. This
-    #: might be the revision number (e.g. in SVN), or the commit hash (e.g. in
-    #: Git). If the this version is pointing to a branch, then ``identifier``
-    #: will contain the branch name.
-    identifier = models.CharField(_('Identifier'), max_length=255)
+    # The identifier is the ID for the revision this is version is for. This
+    # might be the revision number (e.g. in SVN), or the commit hash (e.g. in
+    # Git). If the this version is pointing to a branch, then ``identifier``
+    # will contain the branch name. NULL value means it will use the VCS
+    # default branch cloned.
+    identifier = models.CharField(
+        _("Identifier"), max_length=255, null=True, blank=True
+    )
 
     #: This is the actual name that we got for the commit stored in
     #: ``identifier``. This might be the tag or branch name like ``"v1.0.4"``.

readthedocs/projects/migrations/0090_default_branch_helptext.py

@@ -0,0 +1,37 @@
+# Generated by Django 3.2.13 on 2022-07-11 09:06
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("projects", "0089_update_help_text"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="historicalproject",
+            name="default_branch",
+            field=models.CharField(
+                blank=True,
+                default=None,
+                help_text='What branch "latest" points to. Leave empty to use the default value for your VCS.',
+                max_length=255,
+                null=True,
+                verbose_name="Default branch",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="project",
+            name="default_branch",
+            field=models.CharField(
+                blank=True,
+                default=None,
+                help_text='What branch "latest" points to. Leave empty to use the default value for your VCS.',
+                max_length=255,
+                null=True,
+                verbose_name="Default branch",
+            ),
+        ),
+    ]

readthedocs/projects/models.py

@@ -164,8 +164,8 @@ class Project(models.Model):
         default=LATEST,
         help_text=_('The version of your project that / redirects to'),
     )
-    # In default_branch, None means the backend should choose the
-    # appropriate branch. Eg 'master' for git
+    # In default_branch, ``None`` means the backend will use the default branch
+    # clonned for each backend.
     default_branch = models.CharField(
         _('Default branch'),
         max_length=255,
@@ -174,8 +174,7 @@ class Project(models.Model):
         blank=True,
         help_text=_(
             'What branch "latest" points to. Leave empty '
-            'to use the default value for your VCS (eg. '
-            '<code>trunk</code> or <code>master</code>).',
+            "to use the default value for your VCS.",
         ),
     )
     requirements_file = models.CharField(
@@ -468,19 +467,10 @@ def save(self, *args, **kwargs):  # pylint: disable=arguments-differ
             if not self.slug:
                 raise Exception(_('Model must have slug'))
         super().save(*args, **kwargs)
-        try:
-            latest = self.versions.filter(slug=LATEST).first()
-            default_branch = self.get_default_branch()
-            if latest and latest.identifier != default_branch:
-                latest.identifier = default_branch
-                latest.save()
-        except Exception:
-            log.exception('Failed to update latest identifier')
 
         try:
-            branch = self.get_default_branch()
             if not self.versions.filter(slug=LATEST).exists():
-                self.versions.create_latest(identifier=branch)
+                self.versions.create_latest()
         except Exception:
             log.exception('Error creating default branches')
 

readthedocs/vcs_support/backends/git.py

@@ -174,11 +174,7 @@ def fetch(self):
         code, stdout, stderr = self.run(*cmd)
         return code, stdout, stderr
 
-    def checkout_revision(self, revision=None):
-        if not revision:
-            branch = self.default_branch or self.fallback_branch
-            revision = 'origin/%s' % branch
-
+    def checkout_revision(self, revision):
         try:
             code, out, err = self.run('git', 'checkout', '--force', revision)
             return [code, out, err]
@@ -322,12 +318,12 @@ def submodules(self):
     def checkout(self, identifier=None):
         """Checkout to identifier or latest."""
         super().checkout()
-        # Find proper identifier
+
+        # NOTE: if there is no identifier, we default to default branch cloned
         if not identifier:
-            identifier = self.default_branch or self.fallback_branch
+            return
 
         identifier = self.find_ref(identifier)
-
         # Checkout the correct identifier for this branch.
         code, out, err = self.checkout_revision(identifier)