Opened 2 years ago

Closed 13 months ago

Last modified 13 months ago

#34043 closed New feature (fixed)

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

Reported by: Hugo Herter Owned by: Sarah Boyce
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Thibaud Colas, Sarah Boyce Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: yes

Description (last modified by 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).

Change History (17)

comment:1 by Hugo Herter, 2 years ago

Description: modified (diff)

Remove unsupported HTML tag

comment:2 by Thibaud Colas, 2 years ago

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.

comment:3 by Carlton Gibson, 2 years ago

Triage Stage: UnreviewedAccepted
Type: UncategorizedNew feature
Version: dev

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 is not progressing at that time… — always allowing an update once such exists, if that makes sense.)

🎁

Last edited 2 years ago by Carlton Gibson (previous) (diff)

comment:4 by MauryaRitesh, 22 months ago

Owner: changed from nobody to MauryaRitesh
Status: newassigned

comment:5 by Sarah Boyce, 19 months ago

Cc: Sarah Boyce added

comment:6 by Sarah Boyce, 17 months ago

Has patch: set
Owner: changed from MauryaRitesh to 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.

comment:7 by Mariusz Felisiak, 13 months ago

Needs documentation: set

comment:8 by Mariusz Felisiak <felisiak.mariusz@…>, 13 months ago

In e083f308:

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

comment:9 by Mariusz Felisiak <felisiak.mariusz@…>, 13 months ago

In 33ad36a8:

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

Backport of e083f3082c71853a01bf149bda7fdbaf58d25f4d from main

comment:10 by Mariusz Felisiak <felisiak.mariusz@…>, 13 months ago

In 9c7627d:

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

Backport of e083f3082c71853a01bf149bda7fdbaf58d25f4d from main

comment:11 by Mariusz Felisiak <felisiak.mariusz@…>, 13 months ago

In f6629ee:

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

comment:12 by Mariusz Felisiak <felisiak.mariusz@…>, 13 months ago

In be56c982:

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

comment:13 by Mariusz Felisiak, 13 months ago

Needs documentation: unset

comment:14 by Mariusz Felisiak, 13 months ago

Triage Stage: AcceptedReady for checkin

comment:15 by Mariusz Felisiak <felisiak.mariusz@…>, 13 months ago

In 97b7970c:

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

comment:16 by Mariusz Felisiak, 13 months ago

Resolution: fixed
Status: assignedclosed

comment:17 by GitHub <noreply@…>, 13 months ago

In 3b255d72:

Refs #34043 -- Tweaked wording in release note.

Note: See TracTickets for help on using tickets.
Back to Top