Advanced settings: Remove "default settings"

[stsewd]

We have had several users being confused about their projects using a config file and then changing the settings from the web UI, and being surprised that they don't take effect. Just after we tell them that there is a warning about this, they realize about it.

I think it's probably worth making that an actual warning by making red/yellow.

Page: https://beta.readthedocs.org/dashboard/docs/advanced/
Code: https://github.com/readthedocs/readthedocs.org/blob/main/readthedocs/templates/projects/project_advanced_settings_helptext.html

[humitos]

I'm 👍🏼 on this.

What about going one step further and disable these settings from the UI when we detect that any of the "regular versions" has used a .readthedocs.yaml in the last build?

This will definitely remove this confusion.

[agjohnson]

Agreed that something here would be a great UX improvement 👍

What about going one step further and disable these settings from the UI

This has been my vote. If users are missing the text already, making it more prominent is not likely to help -- users don't really read text in forms like this.

On the technical side, the template code here is just {{ crispy form }} ¹, so this would have to be a backend form/view change. The implementation would be easier if this were two separate forms, but because this is a fieldset, I'm not sure the easiest way to change this.

At the HTML level, I would aim for one of these:

• Add a disabled class on the fieldset element, which disables all the fields on the form:

• Or remove the fieldset entirely from the form.

Either way, there should be a non-disabled class paragraph explaining the removed settings. I have never done this with Django/crispy forms, but if it's less work, there paragraph could be added in the templates instead.

Footnotes

1. https://github.com/readthedocs/ext-theme/blob/main/readthedocsext/theme/templates/projects/settings_advanced_form.html#L12 ↩

[benjaoming]

Since we are now removing support for these settings, I would propose to move forward with this -- but via .org and not in isolated to the beta. I couldn't find an issue for this.

Users can benefit from being able to see their previous dashboard configuration when they create a new configuration file.

Secondly, we should remove the fields -- but that should be pretty easy to do later.

[humitos]

I'm 👍 on removing all this section from the UI on October, after the config file become a strict requirement for building.

[benjaoming]

Seems fine, too. When we do the full removal, we can pay attention to whether users without a config file turn out to somehow benefit from viewing their old configuration data.

I think we can close this issue then?

[agjohnson]

I'm also 👍 on removal once we have deprecate the configuration file. A couple more notes though:

• We might make the form/fields read only instead, to gives users the ability to see the settings they had previously configured
• If we want to spend time here, a configuration file suggestion could use these (non-default) options to populate an example file. Maybe this is the wrong interface for that file though
• There might be some fields that are not in the configuration file

Also reminder that any changes here will be reflected on the beta instance as long as you are performing changes at the form level. If you make template changes, they will not be in the beta instance.

[agjohnson]

I think we can close this issue then?

We should repurpose this issue for removal, we need to track that work either way.

[benjaoming]

@agjohnson I have the same take as you laid out in #159 (comment)

But I can understand that we can implement this more as a need-based thing... so we do the deprecation and removal process and assess from user inputs if we should bring back a "read-only" version of the configuration to help users that still do not have a configuration file.

[benjaoming]

Made an issue about it btw readthedocs/readthedocs.org#10386

We should repurpose this issue for removal, we need to track that work either way.

...yes, sounds good, then we can use readthedocs/readthedocs.org#10386 to track the other part

[humitos]

A couple more notes though:

I wouldn't invest this time here and just remove the form. We've given people months to make this migration and they can always find the combination of configuration that suit their needs by reading the documentation.

[agjohnson]

Well, while it may be the case that the user has had time to switch, but I wouldn't punish the user here either. Removing the form would be fairly hostile UX, as I'm sure some users would need to reference the settings they were previously using. We can avoid all of that by just applying the disabled class on the form element or fieldset, making these fields and the whole form read only.

[humitos]

Well, while it may be the case that the user has had time to switch, but I wouldn't punish the user here either. Removing the form would be fairly hostile UX, as I'm sure some users would need to reference the settings they were previously using

How much time would be an acceptable time for this migration? Can we set a date for removal?