Add example whatsnew file #2418
Conversation
There was a problem hiding this comment.
Good catch, this is a nice improvement IMO.
I think we could merge Testing and Benchmarking into Maintenance, (maybe rename to Development or a broader concept), since they don't really impact users (benchmarking means changes to asv benchmarks, right? I assume it's not about speed improvements in algorithms, that should probably go into Enhancements).
And on the other hand, Requirements section is similar to Breaking Changes. For example, bumping python or numpy versions.
Benchmarking indeed does refer to ASV. I would be fine with merging benchmarking and testing and naming it "Development".
Still open to other ideas! |
|
I disagree with lumping Testing and Benchmarking into Development. Testing is a useful category of change on its own. Development is a broad term that I think of as adding content. |
|
Could we revisit this idea? Adding |
Hmm... I did not find a full docs page (did I miss something?) but there's a short explanation in the 0.2 release and I see it used in several pvlib files, e.g. |
|
@AdamRJensen @RDaxini this is the In any case, I'm slightly opposed to using it, cause I find it clearer to state whether the references are about something inside pvlib or outside (remember there is intersphinx enabled for packages like numpy, scipy or pandas) |
|
GIven the lack of consensus then I suggest that we hold of on the changes proposed by @RDaxini and discuss that elsewhere. @kandersolar would you give your thoughts on this PR given that you have been acting release manager for the past many releases? |
There was a problem hiding this comment.
Fine with me. This reminds me that I think I neglected to add the next whatsnew after the last release.
A side note: I expected sphinx to emit a warning along the lines of "v0.X.Y-example.rst not included in any toctree", but didn't see one in the log. I'd be interested to learn why not if anyone knows why...
I did wonder the same recently, but found the wise magic spell is written here: https://github.com/pvlib/pvlib-python/blame/main/docs/sphinx/source/conf.py#L126 |
Co-authored-by: Echedey Luis <[email protected]>
Part of pvlib's release procedures is to add a new empty Whatsnew file after the release of a new version.
I believe the current practice is to take the previous whatsnew file and delete the content. This is tedious. More of a problem is that not all releases include all types of contributions and thus the added whatsnew file is often missing sections. While, these sections typically get added, they tend to get added in a random order (maybe not a big deal).
In any case, to make the release procedure smoother I suggest having a Whatsnew template that we use as the bases for the new Whatsnew file that is added after a release. The example Whatsnew file has all possible sections (at least the ones we've used historically). Please comment if you think more should be added, if some are obsolete, or if you think that they should be ordered differently.