All committers have signed the CLA.

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

For the initial folks I tagged for review: I realized after I requested review that I had not updated the title — this release notes PR is READY FOR REVIEW.

I pulled this down and made committed some quick changes:

• Swapped references to product names with their variables
• MInor wording adjustments
• Some structural edits, like call-outs for the "Try it" invitations, more line breaks for readability, etc.

Thank you for making these changes! You marked this as "changes requested" but what do you want me to update, @validbeck? Your comment doesn't say.

call-outs for the "Try it" invitations

There's definitely something here — plain links are a bit understated — but I am on the fence about the current formatting with callouts, for the following reasons:

• We already have a ton of visual stuff on this page and the callouts just add to that visual complexity.
• The single link as text in the callout visually looks off to me, like it's split from the body of the PR content itself and kind of gets lost in the callout
• The callouts also highlight that a lot of stuff doesn't have links but maybe should have them ... but if you added them everywhere, callouts would become overwhelming.

Let's chat about what the best approach is here. We already use buttons for some links and could try the same here, or we could look into inventing an entirely new convention for just this purpose.

Thank you for making these changes! You marked this as "changes requested" but what do you want me to update, @validbeck? Your comment doesn't say.

Just the suggestions I committed, and I hear you about the call-outs but I wanted to visually distinguish those links somehow as the previous formatting of them they were sort of lost. I like the idea of buttons for future endeavours, let's remember to chat about that!

I wanted to visually distinguish those links somehow as the previous formatting of them they were sort of lost. I like the idea of buttons for future endeavours, let's remember to chat about that!

Agreed on that visual distinction but let's see if we can figure something out for this PR or defer this change to future release notes?

Here's what a button would look like to front-load the link, with the callout included at the bottom for comparison:

These would be super simple to do and already fit into our convention of having buttons that take people to places like JupyterHub.

(And, generally, breaking up long texts with lots of visuals with some additional colums is helpful, so I might make some addutional tweaks for these release notes.)

Agreed on that visual distinction but let's see if we can figure something out for this PR or defer this change to future release notes?

Are you able to live with leaving the call-outs for this round, unless you want to go back and manually change them as I adjusted some other visuals as well (so you can't just roll the commit back cleanly)?

Are you able to live with leaving the call-outs for this round, unless you want to go back and manually change them as I adjusted some other visuals as well (so you can't just roll the commit back cleanly)?

I'm doing some spit & polish right now and don't mind manually updating the callouts as there's not that many of them. But lemme run the updated version by you later today and then also by Robin.

I have some comments regarding PR 185 the updated release notes, but which don't rise to the level of PR feedback...

(I did add also some minor feedback into the actual PR, though.)

In general, I found the release notes excellent! They provide easy-to-understand descriptive explanations, which actually help the user.

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

Section Introductory notebook for model developers:

• This section looks awesome, especially for people who aren't deeply familiar with the product. I think that in addition to the "try it yourself" link that this is crying out for a video to show it to people so they don't have to do it themselves in order to learn from it.

• I did not actually follow the ValidMind Introduction for Model Developers link and do it myself yet (though I intend to). Is going through that part of reviewing the release notes or would feedback on that (if there is any) be done separately?

• Same thing for the Test descriptions and Test sandbox links. Should they be reviewed as part of this PR? If I understand the PR correctly, it looks like those files were modified. But I'm not sure if it's to the extent that the need a full review for this PR.

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

If I am prioritizing items from a user perspective, I would have put them in the following order (apologies to doc writers!):

• Introductory notebook for model developers
• Support for external models
• Custom metric function decorators
• Documentation overview page
• Generate with AI button in text editor
• Documentation outline page with conversations
• Business unit and risk areas settings for organizations
• New documentation template editor
• QuickStart improvements

Or perhaps "QuickStart improvements" should go in the Documentation section of the release notes?

If so, one could argue that Introductory notebook for model developers should also go in the Documentation

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

Section Support for external models:

• We introduce the idea of attributes=model_attributes and assign_predictions. But is there official reference doc we can link to which shows all of the syntax and options available for these new items?

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

Section Custom metric function decorators

• This section introduces the new metric decorator but doesn't tell us much about it. At first I was disappointed that it didn't explain it more fully. But at the end we say "Try it on JupyterHub: Implement custom tests" and I saw in there that it's explained in more detail. Something to consider is to tell the user that it's explained in more detail at that link?

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

Section New documentation template editor

• Clicking on the videos gave me a network error preventing me from watching them. Maybe this is because I'm previewing or the video links aren't active yet?

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

Section Enhancements - Add extra columns on the fly

• Similar comment as above: should we be linking to reference documentation for the SDk changes we made?

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

Section Enhancements - Support for metadata in new metric decorator

• Do we need to explain what the new decorators do? I kind of get that @tags a will do the equivalent of adding a bunch of tags. But I didn't know what the @tasks decorator does. But then again, I'm not familiar with the API.

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

Section Enhancements - Associate findings with a documentation section

• Does Steven know his video is appearing in the release notes!

• The end of the video has Steven saying that a user has any questions they can always reach out to him...

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

Section Enhancements - Better UI for workflow customization

• Another change that looks like it's crying out for a video.

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

Section Enhancements - Specify a template for rich text custom fields

• Same as above: does Steven know his video is appearing in the release notes!

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

Section Documentation - More contextual information in Jupyter notebooks

• "Most of our Jupyter notebooks are available on JuypterHub" This link took me to Jupyter hub, but it looked like some random notebook, and maybe not the root one that was intended?

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

General question: do we need an Enhancements section? Why not just a list of items of what's new? Or is the intent to separate out something brand new from a change to an existing thing?

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

As always, this feedback are just suggestions. The document owner(s) should decide what, if any, to utilize. I won't be offended if any suggestions are ignored. :)

• I did not actually follow the ValidMind Introduction for Model Developers link and do it myself yet (though I intend to). Is going through that part of reviewing the release notes or would feedback on that (if there is any) be done separately?
• Same thing for the Test descriptions and Test sandbox links. Should they be reviewed as part of this PR? If I understand the PR correctly, it looks like those files were modified. But I'm not sure if it's to the extent that the need a full review for this PR.

No, only the release notes themselves should be reviewed. If you do spot an issue with any of the linked-to items, I'd capture that in a Shortcut story.

If I am prioritizing items from a user perspective, I would have put them in the following order

Reordered as suggested! The QuickStart video actually started out in the "Documentation" section and it's back there now.

We introduce the idea of attributes=model_attributes and assign_predictions. But is there official reference doc we can link to which shows all of the syntax and options available for these new items?
Similar comment as above: should we be linking to reference documentation for the SDk changes we made?

One thing these release notes need more of is related links. In this case, I added links to our developer documentation. Not ideal as it's just reference, but much the info is there.

This section introduces the new metric decorator but doesn't tell us much about it. At first I was disappointed that it didn't explain it more fully. But at the end we say "Try it on JupyterHub: Implement custom tests" and I saw in there that it's explained in more detail. Something to consider is to tell the user that it's explained in more detail at that link?

Added a bit of info but note the callouts are now buttons.

Clicking on the videos gave me a network error preventing me from watching them. Maybe this is because I'm previewing or the video links aren't active yet?

I'll have to re-test but these videos should work. We copy them over as part of the docs site deploy.

Do we need to explain what the new decorators do? I kind of get that @tags a will do the equivalent of adding a bunch of tags. But I didn't know what the @tasks decorator does. But then again, I'm not familiar with the API.

In this case, probably not, as the release notes are just the tip of the iceberg. A related link should tell you more, if you are interested.

Another change that looks like it's crying out for a video.
Same as above: does Steven know his video is appearing in the release notes!

Unless the developer has provided something, creating more visuals for release notes gets expensive fast. Typically, all the curated release highlights should have visuals or they get bumped into the enhancements section.

@even-steven do you know you're in the release notes? 😁

"Most of our Jupyter notebooks are available on JuypterHub" This link took me to Jupyter hub, but it looked like some random notebook, and maybe not the root one that was intended?

We just take you to JupyterHub. In some older release notes I think I added individual links to notebooks but it's quite extra effort at this point as we have so many of them. There's likely an improvement to be hard here, but it won't be in these release notes.

General question: do we need an Enhancements section? Why not just a list of items of what's new? Or is the intent to separate out something brand new from a change to an existing thing?

The enhancement label is a standard one provided by GitHub. From that, we curate the highlights (big, important stuff). If we got rid of one it would be the highlights, but then there's just one big bucket of new or change stuff. Every product I've worked on curates the important bits, so that's what we do as well.

Great feedback, thank you!

OK, so these release notes are done, I think, unless there is review input from @mehdi0501 or @cachafla. The docs demo site has the latest changes.

One other thing new in these release notes is a more prominent CTA to try stuff out. For example:

@nrichers Nice! I like the buttons. The only thing is this section which looks a little wonky in the columns (especially as the first paragraph has a colon at the end, indicating... look to the right / bottom?).

EDIT: Just pushed a commit with these changes, if you're OK with them!

Oooh nice.

You're more than welcome to use the demo videos that I've made, but keep in mind that they were meant to be an "internal" demo. So there might be things in there that needs to be edited out.

Besides that, looks great!

EDIT: Just pushed a commit with these changes, if you're OK with them!

Thank you, @validbeck! Agreed, this looks better. The main issue is that we don't have a whole lot of content and just some screenshots, so trying to make that look decent is a bit of a challenge.