add changelog on render

[nstarman]

Add a change-log to the rendered project. Add the documentation to the rendered docs

Signed-off-by: Nathaniel Starkman nstarkman@protonmail.com

[pllim]

Hmm... This might depends on how the debate over at astropy/astropy#10334 turns out.

[nstarman]

I just took a look at that PR — interesting stuff. What're your thoughts on how long that PR will take to be accepted? If it's a short time, I'll turn this into a draft and update it when 10334 is merged. If it's going to be a few months and this PR is merged, then I can do another PR when 10334 is finished.

[pllim]

The change log debate has been going on for a while, so don't hold your breath. I would recommend pulling out the non-controversial docstring stuff into a separate PR. Thanks for your patience! 😅

[bsipocz]

I don't think this changelog should follow whatever is in astropy core, as the package template is certainly aiming to serve a much simpler setup than that (e.g. most often without submodules, etc.).

Examples scatter a lot, basically all packages require something different, have a look at regions, reproject, specutils, photutils or astroquery. For the latter there are certainly modules, they maybe modules for photutils, too, but they make little sense for the first 3.

[pllim]

Well, if the package author also wants to take advantage of the astropy-bot change log checker, the format does have to follow core. Although, Stuart has a different bot for towncrier too. 🤷 🤷

[bsipocz]

And I think a what's new is also borderline useful for small projects (but a narrative docs page that links to, or even better, parses the changelog would be awesome).
At least in my dream world users read the full changelog not just a glorified what's new snippet (maybe my aversion towards "what's new" is that it suggest to highlight only new shiny stuff, while many of the work and user affecting changes are in fact in the fixes and incremental improvements).

[bsipocz]

@pllim - astroquery, and photutils both use astropy-bot, but the changelog format is not exactly the core format, as there is some room for customization. So, my main point is that maybe not the core is the best format for small projects but one of the other more simpler structure (that is still compatible with astropy-bot). But as you said some projects opted in other changelog solutions, so that's another point against hard wiring one of them (maybe make it an opt in?).

[nstarman]

I would recommend pulling out the non-controversial docstring stuff into a separate PR.

@pllim, sounds good. If the main controversy is the format of the changelog, I can make it blank here and open a new PR for an (opt-in or out) default changelog format. Or if we want to keep the above discussion thread, I can do the reverse and open a new PR for a blank changelog. Given the below discussion, I'm inclined to the former.

[nstarman]

And I think a what's new is also borderline useful for small projects (but a narrative docs page that links to, or even better, parses the changelog would be awesome).

@bsipocz, I wholeheartedly agree. However, a narrative doc by parsing the the changelog seems much easier with the 10334 implementation than the current setup. However, if we are opting for a blank changelog render (above comment), than adding a blank narrative doc might make sense. When the package author starts filling in the project they would presumably choose a narrative doc style or the "whatsnew". I can open an issue on this.

[bsipocz]

@nstarman - I disagree, you can easily dump the current changelog as is in a narrative docs after a paragraph of description, after all it's already in rst, no need to parse a yaml, etc.

[nstarman]

you can easily dump the current changelog as is in a narrative docs after a paragraph of description

@bsipocz. A good suggestion. I've started this, but if you have a suggestion for the paragraph description, that would be appreciated.

If #489 is merged, then this PR should implement a cookiecutter Q to choose between the "whatsnew" styles. The current implementation is just a note saying "choose one".

[nstarman]

@bsipocz Should this be changed to Towncrier? Given the abovediscussion on the merits of narrative docs and a narrative changelog, towncrier seems a better default than a regular changelog.

[pllim]

In offline discussions, there was a consensus that towncrier is too heavy-duty to be included in the template even if the core library uses it.

[pllim]

See https://github.com/astropy/package-template#deprecation-warning