Add optional dependencies section

[lagru]

Right now, its only focused on parsing a pyproject.toml from the
given stop revision (it's fetched form GitHub). Though, we should talk about how we want to scope changelist and what different means of fetching should be supported (e.g. specifying
a project specific requirements.txt, environment.yml, etc)...

Add three new config values `show_required_python`, `show_required_dependencies`, 
and `show_optional_dependencies`.

[lagru]

This is the current output of changelist scientific-python/changelist v0.3 main --version v0.4:

# changelist v0.4

We're happy to announce the release of changelist v0.4!

## Enhancements

- Add support for configuration files either via a remote `pyproject.toml` or a local TOML file given with the new option `--config`. This file allows the configuration of templates, ways that changelist matches labels, finds summaries, as well as logins to ignore in the contributor section ([#30](https://github.com/scientific-python/changelist/pull/30)).

## Dependencies

Minimal runtime dependencies:

- `PyGithub`
- `python>=3.9`
- `requests`
- `requests-cache`
- `tqdm`

## Contributors

2 authors added to this release (alphabetically):

- Jarrod Millman ([@jarrodmillman](https://github.com/jarrodmillman))
- Lars Grüter ([@lagru](https://github.com/lagru))

4 reviewers added to this release (alphabetically):

- Brigitta Sipőcz ([@bsipocz](https://github.com/bsipocz))
- Jarrod Millman ([@jarrodmillman](https://github.com/jarrodmillman))
- Lars Grüter ([@lagru](https://github.com/lagru))
- Stefan van der Walt ([@stefanv](https://github.com/stefanv))

_These lists are automatically generated, and may not be complete or may contain
duplicates._

[bsipocz]

It's weird to me to list dependencies in the changelog, imo that belong to the docs (unless there are changes as those should be listed in the changelog as normal).

[jarrodmillman]

I would just let the wheels handle dependencies, but I don't have a strong opinion on this.

[lagru]

Re #18 (review), I feel like it would be convenient to have the minimal dependencies right there but I get your view. It might be a bit more complex to only list changes but should be doable. I mostly made this PR because the feature was cheap to add and implement.

[jarrodmillman]

The updates should be in PRs, so we shouldn't need to do anything special.

[bsipocz]

Oh, I mean the changes should come from PRs, so ideally they are already there as a suitable entry under maybe API change (not sure that's the best section), e.g
"Minimum python requirement is now v3.9 (prnumber)"

or

"Numpy >=1.23 is now required. (prnumber)"

[lagru]

I am happy to document dependency updates in the API section, but then we need to be disciplined about these kind of PRs, e.g. scikit-image/scikit-image#7043 (comment) or scikit-image/scikit-image#7005.

[jarrodmillman]

Is this really an API change? I would think updating minimum dependencies would be a maintenance thing.

[bsipocz]

Yes, I agree it's not clear. Adding a new dependency is more than maintenance though, and dropping versions is also (the act of dropping it is of course maintenance but the consequences are more)

[lagru]

Coming back to this and addressing #18 (comment) and #18 (comment): I'm still in favor of adding it as a special section. It's awkward recording these changes explicitly in the notes as items (e.g. scikit-image/scikit-image#7284). In practice we often update a bunch of dependencies together. And because this might happen multiple times during a release, we'd end up with multiple cases of "Updated minimal dependency to NumPy X" and "Updated minimal dependency to NumPy X+1", etc.

Adding an optional list of runtime dependencies seems just way to easy not to do it. And as a maintainer I have had to dig through a tag to find out which version was supported at that time.

[stefanv]

Sorry, late to the conversation here, but how would this feature have prevented scikit-image/scikit-image#7284?

[lagru]

Dependencies might be updated multiple times during a release. With the current workflow, these updates would show up as multiple bullet points, not necessarily in a useful order. I'd find a dedicated field with "these are the minimal dependencies of the release" a lot clearer then multiple items, e.g.:

• Update minimal required NumPy version to 1.22.
• ...
• Update minimal required NumPy version to 1.22.1.

It's not a huge issue but the UX could be nicer in my opinion. :)

[jarrodmillman]

I've been rethinking this and it probably makes sense to look into something like this. I would prefer if it was a configurable option, though. Or perhaps instead of a built-in feature/option, we could have some examples showing how users could customize things for various purposes. That way we don't end up having to support too many things.

Maybe we could have a simple plugin system where users could put little functions like:

    def _format_dependencies_section(self, runtime_dependencies: set[str]):
        yield from self._format_section_title("Dependencies", level=2)
        yield "\n"
        yield "Minimal runtime dependencies:\n"
        yield "\n"
        for dependency in sorted(runtime_dependencies):
            line = f"`{dependency}`"
            line = self._sanitize_text(line)
            yield f"- {line}\n"
        yield "\n"

Then either the output of there functions could be inserted in a predetermined location or perhaps they could have a little script or config file specifying the order of the output.