Codestin Search App

ryanhiebert · 2026-05-10T01:40:32Z

Trac ticket number

Branch description

This change implements DEP 16, to rename the django-admin command to django.

Wherever we reference the django-admin command in the docs, update it to reference django or “The django command”.

Renamed the django-admin directive to django-cmd, and the django-admin-option directive to django-cmd-option. If we’re comfortable with it, we can drop the -cmd, but it seemed better to identify the places to change first.

Created a djcmd role to replace djadmin. The djadmin role remains for use in historical release notes, but pointing to the renamed docs file.

The instructions for generating the man page prefer the django spelling, even for the django-admin man page.

Wherever we reference the django-admin command in the docs, updated it to reference django or “The django command”.

Added warning message to django-admin command, as specified in DEP 16.

AI Assistance Disclosure (REQUIRED)

No AI tools were used in preparing this PR.
If AI tools were used, I have disclosed which ones, and fully reviewed and verified their output.

I used Copilot in vscode to help validate this work, and to help get me past my own mental blocks to finish the work.

I wrote the initial version entirely by hand many months ago, with the assistance of the standard find tool in vscode. Of course, I missed somethings and needed to test locally, so I spun up a devcontainer, and enabled Copilot to help me debug, evaluate my approach, and run the tests. It did suggest some changes, which I thoroughly reviewed and evaluated.

Checklist

This PR follows the contribution guidelines.
This PR does not disclose a security vulnerability (see vulnerability reporting).
This PR targets the main branch.
The commit message is written in past tense, mentions the ticket number, and ends with a period (see guidelines).
I have not requested, and will not request, an automated AI review for this PR.
I have checked the "Has patch" ticket flag in the Trac system.
I have added or updated relevant tests.
I have added or updated relevant docs, including release notes if applicable.
I have attached screenshots in both light and dark modes for any UI changes.

ryanhiebert

I left a review to try to point out some things in the code that I think reviewers may want to pay particular attention to.

One thing that I've not addressed, but that was pointed out on the ticket, is translations. These changes came from a full audit of every place where django-admin was in the codebase, but I don't see anything related to translation in them.

ryanhiebert · 2026-05-10T01:42:34Z

+        rolename="djcmd",
+        indextemplate="pair: %s; django command",
+        parse_node=parse_django_cmd_node,
+    )


We could alternatively name this directive django and the role dj or something. This seemed a little clearer in intent for when we're reading the source, but I can go either way.

ryanhiebert · 2026-05-10T01:45:06Z

+        if objtype == "django-cmd":
+            objects.setdefault(("django-admin", name), value)
+
+


We could alternatively replace all existing uses of the :djadmin: role with simple text references that say django-admin. That's what I did in an earlier iteration, but I figured out how to do this, and it leaves cross references functional.

ryanhiebert · 2026-05-10T01:47:00Z

-        $ man _build/man/django-admin.1  # do a quick sanity check
-        $ cp _build/man/django-admin.1 man/django-admin.1
+        $ man _build/man/django.1  # do a quick sanity check
+        $ cp _build/man/django.1 man/django.1 man/django-admin.1


It's worth calling out this change that will be the responsibility of the releaser. These instructions use the generated man page for both the django command as well as the django-admin command.

ryanhiebert · 2026-05-10T01:49:40Z

-==================================
+========================================
+The ``django`` command and ``manage.py``
+========================================


I renamed this page to django-cmd. This will be in the URL. We could consider also keeping this page the same as it was previously to avoid breaking version switching, or renaming it to django instead.

ryanhiebert · 2026-05-10T01:57:11Z

 bcrypt = ["bcrypt>=4.1.1"]

 [project.scripts]
+django = "django.core.management:execute_from_command_line"


The money line.

ryanhiebert · 2026-05-10T02:00:30Z

+                "they are equivalent except for the printing of this message. "
+                "For more details on the naming change, see DEP 16.\n"
+            )
+


It's worth considering where exactly this is happening. Every call to django-admin will have this message. Printing to stderr is less likely to cause unexpected breakage than stdout, but we know how it goes with Hyrum's Law.

This change implements DEP 16, to rename the django-admin command to django. Wherever we reference the django-admin command in the docs, update it to reference `django` or “The django command”. Renamed the `django-admin` directive to `django-cmd`, and the `django-admin-option` directive to `django-cmd-option`. If we’re comfortable with it, we can drop the `-cmd`, but it seemed better to identify the places to change first. Created a `djcmd` role to replace `djadmin`. The `djadmin` role remains for use in historical release notes, but pointing to the renamed docs file. The instructions for generating the man page prefer the `django` spelling, even for the `django-admin` man page. Wherever we reference the django-admin command in the docs, updated it to reference `django` or “The django command”. Added warning message to django-admin command, as specified in DEP 16.

codingjoe

Nice, I'd love to help you to get this into 6.1 but it's going to be a tight squeeze.

My main concern is the ambiguity of django and django command. Commands are an established concept in Django, like migrate, collectstatic and co.

I would encourage you to go for CLI (or similar), as django-admin serves as the command line interface, for all the commands mentioned above. IMHO, this provides a neat separation. So going forward, we will always know what we are talking about.

I think there is also a lot of similar community adoption, like GitHub CLI or AWS CLI. Just to name a few.

I left some concrete but maybe not complete examples.

codingjoe · 2026-05-11T16:02:12Z

+        # Special-cases: We want 'django --version' and
+        # 'django --help' to work, for backwards compatibility.


You have a premature line break now, but I prefer the diff readability in an otherwise gigantic PR.

codingjoe · 2026-05-11T16:03:54Z

@@ -1,5 +1,5 @@
 """
-Invokes django-admin when the django module is run as a script.
+Invokes the django command when the django module is run as a script.


Hm… maybe it's best to refer to this as "CLI", not a command. As we already use the wording Command for the features of the CLI.

Suggested change

Invokes the django command when the django module is run as a script.

Invokes the django CLI when the django module is run as a script.

codingjoe · 2026-05-11T16:04:18Z

+    app.add_object_type(
+        directivename="django-cmd",
+        rolename="djcmd",
+        indextemplate="pair: %s; django command",


Suggested change

indextemplate="pair: %s; django command",

indextemplate="pair: %s; django CLI",

codingjoe · 2026-05-11T16:04:53Z

        node["ids"] = old_ids


+def parse_django_cmd_node(env, sig, signode):


Suggested change

def parse_django_cmd_node(env, sig, signode):

def parse_django_cli_node(env, sig, signode):

codingjoe · 2026-05-11T16:05:28Z

    )
+    app.add_object_type(
+        directivename="django-cmd",
+        rolename="djcmd",


I am not a big fan of abbreviations. I ALWAYS have to look up the Sphinx's directives… But maybe that's just me.

Suggested change

rolename="djcmd",

rolename="django-cli",

codingjoe · 2026-05-11T16:09:23Z

The filename may need updating too.

codingjoe · 2026-05-11T16:10:13Z

    def test_builtin_command(self):
        """
-        directory: django-admin builtin commands fail with an error when no
+        directory: django builtin commands fail with an error when no


The django in each docstring is redundant IMHO:

Suggested change

directory: django builtin commands fail with an error when no

directory: builtin commands fail with an error when no

codingjoe · 2026-05-11T16:10:36Z


 class MainModule(AdminScriptTestCase):
-    """python -m django works like django-admin."""
+    """python -m django works like django."""


Maybe ambigous.

Suggested change

"""python -m django works like django."""

"""python -m django works like django CLI."""

codingjoe · 2026-05-11T16:11:03Z

 bcrypt = ["bcrypt>=4.1.1"]

 [project.scripts]
+django = "django.core.management:execute_from_command_line"


ryanhiebert commented May 10, 2026

View reviewed changes

ryanhiebert force-pushed the cmd branch from 80687ae to 0eacf98 Compare May 10, 2026 02:32

codingjoe reviewed May 11, 2026

View reviewed changes

		if objtype == "django-cmd":
		objects.setdefault(("django-admin", name), value)

		# Special-cases: We want 'django --version' and
		# 'django --help' to work, for backwards compatibility.

	Invokes the django command when the django module is run as a script.
	Invokes the django CLI when the django module is run as a script.

	indextemplate="pair: %s; django command",
	indextemplate="pair: %s; django CLI",

		node["ids"] = old_ids


		def parse_django_cmd_node(env, sig, signode):

	def parse_django_cmd_node(env, sig, signode):
	def parse_django_cli_node(env, sig, signode):

	directory: django builtin commands fail with an error when no
	directory: builtin commands fail with an error when no

	"""python -m django works like django."""
	"""python -m django works like django CLI."""

Uh oh!

Conversation

ryanhiebert commented May 10, 2026

Trac ticket number

Branch description

AI Assistance Disclosure (REQUIRED)

Checklist

Uh oh!

ryanhiebert left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codingjoe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants