Add version info to API reference.

[altocumulus]

Mainly while answering questions on StackOverflow I often find myself looking for information about when a method was added to the code base. It would be particularly helpful if we could have this information presented in the API docs themselves like this:

# selection.selectChild([selector]) · Source · Since v2.0.0

Ideally, the version info on the method would link directly to the tagged release version in the GitHub repository like in above example.

Obviously, this needs to be done twice for every method:

1. Version when added to the module
2. Version when added to the main bundle

This is a one-time effort, though, as the information will not change in the future. Should we agree on this I would love to volunteer for assembling the information from the repository's history.

[curran]

This is a really cool idea!

Have you estimated how many edits would need to be made to implement this across all of D3?

Also the changelog might be a good source, instead of combing through commits.

I'm curious what is your current workflow for researching what release included each method?

[altocumulus]

@curran You won't have to comb through individual commits, sifting through the tagged releases will do.

Back in 2016 I suggested the introduction of the links to the source code behind every method (Add links from API docs to source. #2922) which, I think, is comparable in time and effort. That feat was completed in roughly 3 weeks total (see checklist). Double that time to account for the extra effort for the main bundle and you are still facing a feasible task. Additionally, the source links might change over time, whereas the links to the version are static information.

My current workflow for finding this information is basically a gut-based approach. Since I have closely followed the development of D3 over the past years I have a relatively precise feeling for when a feature was introduced to the code base. When it comes to finding the exact version, though, I always end up poking around in the version history.

[curran]

Got it. This sounds promising! Maybe open a PR that makes the change for just one method? Then we can try to get an audience with more D3 maintaners and ask for feedback on the formatting before doing it everywhere.

I see a path forward as:

• Do it for just one or a few methods
• Await approval or feedback from D3 maintainers
• Go ahead and do it to completion, maybe one package at a time

[Fil]

There is an effort to work the API in a more (data-) structured way:

• data extraction (by reading all the READMEs from all the D3 modules): https://observablehq.com/d/04e78a8833743a0d
• example usage: https://observablehq.com/d/352e015b493a0a84

It's not yet reached the point where it can be used to completely regenerate the API.md file, but it's close. Adding more info to that structure would be very useful.

[altocumulus]

@Fil Sounds promising. I'll have a look into that. BTW, your second link is dead.

[altocumulus]

@curran, @Fil As a POC I just created a PR for the d3-fetch module with the suggested edits to the README.md. Since it's a relatively small module with a short release history it took only about 15 minutes to compile the information and edit it into the README file.

[Fil]

two remarks:

• The more generic syntax we have atm is · [Source](), [Examples]() with the examples link being optional.
• When there is a change in a method's API, would "since" refer to the first time the method was introduced or to the last time it was modified?

PS: I've shared the second link.

[altocumulus]

Fair enough, among others I also stumbled upon the points you mentioned:

• The more generic syntax we have atm is · Source, Examples with the examples link being optional.

I realized the deviation from the generic syntax and I also tried out · [Source](), [Examples](), Since vx.x.x. However, there is a slight difference in the meaning of the links as first two link to resources whereas the Since is a piece of information more like a tag and, hence, the category spacer ·. Furthermore, I found my approach more pleasing to the eye. It's a matter of taste, though, and I am open for discussion.

• When there is a change in a method's API, would "since" refer to the first time the method was introduced or to the last time it was modified?

That's a far more tricky one to answer and I am totally undecided on it. I'd love to hear some pros and cons on this.

Two more things which came to my mind:

• Should we start off with v1.0.0 as the lowest version for the modules or should we include v0.x.x versions as well as alpha-, beta-, and other pre-releases? The problem with starting at v1.0.0 is that, although the version info might read v1.0.0, we still have to link to the v0.x.x tagged release info because that's the only place the information about the method's addition is consistently available. Personally, I tend to include the v0.x.x versions as well.

• As for the main bundle I suggest starting with v3 as the lowest version, because of the extensive changes to the API from v2 to v3.

[altocumulus]

• When there is a change in a method's API, would "since" refer to the first time the method was introduced or to the last time it was modified?

The more I think about those two options the more I tend to the latter. Knowing when a method was first added just by its name is not of much use if its signature has changed in the meantime. The typical use case would be to look when a method with the documented signature first became available in the API.

To get the most out of it I suggest using the following syntax:

• For newly added methods: · Added vx.x.x
• For changed methods: · Changed vx.x.x

The Changed tag should only be used for changes to the signature, though. The decision about what tag to use should solely be made depending on the interface not the implementation.

[Fil]

Yes, it makes sense this way.

[altocumulus]

Just pushed an update incorporating the proposed changes for changed method signatures.

[mbostock]

I’d like to figure out a nice way of doing this for the new VitePress-powered documentation #3655 but I haven’t come up with one yet.

[mbostock]

Documenting the current API versions would be a one-time effort, but this request also presents an ongoing burden for any new or changed API on any future release.

By my estimate, there are currently about 1,200 methods that would need version numbers. Possibly you could parse the release notes and look for links to new API methods of the form “Add d3.foo” and detect when new methods were added… maybe this would also work to detect when methods are changed (“Fix d3.foo”) or accept new options. But the release notes are primarily intended for humans and not machines, and thus any attempt to automatically parse them to understand API changes is unlikely to be robust.

So, I think this is just too much work for me, sorry.