Design doc for changing version's slug

[stsewd]

Related to #6204 #4505 #5318

[humitos]

The document looks good.

I'm not approving it yet because I want to think a little more about this and read other people's thoughts as well.

For now, I'm mentioning a problem in the solution proposed when changing the slug: delete and re-build.

[ericholscher]

This feels really complex, which is the reason I have wanted to not allow this in the past. I don't think we should build an incredibly complex system for handling renaming of the slug. We should either let users shoot themselves in the foot, or not allow it. I tend to err on the side of not allowing it, and having them ask us when they want it.

This is the same conclusion we came to last time, and I still haven't heard a good reason for why we should allow users to rename things instead of just emailing support.

[ericholscher]

What about if a user pushes a branch named latest and then changes the slug of that?

[stsewd]

We already allow users to create a latest branch that isn't machine created, the behavior is like any other branch.

readthedocs.org/readthedocs/rtd_tests/tests/test_sync_versions.py

Lines 527 to 587 in b61663b

	def test_machine_attr_when_user_define_latest_tag_and_delete_it(self):
	"""The user creates a tag named ``latest`` on an existing repo, when
	syncing the versions, the RTD's ``latest`` is lost (set to
	machine=False) and doesn't update automatically anymore, when the tag is
	deleted on the user repository, the RTD's ``latest`` is back (set to
	machine=True)."""
	version_post_data = {
	'branches': [
	{
	'identifier': 'origin/master',
	'verbose_name': 'master',
	},
	],
	'tags': [
	# User new stable
	{
	'identifier': '1abc2def3',
	'verbose_name': 'latest',
	},
	],
	}
	resp = self.client.post(
	reverse('project-sync-versions', args=[self.pip.pk]),
	data=json.dumps(version_post_data),
	content_type='application/json',
	)
	self.assertEqual(resp.status_code, 200)
	# The tag is the new latest
	version_latest = self.pip.versions.get(slug='latest')
	self.assertEqual(
	'1abc2def3',
	version_latest.identifier,
	)
	# Deleting the tag should return the RTD's latest
	version_post_data = {
	'branches': [
	{
	'identifier': 'origin/master',
	'verbose_name': 'master',
	},
	],
	'tags': [],
	}
	resp = self.client.post(
	reverse('project-sync-versions', args=[self.pip.pk]),
	data=json.dumps(version_post_data),
	content_type='application/json',
	)
	self.assertEqual(resp.status_code, 200)
	# The latest isn't stuck with the previous commit
	version_latest = self.pip.versions.get(slug='latest')
	self.assertEqual(
	'master',
	version_latest.identifier,
	)
	self.assertTrue(version_latest.machine)

[ericholscher]

Right, but won't that break places where we expect a latest slug on a project?

[stsewd]

I don't think so, the only parts where this has a special meaning is when we do a sync for versions and when sorting. So it would be sorted first (like a machine created version), but probably that's what users want.

[agjohnson]

As you mentioned, does the usage of an alias resolve some of the problems we have here, or make them easier? We have a lot of internal mechanisms, especially around syncing versions/etc, that use the slug or verbose_name. Would having a separate alias attribute for just the operations that the user cares about (serving doc version, footer version list, etc) allow us to keep existing version logic and only alter where the user facing version name is used?

I don't have a clear idea of all the places in code that we're using version objects right now.

[stsewd]

As you mentioned, does the usage of an alias resolve some of the problems we have here, or make them easier?

It solves the problem with having the docs offline for a time, yes (there is a solution for this in the design doc too). But it introduces more changes, we would need to check the current logic where we use the slug and use the alias (or/and the slug) instead. Also, using an alias doesn't solve the problem to show a different name on the footer or change the order the version is sorted, if we want to solve that with the alias, we'll need to change more code.

Also, the only special cases for the slug are latest and stable, which we already support to be created by a user.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[humitos]

Closing in favor of https://github.com/readthedocs/meta/discussions/147