new changelog section for config updates?

[nilsnolde]

I think it's currently a bit cumbersome to know anything about new config options (as a user). lately new configs all have defaults so it'll not really error out anymore (also I found that too disruptive).

should we just add a new section in the changelog to keep logging those, then people can easily see what's new/changed/removed?

[nilsnolde]

while at it, we could also talk about remodeling our changelog generally, it's not super useful at the moment. I like OSRM's changelog: https://github.com/Project-OSRM/osrm-backend/blob/master/CHANGELOG.md. we could have similar sections, config, build, python bindings, scripts, each endpoint possibly.. while the general overview would be so much better, it'll often be a discussion point in which section to put stuff which sounds very annoying..

any thoughts?

[kevinkreiser]

it would be cool if we could come up with a list of important types of things happening and tag each entry with the types that apply. the reason i say that is because for a given pr it is easily conceivable that we both make a new feature in a specific api but also a breaking config change (ie missing a new value that controls the features default). if we had a list of "types of changes" that we could tag an entry with this would alleviate the problem of organization and having to pick one bucket to put a change into. this assumes that we want to maximize "end-users" ability to make sense of what is changing at a glance. the draw back to any such system is exactly as you put it: it will be burdensome to maintain the diligence needed to really make such a system work.

anyway i would shy away from a new section because then we'll always have the problem about figuring out what the single most important thing is that a PR did. to work around that, my hypothetical changelog would look like a straight up list of changes as we currently do (but no sections) and then optional labels on each item, something like:

Unreleased

pull request	description	labels
#9999	2x speed improvement on map matching	enhancement, breaks_config, breaks_lib_apis
#9998	no longer segfault on certain isochrone input	bug_fix, breaks_lib_apis

Release Date: 2023-05-11 Valhalla 3.4.0

pull request	description	labels
#9997	made all the tests properly access static data	cleanup
#9996	added a beta api for creating mvt (vector tiles)	beta_api, breaks_lib_apis, breaks_config, new_feature

[nilsnolde]

Hm how about a table with each label one column, tick the labels that apply to your PR? I think it needs to be structured and easy to grok, just enuming labels makes that harder, also for the one raising/reviewing the PR (what are available labels, typos).

[kevinkreiser]

yep enumerating the labels as columns with a checkable box for each would work. i took 2 seconds to try to make an example but couldnt figure out how to get the checkbox in the table though haha

[nilsnolde]

yeah, doesn't seem to be supported for github markdown flavor. at least not the usual tickable checkboxes, one could use ✔️ or so.

but really, they shouldn't be interactively tickable anyways, that'd be very weird in a static document 😄