Fixed #30624 -- Changed docs to use numbered list reStructuredText syntax. #11546
Conversation
…ntax. The numbered list syntax simplifies future maintenance: - As items are added or removed, the rendered items are automatically renumbered. - If a long list happens to reach double digits, all items remain indented the same.
There was a problem hiding this comment.
@jdufresne Thanks for this patch 👍 I think we should leave the old release notes untouched.
Why? These are docs to be maintained just as any others through best practices and project standards. The rendered content of these docs aren't changing, merely the raw code form to conform to the larger project. IMO, we should apply this best practice everywhere it can be and makes sense to. Over the long term, code has a tendency to be copied or examined by others as an example. By fixing the old release notes as well, it helps signal to new contributors how new changes should look. |
|
The aim of this change is to simplify future maintenance, we don't need to simplify maintenance of old release notes, IMO. |
|
TBH, I don't think we should make this change on mass at all. For me, it's very little benefit for quite a lot of changes in the blame view. (I see the point in lists or changes to lists going forward.) I agree with @felixxm re the old release notes. |
This really depends on tooling. I use Emac's |
|
Yes, there are tools. But they raise the barrier to entry at the very least. On balance, looking at this, I don't see the cost at justifying the benefit: we make the history more opaque for everyone for a minor gain. I appreciate others (you 🙂) may make that judgement differently. |
|
@jdufresne Many thanks for this patch, but I agree with Carlton. Closing per ticket. |
The numbered list syntax simplifies future maintenance:
As items are added or removed, the rendered items are automatically
renumbered.
If a long list happens to reach double digits, all items remain
indented the same.
https://code.djangoproject.com/ticket/30624