Contributing tutorial shows the django next version but it's hardcoded and could use some automated updating

[Mike Edmunds]

The Writing your first contribution for Django tutorial refers to version 2.2 a couple of times in the Writing documentation section. Although it does say "at the time of this writing," that's still 7+ years out of date (at the time of this writing).

​https://docs.djangoproject.com/en/6.1/intro/contributing/#writing-documentation

Would we want to add this to the list of places the version number should be bumped at the start of each release cycle?

Or if we're comfortable leaving the outdated version in the tutorial, closing this ticket "wontfix" will at least record that decision (where it can hopefully be found by the next person who notices the old version number in docs/intro/contributing.txt).

[James Beard]

Reckon this is worth fixing, even as a once off bump. As someone who just downloaded 6.0 I could imagine wondering how 2.2 is still in the mix.

Btw is this wording potentially confusing:

Since this new feature will be in an upcoming release it is also added to the release notes for the next version of Django. Open the release notes for the latest version in docs/releases/,

"expected" would be better than latest. At time of writing there are release notes in that dir for upcoming releases 6.1 and 6.2.

[Natalia Bidart]

I agree we can do something better here. I would appreciate if some research can be done to use the django_next_version = "6.2" constant defined in docs/conf.py. Ideas?

[Mike Edmunds]

Replying to Natalia Bidart:

I agree we can do something better here. I would appreciate if some research can be done to use the django_next_version = "6.2" constant defined in docs/conf.py. Ideas?

We could define a ​reST substitution like |django_next_version| in the conf.py rst_epilog. (We already do that for various mailing list links.)

That would help with the version reference in the tutorial text, but not the one in the code example. Substitutions aren't processed inside code blocks.

Google AI suggests three possible solutions to that: the ​sphinx-substitution-extensions package (which is meant specifically for this use case), using the built-in .. parsed-literal:: block instead of code (which processes substitutions but would not have syntax highlighting), or hooking Sphinx's source-read event to globally replace "|django_next_version|" (or whatever) in the source before Sphinx processes it.

[SnippyCodes]

I'll take this issue I will research how to use the django_next_version Sphinx variable to keep the tutorial dynamically updated, rather than just hardcoding a version bump.

[Carlton Gibson]

I'm going to mark this as needing improvement. I think the text substitution approach is overkill, and it makes the source hard to read. I recommend just updating to the latest version.

[blighj]

The internals doc on writing documentation uses X.Y ​https://django--21640.org.readthedocs.build/en/21640/internals/contributing/writing-documentation.html#documenting-new-features

Could we use that?

[Mike Edmunds]

Replying to blighj:

The internals doc on writing documentation uses X.Y ​https://django--21640.org.readthedocs.build/en/21640/internals/contributing/writing-documentation.html#documenting-new-features

Could we use that?

(Heh, the internals docs freely mix X.Y and A.B. Either of those seems fine. Or N.M if we want some variety 😀)

Since this is a tutorial, we maybe shouldn't assume that all readers will understand that notation. How about X.Y plus an exact (text) reference using a conf.py-defined rst_epilog substitution (like we already do for several other things). E.g.:

… Open the release notes for the latest version in ``docs/releases/X.Y.txt``
(where X.Y is something like |django_next_version|). …

Turns into:

Open the release notes for the latest version in docs/releases/X.Y.txt (where X.Y is something like 6.2).

[Carlton Gibson]

It was precisely that which I thought too clever. Just use 6.1 and accept that we can bump it in a few years time. 🤷 (Update: I left extra context comments on the PR...)

[Mike Edmunds]

I don't have a strong opinion (other than 2.2 seems really outdated). I have weak opinions that X.Y alone is insufficient in a tutorial, and that if there's a tradeoff between optimizing for readers of the rendered tutorial vs. editors of the source file, I'd lean toward the readers.

My original suggestion was to update it to "6.2" and add it to the release bump checklist. (Or leave it "2.2" and close this wontfix.)

Natalia wondered if it was possible to use django_next_version (in comment:4). I'm guessing the goal would be to avoid adding maintainer chores and avoid similar tickets down the road. ("Tutorial refers to Django 6.2, should be Django 2029.1.")

[Carlton Gibson]

It doesn’t need updating every version. (“The best code is no code” comes to mind.)

[Carlton Gibson]

SnippyCodes updated the PR to just change the numbers. (Diff +7,-6) That's how I'd go, so I'll make RFC. Mike, James, Natalia up to you! (I'm not gonna look again 🥳)

[Natalia Bidart]

Thank you everyone! I do think we need something clever-but-reasonable for these, and I haven't yet looked at the first proposal (but I will in the next month or so), in the meantime my recommendation is to Refs this ticket in the PR that does the manual bump and I'll merge. It's an improvement no matter what, so thank you SnippyCodes!

[nessita <124304+nessita@…>]

In 99ab4bd1:

Refs #37217 -- Updated version references to 6.2 in contributing docs.

[Natalia <124304+nessita@…>]

In 357d3518:

[6.1.x] Refs #37217 -- Updated version references to 6.2 in contributing docs.

Backport of 99ab4bd124df9cd69f990a2deba2bcfa9905851e from main.

[Natalia Bidart]

Setting back to Accepted and adjusting title to see if we can find a way to use django_next_version in the docs. I agree with Mike that I think it's acceptable to have a tiny bit of extra complexities in the docs source content to gain the benefit of super clear and copy-pasteable docs directives.

[Mike Edmunds]

If we're going to try to automate the version in the tutorial, I think SnippyCodes' ​original change to replace "|django_next_version|" in Sphinx's source-read hook is about as simple, stable, and maintainable as it can get:

• The ​source-read event is documented for exactly this sort of transformation.
• It's been available since Sphinx 0.5 (2009), and the only change since then was in 7.0–7.5 (when source-read was briefly also emitted for .. include:: files too; that wouldn't have been a breaking change for this code).
• Our event callback would be str.replace(). No regular expressions, no filtering for specific filenames. No magic.

The downside (as Carlton pointed out) is the tutorial source ends up with lines like these, which are less readable than before:

    --- a/docs/releases/|django_next_version|.txt
    +++ b/docs/releases/|django_next_version|.txt

We could use something other than |django_next_version| as the substitution string, to try to make the source more readable:

• E.g., N.M so the source could read a/docs/releases/N.M.txt, etc. That works for now, if you restrict the replacement to word boundaries (r"\bN\.M\b" doesn't match any existing docs source). But it might cause unintended replacements in future edits. (X.Y and A.B already appear in the docs.)
• Or something like |N.M| or |X.Y| to minimize chances of accidental replacement. (Also, the pipe chars maybe help convey there's reST substitution involved.) I'm not convinced that would be more meaningful than |django_next_version| in the source, but it is shorter.

Like I said above, I don't feel that strongly about automating it. But if we do want to, this would be my recommendation.

[blighj]

Related to this
​https://docs.djangoproject.com/en/6.0/ref/django-admin/#envvar-DJANGO_RUNSERVER_HIDE_WARNING

django-admin.txt has a block that renders with |version| in the url, is that a known bug?

WARNING: This is a development server. Do not use it in a production setting. Use a production WSGI or ASGI server instead.
For more information on production servers see: https://docs.djangoproject.com/en/|version|/howto/deployment/

[Mike Edmunds]

Replying to blighj:

django-admin.txt has a block that renders with |version| in the url, is that a known bug?

WARNING: This is a development server. Do not use it in a production setting. Use a production WSGI or ASGI server instead.
For more information on production servers see: https://docs.djangoproject.com/en/|version|/howto/deployment/

Good catch. It's probably not necessary for the docs to quote the entire warning message there. I'd suggest removing the last sentence to avoid more complicated substitution logic (|version| would need to resolve to dev for pre-alpha versions).