Re: [Django] #35758: Use keyword argument rather than a positional argument for on_delete in the ForeignKey.on_delete docs.

[Django]

#35758: Use keyword argument rather than a positional argument for on_delete in the
ForeignKey.on_delete docs.
-------------------------------------+-------------------------------------
Reporter: kay | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:
Keywords: ForeignKey, code | Triage Stage: Accepted
examples |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Tim Graham):

`on_delete` was an optional argument until Django 2.0 (#21127,
ddd3268975dca9094d94ab1df56dae0a24a58865). At that time, the tests were
updated to remove `on_delete=` (for brevity) and `on_delete=` was added to
the documentation examples as a keyword argument (for backward
compatibility with older Django versions).

I think some of the confusion comes from documentation that wasn't
completely updated at that time.

Since `on_delete` has now been a required argument for years, I think
there's no more value in advocating it be a keyword argument in model
definitions.
--
Ticket URL: <https://code.djangoproject.com/ticket/35758#comment:3>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35758: Use keyword argument rather than a positional argument for on_delete in the
ForeignKey.on_delete docs.
-------------------------------------+-------------------------------------
Reporter: kay | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:
Keywords: ForeignKey, code | Triage Stage: Accepted
examples |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Claude Paroz):

In the same vein as we required all argument of form fields to be keyword
arguments, I'd also be in favor of having mostly keyword arguments for
model fields. In my personal practice, only the verbose_name is used as
first positional argument.
--
Ticket URL: <https://code.djangoproject.com/ticket/35758#comment:4>

[Django]

#35758: Use keyword argument rather than a positional argument for on_delete in the
ForeignKey.on_delete docs.
-------------------------------------+-------------------------------------
Reporter: kay | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:
Keywords: ForeignKey, code | Triage Stage: Accepted
examples |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by kay):

Replying to [comment:3 Tim Graham]:

> Since `on_delete` has now been a required argument for years, I think
there's no more value in advocating it be a keyword argument in model
definitions.

Replying to [comment:4 Claude Paroz]:

> In the same vein as we required all argument of form fields to be
keyword arguments, I'd also be in favor of having mostly keyword arguments
for model fields. In my personal practice, only the verbose_name is used
as first positional argument.

Just to clarify: I wasn't looking to start a discussion about argument
types on model fields, or to advocate one type over another. This is
solely about the docs and code snippets/examples contained within them.
Further discussions about implementation should probably go in a separate
ticket.


Replying to [comment:1 Sarah Boyce]:
> Agreed. Would you like to provide a patch?
>
> I would say this doesn't need a ticket but as you've raised one,
accepting

Yeah, I gathered that the suggested change may be small and
"insignificant" enough to not necessitate a ticket, but I didn't want to
stuff a bunch of explanations in a PR and potentially have to back and
forth there & generally thought it wise(r) to follow the proper workflow
considering I haven't contributed before. (The CONTRIBUTING file on GitHub
warns that "anything more than fixing a typo" is considered a non-trivial
PR.)

Will get working on a patch!
--
Ticket URL: <https://code.djangoproject.com/ticket/35758#comment:5>

[Django]

#35758: Use keyword argument rather than a positional argument for on_delete in the
ForeignKey.on_delete docs.
-------------------------------------+-------------------------------------

Reporter: kay | Owner: kay
Type: | Status: assigned

Cleanup/optimization |
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:
Keywords: ForeignKey, code | Triage Stage: Accepted
examples |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by kay):

* owner: (none) => kay
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/35758#comment:6>

[Django]

#35758: Use keyword argument rather than a positional argument for on_delete in the
ForeignKey.on_delete docs.
-------------------------------------+-------------------------------------
Reporter: kay | Owner: kay
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:
Keywords: ForeignKey, code | Triage Stage: Accepted
examples |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Ahmed Nassar):

Hi there,

I noticed this issue has been open for several months and doesn't seem to
have active progress. I'm interested in contributing to this task.

Could you please:
- Confirm if this issue is still relevant?
- If the issue is still valid, would you be open to having me work on it?
- If you're no longer actively working on this, would you be willing to
unassign yourself so I can take it over?

I'm prepared to:
- Carefully review the current documentation
- Propose specific improvements
- Submit a pull request following Django's contribution guidelines

Thank you for your time and consideration.
--
Ticket URL: <https://code.djangoproject.com/ticket/35758#comment:7>