Skip to content

Making compiling the "What's new" easier #2104

@agbutteriss

Description

@agbutteriss

From working on the "What's New" page, I've noticed that the style of individual "What's new" entries isn't always consistent, and there isn't that clear an indication of what style, if any, they should follow.

While the relevant section of the developer's guide does mention that a "what's new" entry is ideally "written as a single concise bullet point", it doesn't clarify that the entry should start with the bullet point (going off how they compile), or that the normal character-per-line limits don't apply. The page also doesn't mention what mark-up syntax is used, so it'd be perfectly reasonable for a new developer to just write a single line in plain-text (indeed, for all they know that's what they should do). This means that some of the entries need to be manually changed for the "What's New" page to look right, which obviously takes a non-0 amount of time.

To help with ensuring that "What's New" entries are in the form we want, it seems like it might be worth adding some sort of representative example entry to the page, ideally one that takes advantage of Sphinx's features (e.g. linking to a specific class within the documentation). I'm not sure what style that should be in though (e.g. is the "fixed a bug where this function did a broken thing" style preferable to "this function no longer does this broken thing" for "Bug Fix" entries or vice versa? This isn't necessarily important in and of itself, but if one is definitely preferred it'd be better for the example to use it). I imagine it might also be possible to add some sort of test for compliance with some of the rules for the entries themselves(e.g. start with '* ').
Is there some sort of pressing reason that this hasn't been done already that I've missed?

It might also be worth making it clearer in the documentation that (from what I can gather) "What's new" entries are a thing that should be written, not just could (which is the sense I got from just reading the guide). Right now the Pull Request checklist doesn't even mention them, for instance. Adding something like "If your change is non-trivial, have you added a "What's New" entry?" could be useful, since ultimately the entry needs to get written at some point anyway.

Edit: Now I've reread it, there is a passing mention in the "Adding contribution files" section that the entry must be written in markdown, which means the statement that it doesn't make an indication is inaccurate. However, it making an incorrect one (the what's new page is written in reStructuredText, and for some relevant things the syntax is fairly different) isn't exactly better, and it does need to be more clearly highlighted (after being corrected), probably in the Writing a Contribution section.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions