Doc "Writing your first patch for Django" doesn't explain how to contribute to the admin UI

[Hugo Herter]

The documentation ​Writing your first patch for Django is aimed to help new contributors to contribute to Django.

This documentation is focused on the test suite, and does not include any help on how to run the Admin. This makes it difficult for newcomers to contribute to UI enhancements of the Django Admin, or to test and review changes in pull requests that include UI changes.

This would make it much easier to work on tickets such as #34033, #34036, #34037, ...

Proposal

Add a section in this page that explains how to automatically start a sample project pre-populated with enough test data to test most builtin UI features and widgets.

I was recommended by @thibaudcolas to use ​this django-admin-demo project to test the admin. That project appears to be a good start, but requires dependencies unrelated to Django such as spotipy, and is hosted by a third party instead of being (part of) an official Django repository.

Questions

Would the sample project be part of the official Django repository or be a different repository ?

Does Django have test suites and tooling to keep track of UI changes automatically ?
Something like ​https://percy.io/ (proprietary, cloud, sketchy example).

[Hugo Herter]

Remove unsupported HTML tag

[Thibaud Colas]

For context, ​this django-admin-demo is a project set up by Tom so we have a dedicated, fully-featured Django admin to test accessibility issues on. I have a similar ​django_admin_tests project for the same purpose, but I’ve largely stopped using it as it doesn’t cover as much of the admin’s features as Tom’s.

[Carlton Gibson]

Thanks for the suggestion here. I think it's a good idea.

I see two phases here:

1. Can we improve the documentation?
2. Can we add a test project template?

On 1, there is the smallest of mentions in the Writing your first patch for Django tutorial. See the ​Creating projects with a local copy of Django section.

So, question, does that need to be expanded, or put some somewhere more prominent, or …? Had you seen that at all? Does it say enough even once you have? (Likely not on that last)

Then on 2: I think a repo under the GitHub Django org with one or more project templates that could be used with startproject and the --template option would be handy. Perhaps using some of the models from the docs. Perhaps providing fixtures so loaddata has something to work on. Then linked to from the Django docs. I think that would be a great resource. If you want to draft something and let me know we can get it set up on GitHub.

Part 1 is clearly addressable under the scope of this issue tracker, so let's accept for that. (It might be that we could close after that if 2 it's progressing at that time… — always allowing an update once such exists, if that makes sense.)

🎁

[Sarah Boyce]

PR: ​https://github.com/django/django/pull/16963
This hopes to slightly improve the documentation and adds UI testing into our CI.

The phase two of having a test project is difficult to maintain and unlikely to have every widget possibility. I think it's fair to say if you want to update an area, you can create a small project that has the specific thing you're testing.

[Mariusz Felisiak <felisiak.mariusz@…>]

In e083f308:

Refs #34043 -- Clarified how to test UI changes.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 33ad36a8:

[5.0.x] Refs #34043 -- Clarified how to test UI changes.

Backport of e083f3082c71853a01bf149bda7fdbaf58d25f4d from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In 9c7627d:

[4.2.x] Refs #34043 -- Clarified how to test UI changes.

Backport of e083f3082c71853a01bf149bda7fdbaf58d25f4d from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In f6629ee:

Refs #34043 -- Added context managers to SeleniumTestCase for changing window size.

[Mariusz Felisiak <felisiak.mariusz@…>]

In be56c982:

Refs #34043 -- Added --screenshots option to runtests.py and selenium tests.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 97b7970c:

Refs #34043 -- Added GitHub action to capture screenshots in Selenium tests.

[GitHub <noreply@…>]

In 3b255d72:

Refs #34043 -- Tweaked wording in release note.