#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 )
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 , 2 years ago
Description: | modified (diff) |
---|
comment:2 by , 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 , 2 years ago
Triage Stage: | Unreviewed → Accepted |
---|---|
Type: | Uncategorized → New feature |
Version: | → dev |
Thanks for the suggestion here. I think it's a good idea.
I see two phases here:
- Can we improve the documentation?
- 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.)
🎁
comment:4 by , 22 months ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
comment:5 by , 19 months ago
Cc: | added |
---|
comment:6 by , 17 months ago
Has patch: | set |
---|---|
Owner: | changed from | to
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 , 13 months ago
Needs documentation: | set |
---|
comment:13 by , 13 months ago
Needs documentation: | unset |
---|
comment:14 by , 13 months ago
Triage Stage: | Accepted → Ready for checkin |
---|
comment:16 by , 13 months ago
Resolution: | → fixed |
---|---|
Status: | assigned → closed |
Remove unsupported HTML tag