0.14 release crew

[lethal urchin]

Another Bevy release is upon us! We're working together to both get it out the door, and make the process less painful: for this release and the future.

Design doc for tooling improvements: https://github.com/bevyengine/bevy-website/issues/1163

Tracking issue for release steps: https://github.com/bevyengine/bevy-website/issues/1188

Engine repo milestone: https://github.com/bevyengine/bevy/milestone/20

Website milestone: https://github.com/bevyengine/bevy-website/milestone/4

@heady frigate @obsidian peak @ancient summit @lucid hollow @short lake @hushed thistle 🙂

[obsidian peak]

Hello! :)

[ancient summit]

👋

[obsidian peak]

Shall we start a HackMD for the design document?

[lethal urchin]

Yep!

[lucid hollow]

👋

[lethal urchin]

https://hackmd.io/@alice-i-cecile/Skjz81-7A/edit

[wet crypt]

there's a previous thread on this topic, and IceSentry & I discussed a design a long time ago, and I even made a proof of concept for this tool ~10 months ago

[obsidian peak]

Do you think you can find this thread? It would be a good reference

[wet crypt]

I can look tomorrow, it's midnight

[lethal urchin]

Yeah, I did a bit of digging but didn't immediately find it

[obsidian peak]

Does anyone have thoughts on the folder structure we should use for the release notes and migration guide?

[hushed thistle]

most recent thread:
https://discord.com/channels/691052431525675048/1210295602299150426
conversation involving nickk and a design document:
#engine-dev message

[obsidian peak]

@ancient summit suggests a funnel systems, where a folder named after each PR number receives migration.md, release_notes.md, and changes.md

[lethal urchin]

And I argue for a distinct folder for each category

[obsidian peak]

Where migration.md is only required if the PR contains C-Breaking-Change and release_notes.md is only required if there's C-Needs-Release-Notes

[lethal urchin]

Part of the problem with this this suggestion is that the release note sections don't map nicely onto individual PRs

for example, we're going to have a bevy_color section, but this is actually composed of dozens of PRs

[obsidian peak]

Yup, I was actually thinking about that

[ancient summit]

I think separate .md files for the different target documents makes the most sense (migration.md, release.md, etc.). And at first glance I think storing them in a folder per-PR also makes sense, but inverting that structure to instead be a folder of migrations each containing pr123456.md also serves the same purpose

[lethal urchin]

Sounds good, I'll write this up 🙂

[obsidian peak]

@hollow coyote would you be able to take a look over the design doc when you get a chance, so we don't stumble over any Zola issues?

@lethal urchin I'm confused about the distinction between "changelog" and "release notes." Which one is the short form that most read in the blog post, and which contains the list of all PRs?

[lethal urchin]

Blog post == release notes

changelog == list of all PRs

[obsidian peak]

Thanks!

[lethal urchin]

Okay, I think I'm generally happy with the broad shape of the outline

Going to spend a bit of time looking for that thread, then try to tackle implementation steps

#engine-dev message Aha, here's a handy design doc from Nicck to link

I don't think there's anything new in there, but it's nice to gather the history and assign credit correctly

Draft implementation strategy is now ready

1. Create a new folder for the 0.14 release.
2. Add the ability to generate a migration guide for a single PR (pass in a URL or PR number).
3. Change the generate-release tool to generate seperate files for each PR in the folder structure laid out above.
4. Generate a migration-guide/_index.md file that can store links to the seperate files.
5. Change the generate-release tool to add entries to the index file when creating new files.
6. Add a daily job that scrapes the bevyengine/bevy repo and makes an individual PR for each missing example.
7. Add a new validation tool to generate-release to check and repair the document invariants above.
8. Add a CI check to run this validation tool automatically (checking only for missing links, not completeness).
9. Document that the validation tool must be run in completeness mode to the release checklist.
10. Mirror all of these tools so they work for release notes as well as migration guides.

[hollow coyote]

Okay, did a cursory read of the design doc and I have two and a half immediate concerns.

First, I'm not entirely sure how we can "[…] in the central file, import the various component files during the generation of the website according to human-friendly annotations." Unless the files we're importing are stored in another repo, or outside of the /content/ directory, or as a separate file format like *.toml, then these will show up as orphan, and or invalid, pages which is undesirable I believe. Also the one suggestion of the {% include … %} tag from Tera is primarily meant — as far as I know — for templates, to more or less create reusable widgets, rather than import another *.md file.

Second, the Migration Guide may be more similar to Release Notes in process than the design doc seems to suggest in my opinion. In cases PRs will need to be grouped together if they cover and step on the same general migrations and issues, or redundant PRs removed in the case of follow-ups that completely redo the same work.

Second and a half, I still need to solve bevy-website/#1103 (Hide public draft news pages from atom news feed) if we're planning on creating a 0.14 draft news folder for work to go in rather that the branch / PR approach. Otherwise folks with news feeds will receive notification of the article being posted prior to it's release.

[lethal urchin]

First, I'm not entirely sure how we can "[…] in the central file, import the various component files during the generation of the website according to human-friendly annotations." Unless the files we're importing are stored in another repo, or outside of the /content/ directory, or as a separate file format like *.toml, then these will show up as orphan, and or invalid, pages which is undesirable I believe. Also the one suggestion of the {% include … %} tag from Tera is primarily meant — as far as I know — for templates, to more or less create reusable widgets, rather than import another *.md file.
Okay, very helpful. I'm fine to store these outside of the /content/ directory if needed. Happy to defer to your judgement or experimentation here

Second, the Migration Guide may be more similar to Release Notes in process than the design doc seems to suggest in my opinion. In cases PRs will need to be grouped together if they cover and step on the same general migrations and issues, or redundant PRs removed in the case of follow-ups that completely redo the same work.
Agreed. I'll do a pass to try and cover this

Second and a half, I still need to solve bevy-website/#1103 (Hide public draft news pages from atom news feed) if we're planning on creating a 0.14 draft news folder for work to go in rather that the branch / PR approach. Otherwise folks with news feeds will receive notification of the article being posted prior to it's release.
Okay, noted 🤔

Data for each release is organized into 2 folders and 2 stand-alone files.
These folders must live outside of the standard content folder: otherwise they will generate stub .
By convention, these are stored in a top-level release-content folder.
Inside that folder, we will have a folder for each release, and inside of that there will be:

1. changelog.md: a simple generated file of all merged PRs, including their title and PR number, that can be organized by section either manually or automatically
2. authors.md: a trivial generated file containing the full list of authors in a random order
3. migration-guide/: a folder containing the full set of migration guide files, one for each PR that has C-Breaking-Change
   • This should be initially generated from the Migration Guide section of each PR.
4. release-notes/: a folder containing the full set of release note files, one for each area that we want to cover.
   • This could be initially generated from C-Needs-Release-Notes PRs.

The data in this folder is then imported into two index pages (one for the migration guide, one for the release notes), stored in the correct directory for the final post just as in previous releases.
Each index page describes how the various component files are integrated into a cohesive document.
This is done via some text importing mechanism (see Open Questions).

An initial list of files for both the migration guide and releases is generated based on the tags assigned on the bevyengine/bevy repo.
Each of these areas gets its own file, with a name that combines the PR title and its PR number.

The generating tool is run periodically, updating the list of files. When a new file is added, a corresponding stub entry is added to the bottom of the Migration Guide / Release Notes index file, recording that it's currently uncategorized.

Each file for the migration guide has the following metadata fields:

1. PR number(s): multiple may be grouped into a single PR
2. Title

The body text is used for the advice on how to actually migrate.

Each file for the release notes has the following metadata fields:

1. PR number(s): multiple may be grouped into a single PR
2. Title
3. Author(s): many features have multiple authors that need to be credited

There are several invariants we need to uphold (ideally checked in CI):

• Each file must correspond to a section in the index.
• Each section in the index must correspond to a file.
• Each PR with a relevant label must correspond to a file.

Note that neither the migration guide nor release notes map cleanly onto PRs (even though the converse is true)! Many entries will cover multiple PRs, and a few will have no corresponding PR on bevyengine/bevy as they reflect process, book, or website changes that still need to be highlighted.

Revised

I think that I'm comfortable enough with this to start prototyping

@hollow coyote How much would you hate it if we just turned off the RSS functionality until the release was ready?

That seems bad, but is definitely doable

[hollow coyote]

I'm fine with that; turning it off would only impact new-comers to the site, and new articles, since anyone who has previously visited has already got the feed and… well has it already. Tho the fix shouldn't take long according to my notes / initial suspicions (just got lost in other site work and me losing motivation and disappearing from working on the site for like 2 months). Can probably have it fixed sometime today.

[lethal urchin]

Okay, perfect. If a real fix seems feasible then we should go with that ❤️

Like always, I deeply appreciate the help from y'all on this stuff

The website and process stuff isn't always glamorous, but it makes a huge impact on how Bevy is perceived and our ability to teach/communicate

And not having to do it alone really helps with burnout

[hollow coyote]

Okay, got a fix up at bevy-website/#1162 (Add custom atom.xml template to hide public draft news articles). Easier than expected.

[short lake]

Alright, let me catch up on this thread. I'm glad there's interest in finally improving this 🎉

[hushed thistle]

Trying to catch up a bit.

In previous discussions, it was suggested that this be done in a new / separate repo for various reasons

• reduce github notification spam for contributors watching bevy-website
• potentially being able to grant more people merge permissions?

Is this something that was later ruled out?

I guess that was in a discussion about an automated process that generates migration guide files upon bevy PRs getting merged.

Which isn't quite what we're talking about now.

[short lake]

Yeah, I think it's probably easier to start with the proposed process in the website repo and see how it goes. I don't think the spam will be too bad, but we'll have to see

That might also help bring more attention to the website repo and not forgetting it exists until release day

[short lake]

Don't worry about disappearing, we heavily encourage people to not burn out on bevy. I'd much rather you take the time you need and come back with more energy.

[short lake]

@lethal urchin should I wait until the design doc is approved to start looking at updating generate-release to generate multiple files?

[lethal urchin]

Go ahead and start making PRs: I'll just hold off on merging controversial steps forward until there's consensus on the design doc (and @forest anchor or maybe @forest forge signs off)

[lethal urchin]

I think that this is probably not worth it: more complexity and fragmentation

If we find it's intolerable we can always swap over

But as long as we relax criteria to get these merged I can just go through and press the button on these every morning or week

Merging https://github.com/bevyengine/bevy-website/pull/1162 now

@remote bluff points out that we should request reviews from the original PR authors on the migration guide / release note PRs

And we should have a dedicated label for each

[remote bluff]

Or some similar. I was mostly thinking it would be good if the original author got some kind of notification

Helps foster a sense of ownership, and it makes the process more visible/discoverable for new contributors

[forest forge]

I agree on the several files, I proposed that several times already but never got traction. we'll see the exact details in the PR 🙂

[forest anchor]

Did a pass. I'm on board for this plan!

I suspect this will make the process much nicer / I think we should give it a go

[short lake]

I think we've all agreed it was a good idea for a while. It's just that nobody actually took the time to sit down and do it 😅

[lethal urchin]

Awesome: this is officially blessed

Feel free to start work!

[lethal urchin]

And bam: https://github.com/bevyengine/bevy-website/issues/1163

Thank y'all very much: that went really smoothly 🙂

[lethal urchin]

@short lake what are your plans for the release tool? Have anything that you think would be good for me to start mucking around with tomorrow?

[short lake]

I don't remember if @wet crypt stuff could be used as is, but if we go the route of modifying the existing tool. I'd just start with writing separate file instead of a single file. That part should be relatively easy because IIRC it's all collected in a vec being dumped to a file so you'd just need to change the last part to write a separate file for each entry

(when I made my comment earlier I had forgotten that @wet crypt had actual code, I thought it was just our discussion but we were both too busy to implement anything)

[wet crypt]

no, that was my mistake, sorry. Good luck everyone with the new tool

[short lake]

@lethal urchin here's my first draft of generating multiple files, it's pretty rough, but it gives the baseline of a single file for every migration guide https://github.com/bevyengine/bevy-website/pull/1165

[short lake]

I've reordered things a bit and added a bunch more comments. I also added the generation of the _index.md file

Now I'm going to bed, it's really late 😅

The diff is a bit scary because of all the moving around I did, but all you need to look at is generate_migration_guide() and I'd recommend just going over the actual code and ignore the diff

Next step would be to figure out how to generate the big file from all the small files and using the metadata from the frontmatter of the small files

and address all the TODOs

[lucid hollow]

Anything I can help with? I'm new to open source, any guidence would be nice 🙂

[lethal urchin]

Create a new folder for the 0.14 release notes, with a stub index file.
Create a new folder for the 0.14 migration guide, with a stub index file.
These work items from https://github.com/bevyengine/bevy-website/issues/1163 are very approachable, and a necessary step. It's a good way to get your feet wet with Zola and the project structure

[lethal urchin]

What sort of background with programming do you have? Any professional experience, any skills that are particularly relevant to game dev or web dev?

[lucid hollow]

Mostly C# on Unity, and some Rust

[lucid hollow]

I'll look into Zola and the project structure then 🙂 thanks

[lethal urchin]

Sounds good! Let us know if you have questions about how things work 🙂

The other really helpful thing to do for the release will be testing and reviewing the PRs in the milestone (and investigating fixes for any outstanding issues)

https://github.com/bevyengine/bevy/milestone/20

Even just asking questions, fixing typos, improving docs and requesting tests are really valuable

[short lake]

does anyone here have an idea on how to combine the migration guide pages in one big page?

I think using zola for that makes the most sense but I'm not sure exactly how to do that

I guess I could write a simple script that does it automatically and then just run it in CI

but if people start submitting PRs on the generated file it will cause issues

unless we don't commit the genreated file I guess

and just let CI create it

right, we also need a way to identify the specific release. So the structure should probably be

/release-content/0.14/migration-guides/
/release-content/0.14/release-notes/
/release-content/0.13/migration-guides/
/release-content/0.13/release-notes/
...

oh, it was mentioned in the details section, I just missed it 😅

[short lake]

Alright, I pushed a tool that combines all the files together and generates the zola page

So now you can use --migration-guide to generate the separate files in /release-content/version/migration-guides/ and --combine-migration-guides to generate the zola page

the combine step should probably only be done in CI

Now I just need to clean up the code

[short lake]

Alright, https://github.com/bevyengine/bevy-website/pull/1165 is ready-ish for review. I know it's still a bit rough, but I'd appreciate if people here could go over it and see if there's any major issues

[soft estuary]

is social media coordination part of this crew's scope ? I'm asking more for the rust gamedev newsletter, but my question is also for the usual "reddit / X / hackernews" posts + links to them rather than directly linking to the announcement

[lethal urchin]

Yep this seems well within scope 🙂

[obsidian peak]

I know I might be too late, but I’d prefer if Zola did this instead of CI

CI is already a constrained resource, and it definitely should be possible with Tera templates

[forest forge]

as far as I know zola doesn't have a concept of "load all files in this directory, and put them in context to render this template" unless you make all those files pages themselves

that could be an evolution of zola to make https://www.getzola.org/documentation/templates/overview/#load-data accept a glob and return an array

[lethal urchin]

https://elk.zone/mastodon.gamedev.place/@alice_i_cecile/112451242090671503 I've done a pass on the milestone now, for those who want to help out with the actual engine changes for the release ❤️

[hollow coyote]

Hmm, presuming we're just merging plain Markdown files into a Zola page Markdown file we could use macros and a template to maybe merge stuff?

Like:
Actual Page File

+++
title = "0.13 to 0.14"
template = "migration_docs.html"
[extra]
migration_guides = "/release-content/0.14/migration-guides/guides.toml"
+++

Macro Template

{% macro combine_migration_guides(toml_path) %}
  {% set guides_index = load_data(path=toml_path) %}
  {% for guide_path in guides_index.guides %}
    {% set guide = load_data(path=guide_path) %}
    {{ guide }}
  {% endfor %}
{% endmacro combine_migration_guides %}

Migration Page Docs Template

{% extends "docs.html" %}
{% import "macros/migration_docs.html" as migration_macros %}

{% block docs_content %}
  {{ migration_macros::combine_migration_guides(page.extra.migration_guides) }}
{% endblock docs_content %}

Or something along these lines.

EDIT: This admittedly is based on the concept that the migration guide generator also creates some form of toml or json file that keeps the paths, or at least file names, to each of the guides we want merged. And that the docs template would have a docs_content block created for use here.

[short lake]

I don't really understand how the file for each guide should be structured for this to work. The files have to be markdown so they can be easily edited and linted. I added a custom frontmatter at the top with some metadata that is used in the combining tool so if the macro can use that then it should be good

[hollow coyote]

This is with the presumption that it's generic Markdown files without the frontmatter that Zola uses. Basically just the content that will get put into the actual Zola page file.

[short lake]

oh, so the generator should create a separte toml file with the metadata?

[hollow coyote]

Yeah.

So say we start off with a file per PR, or however we're doing it, the tool would generate those as plain Markdown and create a guides.toml that has the path to each file.

As we edit things, merge PRs that are covering same topics, remove redundant / antiquated PRs, we modify the guides.toml to reflect the file structure.

A basic idea of what I'd imagine it to look like is:

[[guides]]
path = "pr_83274"

[[guides]]
path = "pr_87453"

[[guides]]
path = "pr_87443"

Or something like that. Or similar to community's links.toml.

Could be json, or xml, or whichever data format we like. (And that Zola supports).

[short lake]

Right now the metadata I have is the title, url, and areas because I only generate the markup for that while combining the files, but I guess I could generate all of that when generating the guide file. I did it this way so we could more easily update how the markup for those are generated without having to manually update all guides

I guess that could still work like this with the metadata stored in guides.toml, but it seems nicer if the metadata can be stored in the guide file

[hollow coyote]

Mm, it'd be nicer, but I'm not entirely sure Zola can perform the necessary string manipulation to remove the metadata, nor parse the metadata from a plain text file (that's what load_data would interpret the Markdown as).

[short lake]

I mean techinically zola can do it considering I took the frontmatter syntax directly from zola 😅 but yeah, it's probably not exposed to users for things like that

[hollow coyote]

Yeah, no. That's the stuff that's happening in the Rust behind the scenes afaik.

[short lake]

yeah, that's what I meant, the code for that exists in the zola codebase, but it's not exposed to load_data

I need to go to work for a bit, but I'll try this approach

[short lake]

how can I get access to specific keys of the metadata in the macro? Like, how does this know that guide_path is supposed to look for the path = in the metadata

  {% for guide_path in guides_data.guides %}
    {% set guide = load_data(path=guide_path) %}
    {{ guide }}
  {% endfor %}

[hollow coyote]

I… did not write entirely functional code / brain forgot a few pieces whilst trying to get the idea across primarily.

It'd actually look like:

{% for guide_data in guides_data.guides %}
    {% set guide = load_data(path=guide_data.path) %}
    {{ guide }}
  {% endfor %}

[short lake]

ah, that makes way more sense lol

thanks

[hollow coyote]

You could also just have it be file_name rather than path since it'll be presumed that the toml path, minus the slice of the file name, is the same folder.

Which could be accessed like:

toml_path | slice(end=-1) | concat(with=guide_data.file_name)

Presuming I remembered the right filter (it may not be concat).

[short lake]

ah, neat, yeah that makes sense

[short lake]

would that thing go directly inside load_data()

[hollow coyote]

Ye.

{% set guide = load_data(path=toml_path | slice(end=-1) | concat(with=guide_data.file_name)) %}

That should work, probably.

[short lake]

alright, I'll finish updating the generator and report back

[hollow coyote]

O, wait shit, that's a path, not components of paths. Need to split it first, whoops.

{% set guide = load_data(path=toml_path | split(pat="/") | slice(end=-1) | concat(with=guide_data.file_name) | join(sep="/")) %}

[hybrid junco]

sorry if this has been covered like a million times but is there going to be an rc this time?

[hollow coyote]

I believe that is the plan, last I heard.

[hybrid junco]

ty!

[short lake]

oh, right, using a generated metadata file means if people edit it and we regenerate it the edits will be lost 🙃. I guess it's not too bad since 99% of edits happen in the body

hopefully git is better at handling changes to that file since it's a bit more structured

The main issue I'm thinking of is that I'm storing the title in the metadata so we can more easily control how it gets rendered in the final output and I know I've had to update multiple titles in every release

[hollow coyote]

I mean, I imagine you'd have that issue regardless since we're dealing with generating stuff then editing it manually afterwards. Even if the metadata was in each guide file, right?

[short lake]

well, if the metadata is in each file, I just don't regenerate the file if it already exists

so edits aren't lost

the issue is I now regenerate guides.toml everytime

but I think it's structured enough for git to handle it well enough and it will be easy to discard changes

[hollow coyote]

Mm, maybe just append instead of full-rewrite if possible? Like parse the file, see what is there, what is "missing", then append what is missing. Preserves edits, and just adds a bit of annoyance in having to remove unnecessary extra stuff. Or have maybe an [[ignores]] toml table, or toml array, that lists the ones we've manually edited and should be ignored?

[short lake]

the issue is that the ordering matters so we can't do append only. The ordering matters because it's ordered by area (like ECS, Rendering, etc.)

I think the manual work required will be low enough to not justify automation of that part tbh

At least, for now. I assume eventually we'll want that too, but I don't want to block on this

Does anyone here have opinions on whether I should dump all guides under /migration-guides or should I create subfolders per-area? (/migration-guide/ECS, /migration-guides/Rendering, etc.)

there's currently 125 entries just for 0.14 so in a flat list it's a lot of files

but all files start with the pr number so it's nice if you are looking for a specific PR

[hollow coyote]

Hmm, are the folks who will be editing and writing things be more concerned about find specific PRs, or generalized areas. Hmm. Personally I think it'd be the latter, but I'm interested in what other folks have to say.

[short lake]

Yeah, that's why I originally went with area subfolders, but when I started editing some stuff I noticed I looked more for speficifc PRs so that's why I'm not sure which approach to use 😅

especially when looking at the final output, it's really easy to see the pr number and just look for that

@hollow coyote I added the callout thing to the template but zola is complaining and I'm not sure how I should fix that

{% extends "docs.html" %}
{% import "macros/migration_guides.html" as migration_guides_macros %}

{% callout(type="warning") %}
Bevy relies heavily on improvements in the Rust language and compiler.
As a result, the Minimum Supported Rust Version (MSRV) is "the latest stable release" of Rust.
{% end %}

<div class="migration-guide">
    {% block docs_content %}
        {{ migration_guides_macros::combine(page.extra.migration_guides) }}
    {% endblock docs_content %}
</div>

 --> 4:1
  |
4 | {% callout(type="warning") %}
  | ^---
  |
  = expected end of input, a macro definition tag (`{% macro my_macro() %}`, some content, or an import macro tag (`{% import "filename" as namespace %}`

oh, do shortcodes need to be imported in templates?

[hollow coyote]

Shortcodes are Zola, templates are Tera, I'm not sure if they can be mixed actually? I guess you can try importing it like a macro and see if that works?

[short lake]

right

importing didn't work

I guess that means I need to add it to the zola page

styling is broken, but it works 🎉

wait, it didn't add stuff from the template 🤔

oh, @hollow coyote the content of the guides are all in markdown, but using load_data seems to just dump the text directly

is there a way to ask it to parse the markdown?

like a filter or something?

[hollow coyote]

Actually, maybe? I vaguely remember that. Give me a second to scrape the docs

[short lake]

I should probably have looked at the docs lol, but you've been faster at replying than me looking at docs 😅

really appreciate the help btw

[hollow coyote]

Converts the given variable to HTML using Markdown.
- https://www.getzola.org/documentation/templates/overview/#markdown

This may be it?

[short lake]

well, it's html now 🙃

neat, I can add | safe and it works

[hollow coyote]

O, right, safe. I forgot about that part.

[short lake]

I guess we can assume that it's safe since if someone tries to add something weird in a guide it will be pretty obvious

[hollow coyote]

Yeah. I'm presuming this is primarily there to prevent errant <script> tags from being used to mess things up.

[short lake]

@hollow coyote do you know if it's possible to only use the template for the page_content part? Right now it doesn't generate the title/menu because the template replaces the entire page

[hollow coyote]

So, the the page-with-menu template generated title and menu aren't working? What does the template / page file / code overall look like right now? Visual example?

[short lake]

here's the template part I have so far https://github.com/bevyengine/bevy-website/pull/1165/files#diff-08f53675253b9c2e6c6e60d15440b5e5bde5480ee916ce952ca54931c7f310af

If I use template=migration_guides.html in the .md file it looks like this

if I just don't use the template I have this:

the anchor links are also not generated in the menu

here's what the 0.13 migration looks like

[short lake]

not visible in that screenshot, but pagination also doesn't work

[hollow coyote]

Like, the Prev and Next buttons don't even show?

[short lake]

yeah, here's the bottom of the page

[hollow coyote]

Okay. I'mma just add a remote of your fork to my local repo and try to experiment and figure this out on local; this seems to hit a point farther than being basically tech support can help.

[short lake]

So you don't have to generate the entire list of guides here's the first one
release-content/0.14/migration-guides/5781_bevy_reflect_Recursive_registration.md

All types that derive `Reflect` will now automatically add `GetTypeRegistration` as a bound on all (unignored) fields. This means that all reflected fields will need to also implement `GetTypeRegistration`.

If all fields **derive** `Reflect` or are implemented in `bevy_reflect`, this should not cause any issues. However, manual implementations of `Reflect` that excluded a `GetTypeRegistration` impl for their type will need to add one.

And here's the _guides.toml

[[guides]]
title = "bevy_reflect: Recursive registration"
url = "https://github.com/bevyengine/bevy/pull/5781"
areas = ["Reflection"]
file_name = "5781_bevy_reflect_Recursive_registration.md"

[short lake]

I think the main issue is that zola isn't the one generating the links so it's not aware of them

[hollow coyote]

For the anchors, that makes sense. It's the same with generate-community; it's not recorded by Zola, even if it's more or less similar to the general user.

O, shit, that's why. You used the page_content block instead of adding a new docs_content block in docs.html directly under the part where regular zola page content would go.

  <div class="media-content">
  {{ section_or_page.content | safe }}
+ {% block docs_content %}{% endblock docs_content %}
  </div>

Then use that instead of page_content.

As for the anchors, I don't think we can get them to exactly match Zolas. Those are generated from the page markdown afaik; one of those behind the scenes Rust things I think.

[short lake]

right, that worked thanks

The lack of links in the menu is a bit annoying though. I mean, the current styling for those is really ugly so I don't mind not seeing them, but it kinda sucks to not have it

[hollow coyote]

You mean the On This Page feature?

[short lake]

Uh, yeah, I think that's what it's called

The links inside the page are fine because it's pretty trivial to just generate the markup

[hollow coyote]

Huh, that should be working. I didn't think it used anything specific from Zola

[short lake]

Apparently it does, because it's not showing me anything

that or it's something else that is wrong

[hollow coyote]

Hmm. My best guess right now is inheritance is being an annoyance, and the whole docs_macro and on this page stuff is doing stuff before the descendant migration guide template adds anything, but that seems unlikely, but maybe.

Or maybe it has to do with using the Zola table of contents to get the headers, and that being based on Markdown content rather than what exists after the template.

Huh, damn.

[short lake]

I think it probably still makes more sense to go this way than combining in CI. It makes the dev experience much nicer too since you can see the output without running any command other than zola serve

We can always improve it, but I'll clean up what I have and yeet the combine code from the rust tool

[hollow coyote]

Yeah, we've survived without the on this page feature so far. Will just have to make an issue to denote that this bug born from feature conflict exists.

[short lake]

Also, I think it needs something more tailored to the content, like it should probably be split by areas in the menu

[hollow coyote]

Mm, yeah. (I wonder if we can use a bastard's mix of JavaScript and Tera template to get around this issue. Have the JS add content to the page menu trees).

Wouldn't be ideal, 'cause JS, but better than nothing I guess.

[short lake]

Yeah, it should be statically generatable but not sure if we have the tools for it

[hollow coyote]

Sidenote: should we change the page_template in _index.md to migration_guides.html and just manually leave docs.html as the template on the legacy / old migration guides that don't use the new format.

That way we don't have to remember to define template every time on new migration guides.

[short lake]

🤔 maybe, will that break existing pages?

[hollow coyote]

If we manually / override set the template in the legacy pages frontmatter, no.

[short lake]

right

I guess that's fair. I think I'd prefer doing it in a separate PR though

[hollow coyote]

Yeah, was just a thought.

[short lake]

@lethal urchin right now I have a tool that generates the list of PRs by area for the release notes and that's what we've used in the changelog, but there's also code to generate a longer changelog with the # Changelog section of PRs but I'm not sure if we've ever used that. Should I keep it anyway?

Oh, also, the multi file migrations could probably be merged now. I'll update the release-notes/contributors/changelog tools in a future PR

[lethal urchin]

I was just about to ask

[short lake]

could benefit from a quick review / sanity check though

[lethal urchin]

Looks reasonable and there's zero user impact currently

[lethal urchin]

; we don't use that

[short lake]

okay, cool, I need a break and to do actual work, so I'll update the other tools another time

[lethal urchin]

Yep ❤️ Much appreciated!

[short lake]

Working on this is really nice because it's so different to the kind of code I typically work on, so I actually really like doing it lol

[lethal urchin]

😄 It's little shell scripts! But in a real programming language!

[short lake]

I'm really excited for the cargo scripts RFC to be merged

[short lake]

@lethal urchin here's the PR for the changelog and list of contributors. I already have code for the release notes too but there's a few kinks to figure out https://github.com/bevyengine/bevy-website/pull/1172

[short lake]

Okay, the release notes is going to be a bit more annoying to author, but I think technically it will just be a template that combines all files in /release-notes + contributors.md + changelog.md. I think we'll need custom weights for sorting though. I really hope terra templates can handle that. Assuming it does though, it means that the "What's next" section and "Support us" section will probably have to be their own release note file and the introduction too

I guess these could be more hardcoded files like have a fixed intro.md and outro.md

[short lake]

oh, uhm, I didn't consider the images, I think we'll just have to ask people to dump the images next to the index.md of the news post even if they write the text in the release-content folder

right, one issue with using load_data is that zola doesn't automatically refresh on save

I wonder if there's a way to tell it to refresh when some folders update

oh, and the menu is also broken for the news page

well, not broken, there's just no menu

zola really wasn't meant to do what we are trying to do 😅

if we go back to the tool that generates the .md with rust, we could use cargo watch to update on change and it would make the menu work correctly

it would mean only generating the file in CI though

[ionic stirrup]

I wonder, are PR reviewers counted as contributors?

[lethal urchin]

Not currently, but maybe they should be

I have no objections to it: it's just a matter of "can we scrape that information easily"

I would even be open to "people who opened issues that were closed by a merged PR"

[short lake]

getting reviewers might be possible, but figuring out the graphql query for "people who opened issues that were closed by a merged PR" is probably going to be very annoying

getting the list of contributors is already way harder than it has any right to be

because there's no api for contributors that only contributed for a specific release

so I need to get the list of commit then do a graphql query for each commit

it's incredibly slow too

[vernal moss]

Isn’t that sort of n+1 query exactly what graphql is supposed to avoid?

[short lake]

maybe, but they didn't design their data in a way that it's possible get this all in one go

[vernal moss]

Uhg that’s a shame. I do kind of hate gql, it’s impossible to implement the theoretical promises.

[hollow coyote]

So, I've been thinking about this, and it occurred to me that rather than using a Macro and Migration_Guides template, we could just have a shortcode performing the exact same content loading operation as the macro and call that in the <PAGE>.md file since the current logic of the macro uses nothing truly unique to the templates. Then, hopefully, the headers and such will be picked up by Zola's ToC and make all the menus work.

This would make the On This Page and News Menus work I think.

[lethal urchin]

This makes sense to me

[short lake]

can shortcodes use load_data?

[hollow coyote]

I want to say so; don't we have that one file loading shortcode that was intended for loading external code files into code blocks?

[short lake]

I have no idea what you are referring to 😅

[hollow coyote]

Yep, load_data can be used in shortcodes:
https://github.com/bevyengine/bevy-website/blob/main/templates/shortcodes/file_code_block.html

[short lake]

ah

cool, ok, let's try that then

[short lake]

it works 🎉

well, that's the release notes, but same idea

that's even better because it means we can use the macro in the index.md for the release notes so cart will be able to write the intro/outro however he wants directly in the file

one tiny annoyance though is that the shortcode needs to be in a .md file so no syntax highlighting for all the tera stuff

we need that because if it's in a html file it treats the output of the shortcode as html

[hollow coyote]

…Tera has syntax highlighting?

I just kind of figured that it just plain didn't.

[short lake]

uh, not sure where it comes from honestly, but all the tempalte stuff gets highlighted for me in vscode

ah, right, I'm using this extension https://github.com/karuna/tera-vscode

tbf, it doesn't do much, but it's still nice to have highlighting for keywords and strings

[hollow coyote]

A, don't usually use Vscode often (too clunky compared to helix or nvim). Don't think there's an lsp or anything separate of that for highlighting afaik.

[short lake]

it's situations like that where I wish I was actually comfortable with nvim because I could just quickly add highlighting myself for the couple of keywords without having to figure out how to make a vscode plugin

anyway, this is getting off-topic lol

ok, yeah, using shortcode is awesome since now the index.md of the new post is just this

+++
title = "Bevy 0.14"
date = 2024-05-17
[extra]
show_image = false

+++

<!-- Intro -->

<!-- TODO -->

<!-- more -->

{{ combine_release_notes(release_content_path = "./release-content/0.14/") }}

## <a name="what-s-next"></a>What's Next?

<!-- TODO -->

## Support Bevy

Sponsorships help make our work on Bevy sustainable. If you believe in Bevy's mission, consider [sponsoring us](/donate) ... every bit helps!

<a class="button button--pink header__cta" href="/donate">Donate <img class="button__icon" src="/assets/heart.svg" alt="heart icon"></a>

<!-- Contributors -->
{{ load_markdown(md_path = "./release-content/0.14/contributors.md" )}}

<!-- Changelog -->
{{ load_markdown(md_path = "./release-content/0.14/changelog.md" )}}

I added the load_markdown shortcode so we can easily load any markdown files, it's pretty much just a wrapper around load_data

[short lake]

@hollow coyote can I use the public_draft feature to hide the migration guide and release notes? and if so, how? I see it takes a number but I'm not sure what it means

[hollow coyote]

The number is the relevant github issue / tracking issue.

In the case of migration guides and all this it'd be…https://github.com/bevyengine/bevy-website/issues/1163 1163

[short lake]

I was more thinking about hiding it during the RC process, so it would be a new issue for each release I guess

[hollow coyote]

Mm, yeah.

[short lake]

@lethal urchin https://github.com/bevyengine/bevy-website/pull/1172 should be ready now

[lethal urchin]

Yeah, or maybe we can somehow let it take a milestone?

[short lake]

once that's merged, I'll generate all the files using those tools and the templates for the 0.14 release

would be nice to merge this soon so people can start working on release prep and we'll be in a pretty good spot to create an RC next week I think

at least, from a process perspective

[lethal urchin]

Awesome, I'll tackle this Monday?

[short lake]

sure, sounds good, didn't realize it was already 1800 here 😅

[wary adder]

is it documented how to run this locally?

[short lake]

the generate-release tool has help messages when you run it that shows everything

at least, I tried to explain everything in there

I guess it doesn't explain what to actually do with the files it generates

[hollow coyote]

Tbh, a README.md for how to use the tool (even if it's just informing the user to run cargo run -- --help to get info), would be nice I think.

[short lake]

until now I was pretty much the only one that used those so it wasn't particularly needed, but yes

[wary adder]

OK, I think I got it

• Generate GH token
• Save it on an .env file
• Follow CLI intstructions…

[short lake]

sorry, I was writing the README, with those things, I should have explained it first 😅

[wary adder]

the blog post is something that needs to be done manually, no?

no problem

[short lake]

yes, jsut add a new post with this as the index file

+++
title = "Bevy 0.14"
date = 2024-05-17
[extra]
show_image = false

+++

<!-- Intro -->

<!-- TODO -->

<!-- more -->

{{ combine_release_notes(release_content_path = "./release-content/0.14/") }}

## <a name="what-s-next"></a>What's Next?

<!-- TODO -->

## Support Bevy

Sponsorships help make our work on Bevy sustainable. If you believe in Bevy's mission, consider [sponsoring us](/donate) ... every bit helps!

<a class="button button--pink header__cta" href="/donate">Donate <img class="button__icon" src="/assets/heart.svg" alt="heart icon"></a>

<!-- Contributors -->
{{ load_markdown(md_path = "./release-content/0.14/contributors.md") }}

<!-- Changelog -->
{{ load_markdown(md_path = "./release-content/0.14/changelog.md") }}

same thing for migration guide, just add a new post and add this somewhere inside

<div class="migration-guide">
    {{ combine_migration_guides(release_content_path = "./release-content/0.14/") }}
</div>

[wary adder]

really nice, and notes can be sorted in the toml files

eventually it would be nice to generate the changelog/contributors/... as something structured (vs md) so it can be worked with a template (and layout/styling/... improvements can be carried to older releases)

e.g. maybe contributors can be showed in columns, make it responsive, whatever

something for the future 😇

[short lake]

Yes and no, it can be done, but the tool will overwrite those changes every time you run it, so I wouldn't really do that until release day

[wary adder]

I've opened a PR for contributors: https://github.com/IceSentry/bevy-website/pull/9
I'll check the change-log and "Support Bevy" sections the following days

I would like to move the "Support Bevy" section so a shortcode, so it can be improved and the improvements get automatically reflected in older posts

maybe use the new callout, make something fancier

(or at least, if it's in a shortcode, then it's easier to make it fancy later on)

need to leave now 🙂

[short lake]

I added a README, should be a bit easier to figure out what's going on now. I also added some basic templates in the README so it's not just me that knows how the final setup is expected to work

[short lake]

Not sure if it needs a shortcode. There's nothing dynamic in it. We could use the load_markdown shortcode I added and just have a support_bevy.md somewhere

[wary adder]

fair enough, I don't mind how it's implemented, the idea was to have it as a template, as old posts might still have visits but how to support/donate can evolve and it's nice if they show the "current way of donating"

[wary adder]

I've done the same for the changelog: https://github.com/IceSentry/bevy-website/pull/11/files

few things:

• I have changed get_pr_area to return a vec… in the TOML files "no areas" is represented by an empty array
• Which means "no area" case now is handled in the templates instead
• maybe I should rename the new shortcodes to combine_* to match the other ones?
  • btw, we could change the prefix of these shortcodes to render_*? quite irrelevant, but combine for me sound more like a getter/mapper
• does it make sense to just pass the folder name to these shortcodes? like combine_release_notes(version="0.14")/changelog(version="0.14")…
• does it make sense to save a breaking_change flag in _guides.toml? I would say no because if there is a migration, it's breaking something… I suppose this logic has_migration_guide_section || has_breaking_label in migration_guides.rs is just in case the C-Breaking-Change label is missing
• should _guides.toml sorting follow the same as changelog.toml? changes without area are at the end
• should /release-content be moved to /content/releases?

also, for the migration guides post, it's probably better to move out the HTML code to a Zola template and just leave the combine_release_notes(...) part (similar to what we do in the release post): https://github.com/IceSentry/bevy-website/blob/generate-changelog-contributors/generate-release/README.md?plain=1#L31-L47

[short lake]

It's a holiday today here and I'm out with friends, but I'll try to go over this tonight

[wary adder]

no rush, it can wait

[short lake]

I'll answer more later, but release-content is not under content because everything under content is considered a page by zola but they aren't pages

[short lake]

• sounds good
• sounds good
• I used combine because it was originally literally just combining all files together without any markup generation, but I agree that something else makes a bit more sense. I'm not a huge fan of render because to me that's too close to the kind of rendering that bevy does 😅
• Yeah, at first I passed in the entire path, but since we are going with a structured approach you're right that only the version number is important
• The logic is indeed just to catch PRs with the missing label but they are still breaking. The triage team is only human for now and we make mistakes sometimes lol
• Yeah, no area being at the bottom makese sense, but that should be handled by the generator, not changing the generated file
• already answered earlier

do you want to push those proposed changes to your branch and I'll merge it after?

[short lake]

@wary adder let me know if you have any other changes in mind. I've done the shortcode for the migration_guides like you suggested. If you don't have anything else a review would be appreciated. Then alice will be able to merge and we'll be able to generate all the files and start working on the release

[wary adder]

@short lake the missing changes can go in another PR as they are Zola/templates related and won't affect the release-content

[wary adder]

here, the Zola part, except migration guides sorting (which can be done for the next release… or never 😅): https://github.com/IceSentry/bevy-website/pull/13

[short lake]

I like it, but a part of me is worried that we might be over abstracting a little 😅

[wary adder]

🙃

[short lake]

I mean, we both understand what's going on, I just hope it will be easy enough for other people to figure it out too

[wary adder]

in that line, I just moved the MSRV warning to the migration_guides template 🙈

[short lake]

right, I guess that makes sense

it's a bit abusing the intention of shortcodes I guess, but that works

[wary adder]

until you want to change the message without affecting older guides… hence over-abstracting 😅

[short lake]

yeah, that's the part I'm worried about

but we've copied all those things in every release

so...

I guess we'll just deal with it in the future whenever that happens

the annoying part is that we'll have older releases not using this process and newer ones using it

but migrating the old ones sounds way too painful compared to the gains

[wary adder]

yeah, not worth it

[short lake]

anyway, it's super mega late here and I need to sleep. I'll look at the PR tomorrow

[wary adder]

we can revert some abstraction once it's on main

the core TOML data I think is OK, so it doesn't worry me much

[wary adder]

ok! good night!

I'm going for the morning walk with the dog ^_^

[lethal urchin]

@wary adder @short lake you two are still working on this right?

[wary adder]

basically what you mentioned in the GH comment, once the "tweaks" PR is merged 1172 can be merged

well, technically, we could merge the tweaks later on main, as they are Zola templates and README tweaks… but I think it's going to be easier if we just wait a tiny bit for IceSentry#13

[lethal urchin]

Awesome, just wanted to make sure I understood the status correctly 🙂

[short lake]

Should be ready to merge now

At this point I think we are ready to start using it and we'll update things whenever we find issues in action

[lethal urchin]

Awesome. I've pressed the button 🙂

[short lake]

@lethal urchin I guess, in order to confirm it all works as expected and docs is good, would you be interested in being the one that generates everything and opens the PR with the generated files? I can do it of course, but it might be good if we can share the knowledge a bit more. I don't really plan on not helping bevy for a very long time but would be nice if the bus factor was higher than one on this (well, now it's 2 thanks to all the work doup put in this)

If you are too busy I can do it later tonight though

[lethal urchin]

Yep, I'll try this tomorrow!

[short lake]

Actually, if anyone here is interested in doing it just ping me if you have any issues

[lethal urchin]

I'll attempt it based off the docs alone and write up my complaints / let you know where I trip

[short lake]

Oh, I already found something I forgot. I didn't mention the public_draft feature in the README 😅

I'll PR it

[short lake]

@lethal urchin here's the PR https://github.com/bevyengine/bevy-website/pull/1186

[lethal urchin]

Awesome, this is clear to me.

[short lake]

essentially, you'll have to make an issue on the bevy-website repo for the 0.14 release

And other things, but that's in the README so I won't repeat it, I still want to scream test it lol

[wary adder]

is it ok if I put some random feedback on the README on that same PR? it's not related with the changes but I noticed a couple of things

[short lake]

It's already merged so you can make a new PR

[wary adder]

oh, I can't

in any case GH doesn't allow it, in BitBucket is possible to add comments in lines that are not affected 😅

[short lake]

Ah, yeah, no, you can't in github. That's really annoying tbh

at least, you can't in the review UI

I wonder if the vscode github extension let's you do that 🤔

[wary adder]

https://github.com/bevyengine/bevy-website/pull/1187

I noticed few more things in the end 😅

[lethal urchin]

Merging, thanks!

[lethal urchin]

https://github.com/bevyengine/bevy-website/issues/1188

[short lake]

Oh, I got very worried for a second when I saw the milestone was only 50% ready, but it's only for the website 😅

[lethal urchin]

@short lake @wary adder

[lethal urchin]

Maybe a bug: https://github.com/bevyengine/bevy-website/issues/1190
Initial notes: https://github.com/bevyengine/bevy-website/pull/1191
Plz list authors: https://github.com/bevyengine/bevy-website/issues/1192
Plz link original PR: https://github.com/bevyengine/bevy-website/issues/1193

[hollow coyote]

On Issue 1189, I'm confused. The docs (README.md) do explicitly mention that you need a GITHUB_TOKEN environment variable, the kind, and how to set that up. Did you instead just mean that the program itself should explicitly expect the GITHUB_TOKEN environment variable.

[lethal urchin]

Oh! I missed the README since I was initially looking at an old version of main 😅

[winged meteor]

I feel like the release notes and migration guide should be separate prs. Sort of a lot to have in one pr.

[short lake]

The idea is to generate the files as public draft so we could merge the pr right now

Then iterate on main

At least, that was my original intention

[winged meteor]

Hmmm. How do we keep track of what's done and not done?

[short lake]

At least for the migration guide it will make it easier during the rc period if they are public

[winged meteor]

Agree with that. My concern was more the release post

[short lake]

I'm not sure what you mean

[winged meteor]

Before we would have the release post pr to help organize which posts had been written or not

[hollow coyote]

Well, we have bevy-website/#1188 (Tracking issue: release Bevy 0.14) where that can happen in the comments.

[short lake]

The release post PR would only release the page in public_draft mode so not visible unless you know the url

so after that people can just make a PR to the file generated or add a new one

[lethal urchin]

And it should be easy enough to tell from the list of files which ones need work still

[short lake]

yeah, it should just be all files with a TODO comment right now 😅

[hollow coyote]

Yes-ish. There is a TODO, but it just looks like it's referring to the empty authors list more than anything, lol.

[short lake]

oh, guess I removed it then. Originally each file was just a single TODO comment

[lethal urchin]

I'm going to do a pass on what goes into the stubs tomorrow as my primary task 🙂

[short lake]

Btw, the first thing I did pretty much every release was capitalize every title correctly and standardize all the before/after code blocks to use // bevy 0.13 / // bevy 0.14 people use a bunch of different ways to do that but it's pretty easy to just do a search and replace. Although now you'll need to do a search replace in the folder I guess

and adress all the mdlint issues (which is part of why I started making a tool that writes markdown instead of just dumping the raw markdown it's way easier to work with when all the markdown is formatted the same way from the start)

After that it was hunting down all the PRs with missing guides and either write one or ask for the author. At least this release it looks like there's only one missing guide

[short lake]

Welp, @lethal urchin I was about to submit a PR with the code to generate PR authors in the release notes but I lost power because of the current storm

[lethal urchin]

You can come work from here tomorrow if you want :p We still have power!

[short lake]

Thanks for the offer, but I should be fine. It's supposed to be fixed in around 1h, so hopefully I'll have electricity tomorrow.

[short lake]

Power's back 🎉 here's the PR https://github.com/bevyengine/bevy-website/pull/1194

[wary adder]

so… I initially discarded the idea of moving more data to the release-notes TOML, but then I realised we already do that for the migration-guides, so I couldn't resist: https://github.com/IceSentry/bevy-website/pull/14

the only issue I see is that if we tweak the titles in the _release-notes.toml and then regenerate, those changes will be lost… on the other hand the TOML order is always the same so it should be easy to discard the changes in Git

the styling is WIP, we can iterate in parallel

[short lake]

@wary adder So, I think migration guides and release notes are a bit different for this. For migration guides, the title is just the PR title so we can just generate it and use that. They don't need a lot of editing either so won't generate too many diffs. But for release notes, you need more streamlined titles and some features are built on top of multiple PRs. This means the metadata file will receive a lot more edits which is not ideal since that file is always regenerated. With that said, there's a lot less release notes and after the first run of the generator it might make sense to only manually edit it going forward.

That was my reasoning for not using metadata for release notes

it's also less flexible compared to just editing the raw markdown file

What I would like to see is something closer to zola itself with a frontmatter at the top of the file, but I'm not sure we can force zola to do that with shortcodes

[short lake]

oh, didn't realize it was targetting my branch, I'll merge and implement my suggestion

[wary adder]

the only way to make it non-destructive would be by moving the title to another file, either as front-matter in the md file, by adding an extra toml file next to the md or replacing the md with a toml file

it doesn't look like front-matter is supported with load_data

so the next "best" option would be to do something like?

title = "Some feature title"
body = '''
Markdown content goes here…
'''

I don't know

[lethal urchin]

Merging https://github.com/bevyengine/bevy-website/pull/1194 now FYI

[short lake]

no, writing the body in a toml file is definitely worse

I think we'll just stick with what we have for now

and see the pain points when people start using it

[wary adder]

maybe we can encourage people to write nice PR titles 😅

hopefully it's not too painful 🤞

[lethal urchin]

Ha, the quality of these are all over the place

[wary adder]

maybe cleaning the titles and reordering should be one of the last steps, just before publishing the post…

and that's it 🤷

[lethal urchin]

Yeah, that seems workable for now

[lucid hollow]

@short lake Are you planning anything on "Add the ability to generate a migration guide for a single PR (pass in a URL or PR number)." if not I can work on it over the weekend maybe?

[short lake]

I don't personally think it's necessary so no not planning anything

[lethal urchin]

Okay, I can cut it 🙂 How are you planning on handling the "update the list" use case?

[short lake]

Just rerun the command. Dealing with the diff should be pretty easy, albeit a bit manual

By default it only overwrites the metadata file

And generates the missing files

[lethal urchin]

Okay, I can live with that 🙂

Do you have plans for the "lump multiple PRs into a single section"?

[short lake]

Not really, I didn't consider it because it wasn't an issue in the previous releases

Sorry, can't answer more right now I'm not home right now

[lethal urchin]

It's much more a thing for the release notes than for migration guides

No rush 🙂

[short lake]

That's kinda why I didn't want to add a link to the PR in the metadata, because some features are built over many PRs

But that can all be handled manually

[wary adder]

so, what we have now is like "feature PRs" but we should be able to group N PRs into a single release note, no? ~~it's probably over-engineering… but maybe:

• rename _release_notes.toml to _feature_prs.toml (or something like that)
• rename url field to pr (just the number), we can use this as ID
• don't generate a markdown file for each PR
• repurpose _release_notes.toml to define a list of release notes, where each release note references N PRs

In this model the blog post sections are not autogenerated, we have to manually define the sections in the release_notes.toml and generate corresponding MD files. It could look something like:~~~

[[release_notes]]
title = "We introduce `bevy_color`"
prs = [12013, 12147, 12163]
body = "bevy_color.md"

~~At the top of the section we could show the sum of the authors of the PRs, and at the end of the section we could link to each PR.

I'm not sure how this would work out in the Zola templates, I suppose it wouldn't be too bad if we can generate a Map in _feature_prs.toml so it's easy to find a PR by ID.~~

---

Alternatively, we just use what we have, and just do some editorial work of removing sections and merging authors manually. With maybe just changing release_notes.url into an urls array. So that different sections can be merged.

is similar to the over-engineered solution, but we merge the authors and PR links manually, and instead of creating MD files we delete the redundant ones 😅

I've a hunch that we can't have both simple and non-destructive/idempotent

[wary adder]

another idea, similar to the second option, we generate something like this, where each release_note has an array of prs (by default we generate a release note per PR):

[[release_notes]]
title = "Upstreaming bevy_color."
file_name = "12013_Upstreaming_bevy_color.md"
[[release_notes.prs]]
title = "Upstreaming bevy_color."
authors = ["@viridia","@mockersf"]
url = "https://github.com/bevyengine/bevy/pull/12013"

Then, several of these can be merged into one by copying the [[release_notes.prs]] section. The templates will join the "authors", and we can show the list of PRs in the end/start of the release note.

merging few of these would look like this

I would just ignore the first options, is overkill

TLDR; assuming we don't want to tie one release note to one PR, do we really want to show the list of related PRs for a release-note?

• YES, choose:
  • change [[release_notes.url]] to urls: string[]. Merging two release-notes means manually merging authors & urls.
  • [add [[release_notes.prs]]](#1239930965267054623 message) (array of objects with title, authors, url). Merging two release-notes means [cutting/pasting the TOML "prs" sections](#1239930965267054623 message).
• NO, remove [[release_notes.url]]. Merging two release-notes means manually merging authors.

[lethal urchin]

I was thinking we don't render the URL, but instead simply use that for internal tracking. I think my preference is for the second option under YES

I've made two small improvements to the generate-release tool that need review:

1. Fix noisy warning
2. Normalize migration guide whitespace

And the initial notes PR itself is also ready for review: https://github.com/bevyengine/bevy-website/pull/1191

Wait, why doesn't this have the authors / links in the release note sections 🤔 Oh I see, it's in the release-notes.toml

[lethal urchin]

https://github.com/bevyengine/bevy-website/pull/1198

[lethal urchin]

https://github.com/bevyengine/bevy-website/pull/1199

[lethal urchin]

I'm going to go with a one-approval standard for the initial notes for the release process

They're all getting a second review pass before publication anyways, and this will dramatically smooth out the process

[short lake]

it's also super self contained so the impact of merging something is very low

oh no, the on this page thing doesn't seem to be working correctly. It should be highlighting the first one

[lethal urchin]

I'm triaging what goes in the release notes: please bikeshed me :p https://github.com/bevyengine/bevy-website/pull/1203

(sorry for spamming y'all with PRs to review 😅)

[wary adder]

I've just read the messages; @lethal urchin how is the workflow so far?

I pushed the release-notes TOML with PRs as an array of objects here: https://github.com/doup/bevy-website/tree/feature/release-notes-prs

but, I'm thinking that if having the PR URL around is just for reference, and that we really don't want to show the PRs list… then, maybe, why not just keep it as it is now but replacing the url field for a TOML comment?

[short lake]

personally, I think the URL comment should just be in the file people edit because that's where the reference is most useful

[wary adder]

that would be useful

in any case, with all my ramblings what I was trying to solve is that a release-note might reference N PRs, it's not a 1-to-1 relation

but, if we won't show the PRs in the notes… then there is nothing to solve

we could just put the link in the MD file between some <!-- … --> or as an ul/li at the end and that's it… when two release-notes are merged these could be also merged manually

[lethal urchin]

Pretty good! My main complaints:

1. The generated toml files should be linted so I can auto-format on save
2. I really need a way to merge PRs
3. It's hard to tell at a glance which PRs are done, and renaming them is a pain
4. The URL should be in the generated md files probably

[lethal urchin]

This is exactly what I want

[short lake]

didn't I make a PR that does that already?

oh, I never actually pushed the code and made a branch lol

https://github.com/bevyengine/bevy-website/pull/1215

here you go

it adds a comment with the title and one with the link

it's too late for the ones already generated though

although, might be worth trying to use --overwrite-existing and manually deal with the diff

might be easy enough

[lethal urchin]

Thanks!

[rocky rover]

@lethal urchin it might be worth pointing out how to "claim" a release notes file in the announcement post (unless I missed that somewhere)

[lethal urchin]

Yeah I'm not sure of the best process for this?

Maybe just open a draft PR?

[rocky rover]

Hm, I sorta like how it was done in the past where an issue maintained the list of notes and their authors. And you could comment your interest in working on a release note on that issue

The draft PR could work, but you'd have to make a dummy commit or something first

Unless GitHub allows you to make a PR without any changes

[lethal urchin]

This was a very large amount of work to coordinate 🤔 Might be worth it though

[rocky rover]

Yeah if it's not sustainable or can't be easily automated then we should probably look into other solutions

[lethal urchin]

Hmm, we actually could probably automate it 🤔

At least the initial list

Scrape the PR titles, add links, request from the PR author?

That would help a lot

[rocky rover]

Yeah that would be good. And down the road maybe we could add some more automation/actions to handle sign-ups?

But that all depends on if everyone else thinks the issue list is the way to go haha

[obsidian peak]

I created https://github.com/bevyengine/bevy-website/issues/1216, what are your thoughts? Its a way to list every changed API, and filter through them easily on the migration guide

It could eventually lead to tools such as cargo fix, which automatically upgrades your code

[wise juniper]

@lethal urchin I saw you removed the release note tag from https://github.com/bevyengine/bevy/pull/11904. Does this mean I shouldn't write anything about it? Or just that it's low priority?

[lethal urchin]

If you can explain the broader importance and relevance that it has, petition me for its inclusion 🙂

I didn't feel like I could do a good job of making it relevant and interesting, but you may be able to do better

[wise juniper]

Ah, I see 🙂
It allows repeating textures directly in programs like Blender, which I believe is a very common use-case for 3D environments (ground textures, wall textures, wood, etc.)
I'd include a screenshot of the relevant Blender setting and how it looks in Bevy. Does that sound alright?

[rocky rover]

Another idea could also be to create an issue per release note. That could also be automated but might not be the cleanest/easiest to manage (especially without GitHub tasklists which are still in private beta)

Although I guess you could track each issue in a milestone 🤔

[lethal urchin]

Yep, I'm interested in that!

[rocky rover]

The advantage there is it also gives a space to have initial discussion on the topic before working on a PR, including potential authors

[lethal urchin]

Yeah okay that's valid

And it avoids the ping limit and notification spam

[rocky rover]

Yeah

[lethal urchin]

And makes it easier to track the work that needs to be done at a glance...

[rocky rover]

And it might also help with discoverability for people looking to contribute

😅

[lethal urchin]

Yeah. I think I'm getting convinced

This will be exciting to see in action lol

[rocky rover]

The only downside is a huge number of issues being created so #github should be fun haha

[lethal urchin]

Well ideally this will happen gradually throughout the cycle in the future

[rocky rover]

Oh cool!

[lethal urchin]

We could even run this job on merge in the main Bevy repo

But yeah, the release note crunch is dumb and painful

I actually quite like writing these sections!

[rocky rover]

Yeah I was gonna say another downside if we keep crunching like this is that any issue with the script will be harder to undo

[lethal urchin]

Just not... as my only task for weeks while the release is blocked..

[rocky rover]

Yeah 😣

[weak widget]

oh yeah

[lethal urchin]

https://github.com/bevyengine/bevy-website/issues/1220

[obsidian peak]

@lethal urchin should I be normalizing migration guide filenames when I go over them, or just leave them as they are?

[lethal urchin]

Leave them as is: they're not user facing

[obsidian peak]

Ok, I'll do that from now on :)

[lethal urchin]

Would open issue on GitHub with the title and body:
Title: Write release notes for PR #13418: Implement opt-in sharp screen-space reflections for the deferred renderer, with improved raymarching code.
Body: This PR needs release notes for the upcoming Bevy release!
        Please reply below if you'd like to volunteer do so, whether or not you're the author of the PR.

        Release notes should:

        1. Clearly motivate the change.
        2. Be written in a way that is understandable by the average Bevy user: some programming background and a general understanding of games.
        3. Show off the coolest features of the PR. Screenshots are awesome, but elegant APIs are also welcome!
        4. If this was a perf-centric PR, quantify the performance improvements. Graphs and statistics work well for this.

        We can help you revise the release notes: a rough draft alone is incredibly useful :)
        Your expertise is invaluable for contextualizing the changes; we'll work with you to bring the technical writing up to par.

        To submit your release notes, modify `..\release-content\0.14\release-notes\13418_Implement_optin_sharp_screenspace_reflections_for_the_defe.md.md` and submit a PR.
        In that PR, please mention this issue with the `Fixes #13418` keyphrase so it gets closed automatically.

        Pinging: @@pcwalton
    )
Milestone: Release main

Progress, but I think we've somehow swapped the values of from and to 🤔

Oh wait, no, I see what happened...

Milestone: Release v0.14

There we go! We love string math

NOTE: Only users with push access can set the milestone for new issues. The milestone is silently dropped otherwise.
Boo!
NOTE: Only users with push access can set labels for new issues. Labels are silently dropped otherwise.
Double boo!

[lethal urchin]

Alright, I'm at the point where I think I need help on https://github.com/bevyengine/bevy-website/pull/1222

I'm getting a surprising JSON parsing error when fetching the list of issues, and I'm not sure how to debug or resolve it since the parser is ureq's, not ours

[obsidian peak]

I'll take a look at it and see what I can find

Looks like a serde extension on the Chrono crate

https://docs.rs/chrono/0.4.35/src/chrono/datetime/serde.rs.html#57

I'm going to see where we're deserializing a datetime struct but are not accounting for null

Yup, we're failing at client.get_issues_and_prs on line 46 of release_notes.rs client.get_issues_and_prs_per_page()

Ah, of course! Some issues have "closed_at": null because they are open!

The parser doesn't understand this, so it throws an error

@lethal urchin try this:

I don't know if the Option::unwrap logic is correct, but it handles null while parsing

And it doesn't crash anymore! :)

[lethal urchin]

Aha, thanks!

[lethal urchin]

Yep, this works a charm

[obsidian peak]

🎉

[lethal urchin]

Would open issue on GitHub with the title and body:
Title: Write release notes for PR #13501: Implement Rhombus 2D primitive.
Body: https://github.com/bevyengine/bevy/pull/13501 needs release notes for the upcoming Bevy release!
        Please reply below if you'd like to volunteer do so, whether or not you're the author of the PR.

        Release notes should:

        1. Clearly motivate the change.
        2. Be written in a way that is understandable by the average Bevy user: some programming background and a general understanding of games.
        3. Show off the coolest features of the PR. Screenshots are awesome, but elegant APIs are also welcome!
        4. If this was a perf-centric PR, quantify the performance improvements. Graphs and statistics work well for this.

        We can help you revise the release notes: a rough draft alone is incredibly useful :)
        Your expertise is invaluable for contextualizing the changes; we'll work with you to bring the technical writing up to par.

        To submit your release notes, modify `..\release-content\0.14\release-notes\13501_Implement_Rhombus_2D_primitive.md.md` and submit a PR.
        In that PR, please mention this issue with the `Fixes #13501` keyphrase so it gets closed automatically.

        Pinging: @salvadorcarvalhinho, @LuisFigueiredo73
    )
Milestone: Release v0.14
Labels: ["A-Release-Notes", "C-Content", "S-Ready-For-Implementation"]

I like the look of that!

[vernal moss]

lgtm

[wary adder]

looks nice, one thing though: you got a double .md in the file name

[lethal urchin]

Yep BD already submitted a fix for it!

I still need to figure out the actual issue creation

Running errands for a bit then I'll be back at it

[lethal urchin]

Alright, I poked at the Github docs a bit further and I'm stumped

thread 'main' panicked at generate-release\src\release_notes.rs:211:14:
called Result::unwrap() on an Err value: Ureq(Status(404, Response[status: 404, status_text: Not Found, url: https://api.github.com/repos/bevyengine/bevy-website/issues]))
note: run with RUST_BACKTRACE=1 environment variable to display a backtrace

Oh my god do I have an extra ] in there?

Hmm, that would be very odd given the code...

        let response = self
            .agent
            .post(&format!(
                "https://api.github.com/repos/bevyengine/{repo}/issues"
            ))
            .set("Authorization", &format!("Bearer {}", self.token))
            .set("Accept", "application/vnd.github+json")
            .set("X-GitHub-Api-Version", "2022-11-28")
            .send_json(ureq::json!({
                "owner": "bevyengine",
                "repo": repo,
                "title": issue_title,
                "body": issue_body,
                "milestone": milestone,
                "labels": labels,
            }))?;

[winged meteor]

square bracket is the other side of Response[
Some apis return 404 if your api token doesn't have access

[lethal urchin]

Okay, that makes more sense

That should be a 401 right?

[short lake]

github is very inconsistent about respecting http codes

like, sometimes they rate limit with a 403 and sometimes with a 429

[lethal urchin]

OKay, here's the get code that we know works:

    fn get(&self, path: &str, repo: &str) -> ureq::Request {
        self.agent
            .get(&format!(
                "https://api.github.com/repos/bevyengine/{repo}/{path}",
            ))
            .set("Accept", "application/json")
            .set("Authorization", &format!("Bearer {}", self.token))
    }

Lemme check the permissions on my token...

[short lake]

just give it all of them 🙃

it's a bit riskier for you though, because your user actually has those permissions. Even if I give it the permission to create commits github will still block it on the bevy repo for me

[winged meteor]

never trust programmers with error codes

[lethal urchin]

Aha, it has none set...

[short lake]

tbf, none is enough for the generator tool

[lethal urchin]

Mhmm

thread 'main' panicked at generate-release\src\release_notes.rs:211:14:
called `Result::unwrap()` on an `Err` value: Ureq(Status(422, Response[status: 422, status_text: Unprocessable Entity, url: https://api.github.com/repos/bevyengine/bevy-website/issues]))     
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Progress!

I think that means my request is malformed in a way that they're not bothering to tell me about

Welp, let's see what octocrab does?

CreateIssueBuilder

Alright, and here's what their JSON looks like:

            serde_json::json!({
                "title": "test-issue",
                "body": "testing...",
                "milestone": 3456,
                "labels": ["help-wanted"],
                "assignees": ["octocrab", "ferris"],
            })

Here's what my generated json looks like in a dbg!

[generate-release\src\github_client.rs:361:9] json = Object {
    "body": String("https://github.com/bevyengine/bevy/pull/12792 needs release notes for the upcoming Bevy release!\n\n        Original authors: @Kurble, @alice-i-cecile\n        \n        Please reply below if you'd like to write these notes. \n        While the author(s) of the PR often have the context, knowledge and motivation to draft the release notes for their feature,\n        anyone can contribute release notes!\n        \n        ------\n\n        Release notes should:\n        \n        1. Clearly motivate the change.\n        2. Be written in a way that is understandable by the average Bevy user: some programming background and a general understanding of games.\n        3. Show off the coolest features of the PR. Screenshots are awesome, but elegant APIs are also welcome!\n        4. If this was a perf-centric PR, quantify the performance improvements. Graphs and statistics work well for this.\n\n        We can help you revise the release notes: a rough draft alone is incredibly useful :)\n        Your expertise is invaluable for contextualizing the changes; we'll work with you to bring the technical writing up to par.\n\n        To submit your release notes, modify `..\\release-content\\0.14\\release-notes\\12792_Implement_Auto_Exposure_plugin.md` and submit a PR.\n        In that PR, please mention this issue with the `Fixes #12792` keyphrase so it gets closed automatically."),
    "labels": Array [
        String("A-Release-Notes"),
        String("C-Content"),
        String("S-Ready-For-Implementation"),
    ],
    "milestone": String("Release v0.14"),
    "title": String("Write release notes for PR #12792: Implement Auto Exposure plugin"),
}

[short lake]

the milestone is a string here, is that correct?

the example above uses an int

[lethal urchin]

I assumed that accepting a string meant they'd match, but maybe not!

[short lake]

oh, you're missing an assignees field, you might need to give it an empty array

[lethal urchin]

First guess was right :p

The milestone needs to be parsed

https://github.com/alice-i-cecile/bevy-website/issues/10 sample issue

It's all tabbed over

[lethal urchin]

https://github.com/bevyengine/bevy-website/pull/1222 is now ready for review 🙂 Thanks for the help so far!

[lethal urchin]

https://github.com/bevyengine/bevy-website/issues/1225 It works! Time to spam the repo 😄

Okay, I got a number of them up in this first batch

Now I'm getting a 403 Forbidden

So I think that means I got rate-limited

[short lake]

yeah, that's why I have a bunch of thread::sleep in the generator tool 😅

github doesn't like that kind of api use I think

[lethal urchin]

Yeah, I did sleep for a second as they suggested

But they still got mad :p

And now my duplicate checking isn't working properly 😅

[rocky rover]

I wish there was a way to exclude PR suggestion commits from being counted as an “author”

I fixed a typo haha I didn’t write the PR

[lethal urchin]

Although in some cases it does make sense to credit reviewers as co-authors

[rocky rover]

Yeah exactly

It’s tricky

[short lake]

Some suggestions are actually big enough to count as contributions I think

[ivory cosmos]

You contributed, that's what matters

[rocky rover]

And sometimes the PR author is proxying for some other author

[vernal moss]

I think we don't want to discourage frequent reviewers by nuking their inbox every three months

🙏

[rocky rover]

As long as my name comes last I think it’s fine haha

[ivory cosmos]

Hmm, that also makes sense

[short lake]

and yeah, I would really like to count reviewers. People that mostly review code need more recognition

[rocky rover]

Well ideally this runs throughout the cycle

[short lake]

For the release notes, the first author is always the PR creator

[vernal moss]

also, duplicate. https://github.com/bevyengine/bevy-website/issues/1267 https://github.com/bevyengine/bevy-website/issues/1247

[lethal urchin]

Ah good, please let me know if I've missed any more

[hushed thistle]

Issue number doesn't seem to be getting evaluated in this part of the template:

In that PR, please mention this issue with the Fixes #ISSUE_NUMBER keyphrase so it gets closed automatically.

[lethal urchin]

The duplicate functionality was tricky to test in advance

[lethal urchin]

That's deliberate

I didn't have a good way to populate it

Since we need to define the body text before we hear back from the server

[hushed thistle]

Makes sense

[lethal urchin]

Okay so, we're not getting any skipping due to issues already existing

I must be scanning the issues wrong?

Or there's a dumb string formatting problem

[lethal urchin]

This looks like it: the list is only PRs

Title: Write release notes for PR #13080: Deprecate dynamic plugins
Title: Write release notes for PR #13417: implement the full set of sort methods on QueryIter
Title: Write release notes for PR #13123: Implement a SystemBuilder for building SystemParams
Title: Write release notes for PR #13315: Add Distribution access methods for ShapeSample trait
Title: Write release notes for PR #13482: New circular primitives: Arc2d, CircularSector, CircularSegment
Issue already exists for PR #13501: Implement Rhombus 2D primitive.
Issue already exists for PR #13418: Implement opt-in sharp screen-space reflections for the deferred renderer, with improved raymarching code.
Bingo!

[bronze stream]

1234 and 1254

[lethal urchin]

Alright, I've got the duplicate checking logic working now.

Please re-review before I try that again

[lethal urchin]

We may want to reconsider our notification strategy. See this poll: #engine-dev message

[wise juniper]

I'm ready to write the release notes for https://github.com/bevyengine/bevy/pull/11904 now that I made some screenshots of a little setup. What's the current workflow? Should I wait until the files under release-content/0.14 get generated again? My PR does not have the tag, so it wouldn't be included. Or should I manually add it as an md file under release-notes and append it to _release_notes.toml?
Do I need to include this header manually?

<div class="release-feature-authors">authors: @janhohenheim</div>

Or does it get added automatically later?

[lethal urchin]

Label readded

Just do it manually for now

[wise juniper]

Do I need to add a ## title and the author header to my file?

[wise juniper]

Alright, done 🙂 I quite like how the screenshots turned out.
https://github.com/bevyengine/bevy-website/pull/1273

[hushed thistle]

Did we have some guidelines written somewhere regarding screenshots in blog posts? I recall some discussionat least, and none of the screenshots in the 0.13 post have titles/borders.

[hushed thistle]

You should be able to disable window decorations in Bevy and hold option while using window mode in the screenshot tool to get rid of the shadow / huge margin.

[lethal urchin]

@hybrid junco can you modify the migration guide for the "split visibility checks" on the bevy-website version?

Or make an issue to do so?

[hybrid junco]

yeah, i can do it, let me catch up to speed on how y’all are doing all this release work~

[wise juniper]

Fixed it, thanks for teaching me about holding alt to remove shadows 🙂

[lethal urchin]

I've swapped to leaving comments on the original PR for the issue generation: https://github.com/bevyengine/bevy-website/pull/1222/

I'd appreciate another round of review: I'd like to get this merged and then run the tool again

[tropic lark]

Hi release crew! Pretty please reiterating a past ask, if we're formalizing a release process, can we consider keeping everyone up to date with an estimated release date in an easy to find place (like #dev-announcements) so that third party crate maintainers can be aware of when to get ready to upgrade? That would save the stress of discovering after the fact that Bevy already upgraded and now everyone's waiting for your crate 😭 Thanks!

[wary adder]

I think the idea was to do a RC so plugin authors have some time, then after some time do the actual release and announcement… I don't know the timing details though

[vernal moss]

With the new RC process there will be an announcement at least one week in advance (that’s what cart said at least). It would be nice to have an announcement as soon as the RC date and tentative release date have been chosen, which would give author more time to adjust their schedules.

[lethal urchin]

Merging https://github.com/bevyengine/bevy-website/pull/1222 at last!

I'm going to run it this afternoon 🙂

[azure kestrel]

🎉

[lethal urchin]

And open a PR with the new sections as well

Thanks for all the feedback and reviews

I do rather like this tool!

[lethal urchin]

https://github.com/bevyengine/bevy-website/pull/1286

There's the new release notes 🙂

Now it's time to generate some issues 😅

Okay, I got through a number of them before getting rate-limited...

The duplicate detection worked perfectly, and the comments were left successfully

Love to see it

Looks like I get about 10 at once

I can work with that

https://github.com/bevyengine/bevy-website/issues/1317 A small improvement to the tool, if anyone's in the mood 🙂

[short lake]

I guess that would be better than just my dumb loop that waits for a few seconds for a few times before giving up 😅

I really did not expect all those tools to grow so big so I never really considered that when I made the github client thing

[lethal urchin]

I've been really surprised / impressed by how comfortable this has been to refactor and improve

Oh man this is gonna juice my Github activity!

And there we go: that's the last of the issues we needed 😄

[short lake]

I've been pinged by so many PRs 😅. Sometimes I forget how much stuff I reviewed

[vernal moss]

I find this approach much less intrusive.

Nice little short message, and it registers differently in my inbox because the PR is already closed.

[hybrid junco]

it would be cool if the script could (a). create the release note file and (b). link to the github ui for editing it, that way i could write and submit the pr for my release note entirely in the github ui 🙂

[lethal urchin]

Oh that's a neat idea. Can you open an issue to do this?

[lethal urchin]

I didn't get any pings

[short lake]

I personally don't like that because I'm always scared that github will just lose progress if I'm writing something big and it also makes it impossible to preview, but I guess it's pretty easy to just do it on my computer and paste it in there

[hybrid junco]

i definitely don't use github for this kind of stuff usually but it might decrease friction, especially for smaller features

[short lake]

do you have custom filters? I just have one big catch all filter for github but that's it 😅

[hybrid junco]

a bit of carrot and stick with the nag but also we made it easy for you to just write and submit!

[lethal urchin]

I don't use email notifications for Github at all 🤔

[short lake]

The notification UI is a mess for me so I don't use it. I like how with emails it's just a linear list of the most recent notifications in order

I just don't like github's UX for that tbh

I also like using a ton of tabs and it really doesn't like that

for people that just have one github tab for everything then it probably works better

[rocky rover]

Can we link to postings in #showcase? Or should we trying to stick more to things on GitHub?

I'm wanting to link to this post #showcase message by @glad osprey for the Custom Attributes release notes

Like I could link to the demo on the bevy_reactor repo, but I like the image that goes along with the #showcase post

[short lake]

Couldn't you just copy the image and add a note that it's from discord?

[rocky rover]

I could but my only concern would be taking up too much space

[short lake]

Rendering changes all have screenshots so I don't think there's anything wrong with reflect also getting a bit more space

[rocky rover]

Fair, I could also just include it in the PR and if we feel it'd be better as a link we could do that

@glad osprey Let me know if you have any issues with me adding this to the release notes btw. I'll make sure to add you as a reviewer

[lethal urchin]

Yeah, I would just add this as an image

I treat Discord links as ephemeral, so I'd prefer to avoid them as needed

[glad osprey]

It's all good

[vernal moss]

It looks like there are a bunch of reduntant release notes issues

https://github.com/bevyengine/bevy-website/issues/1309

Was resolved last week in https://github.com/bevyengine/bevy-website/pull/1201

Should we be closing these when we see them?

Or is there a reason to keep them open?

[lethal urchin]

Close as you see them please

[vernal moss]

Now that I am starting to write release notes, I kind of wish we had a style guide. The bevy blog has a very specific friendly voice (largely something I think you developed Alice) and it was easier to replicate it when it was just one big file and I had other stuff to reference.

Now that it's split up, I am finding myself having to reference other random stuff more to get it right. Maybe that's just me?

[short lake]

I mean, the stuff that's already written is just a file away right? I don't see how that's different? (other than being a bit more tedious)

Although, I do agree that clear guidelines might be helpful

[vernal moss]

🤷‍♂️ more authors will get the style wrong if they don't have samples handy.

But we need to edit for style anyway, considering our many amazing esl contributors, so no big deal

[ancient summit]

Generally I think this is a good idea. Since we stub out these files as empty with a TODO, perhaps we could develop a short starter template like we have for GitHub issues?

Open with sentence providing clear context for the changes about to be described.

Follow with an example of what Bevy was like prior to this release, taking care to highlight any key differences that can illustrate why we are making this change.

Consider including example code using code blocks

\`\`\`rust
use bevy::prelude::*;

fn main() {
    App::new().run();
}
\`\`\`

Where appropriate, [link to external information](https://bevy.org/) on related topics.

And if this change is appropriately visual, please include imagery!

![Alt text for this image](a_cool_image.png)

End with a short call to action linking to further information, and any possible related work that may come in the future.

Obviously this is just an example and mostly my own writing style, and it would probably be worth making clear that this is just a suggestion and not a strict template that must be adhered to (although, rules around headings etc may be worth calling out!)

[vernal moss]

great idea

[ancient summit]

I've just thrown up an issue #1343 so the idea doesn't get lost in Discord logs, I might have a crack at this later but if anyone else wants to first feel free to!

[short lake]

I remember @forest anchor at some point had some clear guidance for what he'd like to see in a release note, but I have no idea where that was

[forest anchor]

Yup! I've been posting them in the top-level release PRs since I opened that up to collaboration:
https://github.com/bevyengine/bevy-website/pull/754

1. Show, don't tell. Don't bombard people with information. Avoid large walls of text and large walls of code. Prefer the pattern "byte sized description of one thing" -> "example code/picture/video contextualizing that one thing" -> repeat. Take readers on a journey step by simple step.
2. Don't use up reader's "mental bandwidth" without good reason. We can't afford page-long descriptions of minor bug fixes. If it isn't a "headliner change", keep the description short and sweet. If a change is self describing, let it do that (ex: We now support this new mesh shape primitive ... this is what it looks like). If it is a "headliner change", still try to keep it reasonable. We always have a lot to cover.
3. In slight competition with point (2), don't omit interesting technical information when it is truly fun and engaging. A good chunk of our users are highly technical and enjoy learning how the sausage is made. Try to strike a balance between "terse and simple" and "nerdy details".
4. When relevant, briefly describe the problem being solved first, then describe the solution we chose. This contextualizes the change and gives the feature value and purpose.
5. When possible, provide visuals. They create interest / keep people hooked / break up the monotony.
6. Record images and videos at the default bevy resolution (1280x720)
7. Provide an accurate listing of authors that meaningfully contributed to the feature. Try to sort in order of "contribution scale". This is hard to define, but try to be fair. When in doubt, ask other contributors, SMEs, and/or maintainers.
8. Provide numbers and graphs where possible. If something is faster, use numbers to back it up. We don't (yet) have automated graph generation in blog post style, so send data / info to me (@cart) if you want a graph made.

[short lake]

@ancient summit ^

[forest anchor]

Point (8) is still a bit of an open question. I have yet to find a perfect solution

The method I've used in the past is laborious (Make graph in Libre Office calc, manually prune some details, export to SVG, open in inkscape, adjust color palette, remove background, convert text objects to curves, save)

It produces something that feels at home with the website style, but its 100x harder than it should be

[ancient summit]

Thanks for sharing this again! I've added it as additional info to the issue I've opened to help provide this context.

[ancient summit]

That definitely feels like something that should be automated...somehow.

[wise juniper]

Maybe point 6 should include "and without window decorations" per @hushed thistle

[forest anchor]

Agreed

[lethal urchin]

The voice was actually mostly Cart's! I've tried to follow it as I've helped 🙂

[undone crown]

Hello there, I have a simple question. I'm trying to write a release note for the Ui gizmos PR, but I'm not very used to the website. If I want to include a file in the release note (an image), where should I put the file?

[ancient summit]

I believe you include the image in the same folder that the release notes markdown files are in. I don't know that for certain, but I've seen at least 1 other PR do that and get merged, so you'd be in good company if it's a mistake!

[lethal urchin]

Yep, I think this is the best way for now

[undone crown]

Okay, I'll do just that, thanks!

[azure kestrel]

Let me know how you want to structure state-related release notes Alice,
I know you wanted to separate State Scope from Computed/Sub States,
but you also marked identity transitions and I'm not sure how you want to include that

[lethal urchin]

I think we do three sections back-to-back.

I was thinking:

1. Computed and sub states
2. Identity transitions
3. State scope

computed states does a good job reminding people of how states work, and the other features are more powerful with it

identity transitions is relatively minor, but deserves a tiny section

And then state scopes are a clear example of how these fancy state tools can be used in your game today

[azure kestrel]

Is it alright if I address all of those in a single PR?

[lethal urchin]

Yep!

[azure kestrel]

cool

[lethal urchin]

Just mark that you're fixing the issues

[azure kestrel]

There are no issues for 2 and 3

Should I make them?

[lethal urchin]

Oh lemme rerun the tool now

[lethal urchin]

Made, and generated https://github.com/bevyengine/bevy-website/pull/1349

[azure kestrel]

You sure the tool is working correctly?

Only state scoped entities issue was made

but you made 4 stubs

3*

[lethal urchin]

Hmm 🤔

[lethal urchin]

The #github feed shows them correctly

and I'm seeing them on the repo too

[azure kestrel]

Oh, I added state into the filter and forgot about it

sorry for the trouble

for some reason that didn't match the identity transitions issue, bit odd

[lethal urchin]

https://github.com/bevyengine/bevy-website/pull/1349 please review so I can merge this in 🙂

[short lake]

@lethal urchin not sure what's the best place to discuss the what's next section, but should the BRP also get a mention? I think it will be a pretty important building block for bevy

[vernal moss]

A on the horizon section could be interesting.

[short lake]

Isn't that the same thing? Or are you just proposing a more thematic name for the section?

[lethal urchin]

Yeah, we should toss in a line in the "what's next" section for it

[vernal moss]

I agree, and would like to see all kinds of in progress stuff highlighted (especially the current working groups)

[lethal urchin]

cc @plucky granite @analog yacht, just so you're aware

[vernal moss]

burp especally

[lethal urchin]

Yep, I've tried to add a section for most / all of them 🙂

[lethal urchin]

Discussing milestone planning: #ecs-dev message

[lethal urchin]

We're drawing close to closing the milestone out. I've listed how you can help here: #engine-dev message

[forest anchor]

Thanks! I'm pretty proud of the blog post tone. I'll note that there have been a number of times where you've course corrected me for not matching the right tone though. I think we're pretty in sync on "what it should sound like" and it has evolved as we've worked together

[lethal urchin]

Yeah, and I've seen the community start to pick it up in their release note PRs too now 🙂

I've filed https://github.com/bevyengine/bevy-website/issues/1354 complaining about the pain that is merging PRs into a single release note section under the current workflow

[short lake]

Yeah, I expected that to be a bit painful but manageable. I don't really have a good solution in mind though

[lethal urchin]

Yeah I think I have a design in mind

But let's finish this cycle out before we muck with the process more

(and then once the problems are ironed out a bit we can add more automation)

[short lake]

I'm always a bit worried of adding too much automation making things not flexible enough, but yeah, let's see how it goes first

[lethal urchin]

Yeah, I think I want to do a cycle or so of just running the command once a week by hand

Which should give us the confidence in the tool and process to try automating it

[lethal urchin]

https://github.com/bevyengine/bevy-website/pull/1364 needs a review: this is the last time I intend to run the release note tool this release

I also need to do a pass on the migration guide generator later today

@forest forge is planning to cut the release candidate branch tomorrow, and then we'll have a 2 week period to finish up notes and let authors port

[azure kestrel]

I've had my friend proof read the states release notes

There are some topics we could touch up, if not in the release noted, then in the docs themselves

[lethal urchin]

I quite like the edits you've made so far 🙂

If there's more detail needed, I'd prefer to try and add it to the docs, since that'll stick around

[azure kestrel]

gosh you're impatient xD

7 minutes of inactivity and i get a "Waiting On Author"

[lethal urchin]

I'm literally waiting! :p It was actually mostly because it's still in draft mode

[azure kestrel]

Yeah, I'm just checking whether the problems we found are described in docs

If not I'll add an issue

[lethal urchin]

👍

Much appreciated!

[azure kestrel]

Hm, I'm not sure why it's conflicting with main i just rebased found it

Seems to be mostly documented or visible in examples

PR rebased and ready for review

[lethal urchin]

Awesome

I'll take a look in a couple hours

I'm about to go AFK to do brunch with my not-quite-father-in-law

[azure kestrel]

Sure no hurry

[lethal urchin]

I've swapped the label though 😉

[obsidian peak]

I’m going to have a lot more free time in the next two weeks, so my focus is fully on the migration guide

I hope to finish it, though I would really like a friend to help too :)

[lethal urchin]

I'll be around and reviewing PRs at least!

@obsidian peak do you want to take a crack at generating the updated migration guide?

[short lake]

I'll definitely be helping more soon, but it's been nice to not have to do most of the grunt work myself this time around

[obsidian peak]

Sure, I’ll try it out!

[obsidian peak]

Hah, fair! Take your time and work on other exciting things :)

[lethal urchin]

Make sure to cross-reference the PR that removed some of the unhelpful ones

[obsidian peak]

Note to self: you need to cd into generate-release before running it, else it writes files outside of the project

I bet you could use the env! macro to fix that, or at least get the directory of the binary being run

[short lake]

How can you run it without that? Like, how do you call cargo from a non-cargo workspace?

[obsidian peak]

cargo run -p generate-release

That's what I usually do, so I spent 15 minutes debugging why nothing was happening

[short lake]

wait, that works? I assumed you needed a cargo workspace for that 😅

[obsidian peak]

It is a cargo workspace!

I actually submitted that PR

https://github.com/bevyengine/bevy-website/pull/978

[short lake]

Oooh, nice, I didn't know that was a thing so I've just been cd'ing into all those rust based tools

even more reason to fix that tool so it works correctly then

Wait but, why did you need to run generate-release? Aren't the files already generated?

[obsidian peak]

More PRs have been merged since then, so Alice asked that I regenerate them

[short lake]

nvm, just saw your PRs

[obsidian peak]

No worries :)

[hushed thistle]

I looked into whether it's possible to get zola to hot reload on changes to stuff in release-content. Seems like no, the list of paths it watches are hardcoded.

[short lake]

yeah, that's definitely annoying, not sure what to do about that

there's probably some kind of cli based file watcher that can automatically rerun zola serve on save

something like cargo watch

[hushed thistle]

yeah I'm sure that would work, will try fswatch in a bit

[grim socket]

https://github.com/bevyengine/bevy/pull/13692 should be fixed for the release.

[hushed thistle]

The JS part of the hot reload stuff doesn't happen when restarting the server. I managed to hack around this by creating/delete a file in content when release-content changes. Somehow couldn't get this to work through other means of modifying the content directory.

fswatch -0 -o release-content | xargs -0 -n1 -I{} sh -c 'touch content/test.md && rm content/test.md'

[plucky granite]

👀 (Catching up to old messages) I can help with the release notes, though @analog yacht has been carrying the torch so if they'd rather also write the section that's okay

[lethal urchin]

Yep 🙂 Maybe try to tackle it? pcwalton will have dozens of rendering features to review the notes of 😅

I'm going to try and draft them though for him: there's excellent starting material in the PR descriptions

[analog yacht]

I haven't had that much time lately

well, and motivation

[lethal urchin]

Added more to "what's next": https://github.com/bevyengine/bevy-website/pull/1369

[lethal urchin]

I didn't get to this today, but please prioritize other notes 🙂 This is my first task on Sunday

I've assigned those notes to myself now so y'all can track that easily

[pulsar terrace]

I'll try to get contextual gizmos some release notes today/early tomorrow, unsure of how much you want covering it since it's almost just a bug fix but I could put a gif of before and after for fixed update

[lethal urchin]

Let's just do a line or two 🙂

It's a bug fix, but a relatively impactful one

Although double check before you start writing @pulsar terrace : I remember reviewing a PR for it already

[pulsar terrace]

Ah gotcha, I'll take a look once i get home

[vernal moss]

Wow, lots of good(?) puns in the blog post already.

[lethal path]

Shame I can’t see it yet.

[glad osprey]

@lethal urchin One thought I had for future releases: to avoid generating lots of individual release notes for a feature with many PRs, you could have a special github comment such as followup: #1234 which would mark a PR as being a followup. The generator tool would then aggregate these into a single markdown file.

[short lake]

I really don't want to have to do even more github description parsing 😅, but that would solve that issue

[lethal urchin]

Yeah I think that the big thing to fix is PR agglomeration

[short lake]

That's what I liked with using a big markdown of everything. I could just deletes parts of it easily

[lethal urchin]

The problem comes when you try and regenerate it though

[short lake]

Git handled it mostly fine most of the time because it kept a fixed ordering, but it was really tedious to always have to remove the same sections every time

[obsidian peak]

You can view the draft at https://bevyengine.org/news/draft-bevy-0-14/ :)

[wise juniper]

Huh, the images seem broken. Is this because it’s a draft?
Edit: seems fixed now 🙂

[wise juniper]

I'm upgrading all of my crates to the RC today and will edit this post with my experiences so far.
I published an rc version for all migrated crates to that other devs can already port whatever project depends on my stuff.
Sidenote: I don't think I can create a sub-thread here, can I?

• bevy_wind_waker_shader:
  • Got a message about needing to enable nightly features for #[diagnostic], which confused me. Turns out my rustc was outdated, oops. Maybe we should mention that users need to bump their Rust version?
  • The rest of the migrations needed were already nicely documented 🙂 Most changes were Color related, and all of these were easily understandable and made sense to me.
• pixelate_mesh
  • VisibleEntities now differentiates the kind of entities it looks at. The guide tells me how to migrate when I want to examine VisibleEntities. But I'm actually interested in overriding it with my own list of entities! I'm now just inserting everything for TypeId::of::<WithMesh>() and hope that's fine? Note that VisibleEntities of has a push but no extend, so I have to touch the underlying entities directly. Not too bad, but a bit unwieldy. As for the bins used: the types highlighted in the migration guide, namely WithMesh2d, WithMesh, WithLight, and WithNode, don't seem to be mentioned in the actual Bevy docs. How am I supposed to know that I should be querying these types in particular as a new user? Did I miss something? Also: what should I do with entities that have both a Mesh and a kind of Light? Do they go in the WithMesh or the WithLight bin? @analog yacht, am I misunderstanding something here or could the docs be improved? I hope I don't sound harsh or anything, I'm just a bit confused 😄
  • RenderLayers seems to no longer be Copy. Simple fix, but I think it's missing from the migration guide.
• spew
  • The library itself needed no migrations whatsoever, just a simple version bump. Yay!
  • While running my examples, I ran into Panic when bevy_pbr feature is not included and In 0.14.0-rc.2, minimal app with bevy_core_pipeline crashes without ktx2, zstd, and bevy_pbr which were really unexpected as my examples are not graphical in nature. In fact, they don't even have a camera. Good thing other users already reported the issues so that I knew which features to depend on! Not going into too much detail here as I assume these will be fixed in time for 0.14.0
• bevy_sprite3d
  • Made by @heady quiver and not me, but needed for the Yarn Spinner for Rust demo
  • Lots of Color again, and using URect and UVec for UI stuff instead of the float versions. Very easy migration overall.
• Yarn Spinner for Rust
  • Lots of turning .world into .world[_mut](). Had some lifetime issues as a result, but nothing too tragic.
  • Pleasently surprised to see AssetLoader use native async fns now! There's a lot of lifetime boilerplate involved, but it's alright for now.
  • Took a moment to realize that Color::TOMATO is now in css::TOMATO.
  • Color::with_a is now Color::with_alpha, and Color::a() is now Color::alpha(). Simple fix, but I couldn't find it in the migration guide.
  • Ran into a UI issue detailed below in Discord
• Foxtrot
  • Impossible to migrate now because of all the dependencies used, but that's expected.

[forest forge]

my most painful updates (without reading the migration guide) was updating colors, and usually because it's in a lot of places. but it was just finding the correct regex to apply each time

[hushed thistle]

@wise juniper Excellent, thanks for sharing. Great feedback.

Maybe we should mention that users need to bump their Rust version?

We do, big yellow message at the top 🙂

Color::with_a is now Color::with_alpha, and Color::a() is now Color::alpha(). Simple fix, but I couldn't find it in the migration guide.

Color::a and Color::set_a are in there, but we should add with_a for sure.

[wise juniper]

Oh wow, you're right. Looks like I just mentally skipped it completely. Hard to say why after the fact, but I guess I was expecting it to say "This is only a draft!".

[vernal moss]

maybe we should make it flash

[wise juniper]

Or <blink> /s

[vernal moss]

an elegant weapon from a more civilized age

[hushed thistle]

My only personal current lingering issue is that the guide definitely doesn't seem adequate to figure out how the heck to migrate bevy_asset_loader, but most people are probably not doing such advanced things with states.

[wise juniper]

Without having looked into it: is it at least clear for new users coming to Bevy 0.14.0 how to setup this stuff?

[hushed thistle]

For normal users of states I think it is pretty straightforward / the changes are small.

[lethal urchin]

Yeah, the idea was "simple users of states should be completely unbroken"

[heady frigate]

I spent some time yesterday porting iyes_perf_ui and bevy-inspector-egui, colors where definitely the most annoying part. Especially because some places .into() couldn't figure out the type, so I had to switch between it and Color::from.

[vernal moss]

Any specific examples? We are not past adding more color conversion stuff (we just added StandardMaterial::from_color(color: impl Into<Color>))

[heady frigate]

I'll try to see if I can find some examples after work, the code is on my home pc. I think those 2 crates are also among the harder ones because they actually do interesting stuff with colors (e.g. color pickers)

[wise juniper]

Something weird just came up. The first image is Bevy 0.13.2, the second 0.14.0-rc.2. It's a bit hard to spot, but notice that the border of the textbox is now a bit more separated from the main square. There's a line now separating the black. I guess it doesn't matter too much since I can actually replace my images with a rounded corner box directly in the UI now, but still weird.

Looks like my three pictures "top border", "main text rect", and "bottom border" now have a pixel or so of margin inbetween them

[hushed thistle]

Opened an issue for one thing from bevy_ecs_tilemap.

Maybe @undone solstice has some more migration guide feedback from that process.

[hushed thistle]

Node rendering went through quite a few changes I think. Worth opening an issue if you can isolate it.

[lethal urchin]

There's a good chance that this is a spec compliance bug fix on taffy's end

One of the perils of flexbox is that correct and incorrect behavior are nearly indistinguishable for mere mortals, so you just end up twiddling until it works

[wise juniper]

Fair enough. I don't really want to isolate it right now since that seems fairly annoying. Should I open an issue or leave it? As I said, it's not impacting me because I can now use rounded corners directly.

[hushed thistle]

Wasn't too hard to reproduce, I'll open an issue.

[wise juniper]

Thanks! That was quick! 😄

[hushed thistle]

https://github.com/bevyengine/bevy/issues/13807

[wise juniper]

Alright, done now. Some final thoughts:

• It's very nice to have an RC period! Thanks for implementing the community feedback!
• The WIP migration guide covered most things I needed. I noted the exceptions in my post above, but keep in mind that I did not highlight all the changes that were nicely documented, which is most of them. Good job, everyone!
• I had some weird behaviour while changing from a flexbox to a grid, see here. @floral fjord and me experimented a bit, and in our opinion, the UI linked should look the exact same without overriding grid_auto_rows, but it currently does not. Note that when executing the equivalent CSS in a browser, the layout looks the same when leaving grid_auto_rows at its default. I have no idea if this is related to Bevy 0.14 nor do I know much about CSS grid in general. Or CSS. Or layouts. So I can't really comment much on this.

[wise juniper]

Is there an official stance on how I should publish plugins updated to the RC? Currently, I have published them all to crates.io with an RC version of my own, but I've seen others just having a dedicated branch on git.

[lethal urchin]

Mild preference for a crates.io release

[vernal moss]

I would say that if you already keep your plugin minor version in lock-step with the bevy release, then keep your rc in lock-step too. So for rc2 release an rc2 of your own, and if we do an rc3 release an rc3.

[lethal urchin]

With matching rc numbers

[wise juniper]

oh well, they're all -rc without the .2 now 😄

I'll keep it in mind for next time

[vernal moss]

I'll add a section on the contributing book topic on this.

Speaking of which, I need to finalize and publish my edits.

[winged meteor]

For the VisibleEntities issue, the migration guide suggests adding your own check_visibility system. Would that make sense in this case?

[wise juniper]

I've got a Bevy dependency table in all of my readmes anyways, so at least there shouldn't be any confusion there for users

[wise juniper]

I don't think so, since I'm not interested in adding any "new type of renderable entity" and also don't need to run any new visibility checks. The thing I need is to be able to say "I want these exact entities to be visible". Take this with a grain of salt; I don't fully understand the changes.

[wise juniper]

Talking about it, should I have been doing a lockstep? I currently start all of my plugins at 0.1.0 and then bump them every time there is a Bevy release, e.g.

Bevy -> My Plugin
---
0.12 -> 0.1
0.13 -> 0.2
0.14 -> 0.3

Should instead be doing the following?

Bevy -> My Plugin
---
0.12 -> 0.12
0.13 -> 0.13
0.14 -> 0.14

Sorry for mild off-topic

[vernal moss]

I reviewed this at the time and still think I have a pretty good handle on this. Give me a sec to look it over again.

But I'm actually interested in overriding it with my own list of entities!
Like completely? You had your own way of adding lights and ui elements to VisibleEntities::entities?

What were you doing before?

[wise juniper]

Phew, been a while since I implemented it. Lemme check 🙂

Okay, the relevant code is here. I think lights are erroneously missing right now, but the idea is that the camera in question should only show the entities that have the pixelation effect applied. In hindsight, this should probably be more of a filter than a complete reset.

[lethal urchin]

I don't: it's too limiting

[vernal moss]

So VisibleEntities::entities is pub TypeIdMap<Vec<Entity>>. Seems like you should be able to just grab entities.get::<WithMesh>() and then filter that vector.

[forest forge]

you can if you want, but at some point you'll want to do a breaking change and you'll end up desynced or have to wait to release it with the Bevy update...
and if possible I would recommend to release breaking changes in independent versions, otherwise your users have to update for Bevy breaking changes and yours at the same time

[vernal moss]

Also good content for the contributing book

[wise juniper]

That makes sense, thanks! I'll try it out later 🙂 Did I see it correctly that WithMesh, WithMesh2D, WithLight and WithNode are not currently highlighted in the docs?

I've got an issue now while publishing my crates: "the trait Deserialize<'_> is not implemented for bevy_ecs::entity::Entity". I feel like this has something to do with the crate in question enabling very few bevy features. Maybe I need to enable a new one? bevy/serialize is already on.

[wise juniper]

That points towards not keeping lockstep, right?

[vernal moss]

Yeah, docs could use a pass.

[forest forge]

yes!

[vernal moss]

I think it would be ok to add VisibleEntities::filter<QF>(&mut self, Fn(Entity) -> bool)

Mm no I think that closure would have issues

well anyway, there should be a blessed way to do this.

Oh, and why aren't you using render layers?

[wise juniper]

Because IIRC there is one such camera per pixelated object. This means that each camera would have its own render layer, which did not seem feasable for dozens of entities.

[vernal moss]

i need to look at your code more closely

[wise juniper]

Hey, I barely understand what I did there myself 😄

[wise juniper]

This goes away when I enable all default features. Now toggling them out one-by-one until I find the one that I need.

[lethal urchin]

and if possible I would recommend to release breaking changes in independent versions, otherwise your users have to update for Bevy breaking changes and yours at the same time
Yep, that's my plan for LWIM this release

[wise juniper]

Turns out I needed to enable bevy_scene. This is not obvious from the error message and I did not see anything related on the migration guide. Not sure if there's already an issue for this. Should I open one?

[undone solstice]

this fix was already merged I believe: https://github.com/bevyengine/bevy/pull/13740 I ran into the same updating some other crates

[wise juniper]

Ah, good to know 😄 thx!

[undone solstice]

I didn't really use the migration guides unless they were in the PRs directly. I already had a pretty good cache in my head of the PRs that went in over the last few months because of the thisweekinbevy work, so I just did a quick find-via-search in the github ui and checked them to look at the changes. that's why the ecs_tilemap PR has all the links (https://github.com/StarArawn/bevy_ecs_tilemap/pull/537).

Biggest upgrade slowdown for me was running into the bugs for serialize and the extra ktx/etc features, which seems like the rc process working as intended in terms of discovering them. (https://github.com/bevyengine/bevy/issues/13728).

Other than that, there's a long-tail that's kind of awkward. The app I'd like to upgrade to the rc requires seldom_state, which in turn requires leafwing-input-manager, which in turn requires bevy_egui, etc. Each of those kind of needs one of the -rc releases before the next can -rc release so "testing the bevy rc" on apps with these kind of dependency chains isn't really going to happen before the real release it seems.

[lethal urchin]

Yeah. Which is part of why I'm trying to strip out dependencies like that in my crates, and move more core elements upstream

[hushed thistle]

Yeah, I can get a few of my simpler apps going once bevy_asset_loader is migrated, but I'm also stuck at the first level of deps. Still have extremely positive feelings about the RC process.

I attempted it but it wasn't going well and I know nikl said they planned on doing it so I haven't tried again.

[heady frigate]

Ok, after looking through it again it wasn't that bad, just 2 minor things:

• I don't like the sentence Call .into() on them to convert them into a Color for quick debugging use in the color migration, as it felt like I was doing something wrong when porting a bunch of color constants. I would replace this with something like: You can convert these into Color using .into() or Color::from().. It would also be nice with a sentence or two motivating this change and when to use the different types in the migration guide, even though this will probably be in the blog post.
• Some places I needed to change a T: States bound into T: FreelyMutableState, which was easy enough to guess from the error message but wasn't mentioned in the guide

[vernal moss]

Amazing, thank you so much this is great feedback

[undone solstice]

imo bevy_asset_loader is a second-order dep in that scenario because of the bevy_common_assets dependency (and iyes_progress).

totally agree that the rc has been a great thing as well

[hushed thistle]

argh, I forgot about the iyes_progress dep there. bevy_common_assets has an rc release.

indeed, https://github.com/IyesGames/iyes_progress/pull/29#issuecomment-2156709116

[heady frigate]

I'm not sure I agree releasing rc versions for plugins is necessary, it seems like it's just going to stress people out because they're holding back the dependency graph. From a user perspective as soon as there is a PR on all my dependencies then I'm unblocked, and if a sub-dependency has a PR you can temporarily use a [patch] until it gets merged / released.

Do the rc releases work out of the box when 0.14 comes out, or does that require a new release?

[short lake]

I'm not sure I understand your point about holding back the dependency graph

[heady frigate]

For example the comment on the iyes_progress PR about "hey, please do a release so this other crate can release"

[undone solstice]

I just took a look at iyes_progress. Mostly seems straightforward (needs a new dep on bevy_state) and the addition of + FreelyMutableState for setting. The bevy_main PR from 3 weeks ago seems like a lot more changes than that though

maybe its just github showing the diff weirdly

ah no, the tests did end up failing on the state schedule changes

[heady frigate]

Ok, I'm having the weirdest issue porting bevy-inspector-egui. It has a check like this:

fn build(&self, app: &mut bevy_app::App) {
    if app.is_plugin_added::<Self>() {
        return;
    }

but when running the examples this always evaluates to true.

If I remove the check it crashes because some glam types aren't present in the type registry:

fn add_raw<T: 'static>(
    type_registry: &mut TypeRegistry,
    fn_mut: InspectorEguiImplFn,
    fn_readonly: InspectorEguiImplFnReadonly,
    fn_many: InspectorEguiImplFnMany,
) {
    type_registry
        .get_mut(TypeId::of::<T>())
        .unwrap_or_else(|| panic!("{} not registered", std::any::type_name::<T>()))
        .insert(InspectorEguiImpl::new(fn_mut, fn_readonly, fn_many));
}

    ...
    add_raw::<bevy_math::UVec2>(type_registry, glam_impls::uvec2_ui, glam_impls::uvec2_ui_readonly, glam_impls::uvec2_ui_many);
    add_raw::<bevy_math::UVec3>(type_registry, glam_impls::uvec3_ui, glam_impls::uvec3_ui_readonly, glam_impls::uvec3_ui_many);
    // add_raw::<bevy_math::UVec4>(type_registry, glam_impls::uvec4_ui, glam_impls::uvec4_ui_readonly, glam_impls::uvec4_ui_many);
    add_raw::<bevy_math::IVec2>(type_registry, glam_impls::ivec2_ui, glam_impls::ivec2_ui_readonly, glam_impls::ivec2_ui_many);
    // add_raw::<bevy_math::IVec3>(type_registry, glam_impls::ivec3_ui, glam_impls::ivec3_ui_readonly, glam_impls::ivec3_ui_many);
    // add_raw::<bevy_math::IVec4>(type_registry, glam_impls::ivec4_ui, glam_impls::ivec4_ui_readonly, glam_impls::ivec4_ui_many);
    add_raw::<bevy_math::DVec2>(type_registry, glam_impls::dvec2_ui, glam_impls::dvec2_ui_readonly, glam_impls::dvec2_ui_many);
    // add_raw::<bevy_math::DVec3>(type_registry, glam_impls::dvec3_ui, glam_impls::dvec3_ui_readonly, glam_impls::dvec3_ui_many);
    // add_raw::<bevy_math::DVec4>(type_registry, glam_impls::dvec4_ui, glam_impls::dvec4_ui_readonly, glam_impls::dvec4_ui_many);
    ...

Each line above that are commented out crashes with the "type not registered error", the others work just fine

Maybe the reflection-dev channel is better for this unless someone here has any clue what could cause this

[ionic stirrup]

Hm, could this be related to
https://github.com/bevyengine/bevy/pull/13520

idk much about reflection so i cant really help, but seeing those are bevy_math (re-exported) types, this PR comes to mind

[heady frigate]

Hmm maybe, it doesn't seem to touch the glam types though. But it's a good guess

[wise juniper]

Refactored it according to your suggestions and it works like a charm. Thanks! 🙂

[heady frigate]

@lethal urchin I figured out my issue: after https://github.com/bevyengine/bevy/pull/5781 (or perhaps later) a bunch of glam types are no longer registered. Only those that are registered through another type are now. This is a regression from 0.13 which makes it impossible to update bevy-inspector-egui

[lethal urchin]

You should be able to manually register these externally

cc @rocky rover

[heady frigate]

Oh, if it's intended then it should just get a note in the migration guide I think

[lethal urchin]

Yep, I think so 🙂

[heady frigate]

Do you know which PR the registration was removed in? It wasn't in the one I linked, that's just the one that makes it work. And it's a bit hard to search for on github

[lethal urchin]

Not off-hand. Just add it to the notes for #5781 please?

[heady frigate]

If we're certain that it was deliberate and not accidental then sure

[lethal urchin]

Lemme double check what the math folks did...

[heady frigate]

It's just feels weird to me to actively remove the register_type call for e.g. UVec4, just because it isn't actively used in any bevy structs

So I'd like to find the PR where that happened

[lethal urchin]

Are you able to find where this was being done in 0.13? My initial searches aren't showing anything

https://github.dev/bevyengine/bevy/tree/v0.13.2 is useful

[heady frigate]

Let me check. It kinda has to be though because the crate worked before, and it's assuming all glam types are present

[lethal urchin]

Yeah 🙂

If we can find where it was being done, we can look at the per-file commit history

[heady frigate]

@lethal urchin here: https://github.com/bevyengine/bevy/blob/release-0.13.2/crates/bevy_core/src/lib.rs

[lethal urchin]

Which yields https://github.com/bevyengine/bevy/pull/12314

[heady frigate]

yep, that should go in the changelog, I'll make a PR

[lethal urchin]

Great 😄

[heady frigate]

Another difference I found: it seems like app.is_plugin_added::<Self>() always returns true now (i.e. the plugin is always considered added inside it's own build function). I'm not sure if that is intended? The old behavior seems better to me at first glance

[lethal urchin]

I would call that a bug. Can you open an issue or PR please?

[heady frigate]

https://github.com/bevyengine/bevy/issues/13815

[lethal urchin]

Thanks!

[obsidian peak]

Create an issue for these on the website, and I’ll take a look at them :)

[heady frigate]

I'll probably just do it myself tomorrow, got through the other issues I had today

[rocky rover]

Oof yeah this was one of the potential problems with recursive registration. Things won’t get auto registered unless you register something that depends on it. So this PR should have been marked as a breaking change and given a migration guide

[obsidian peak]

Ping me when you do, I’ll approve it!

[heady frigate]

I added one: https://github.com/bevyengine/bevy-website/pull/1388. It was definitely confusing because I had vaguely followed the recursive registration PR, but not seen the cleanup one xD

So I was like "what do you mean only half of glam types are in the registry?!"

[obsidian peak]

Hey everyone! Could I please have some help working on the migration guide? I'm only 15% of the way done, and I worry that I won't finish in time before Bevy 0.14 releases. I'm hoping for 1, maybe 2 other people. We can split up sections and review each other's writing

This work involves going through each breaking change PR and updating the corresponding migration guide for consistency and clearness

With just me, I worry that I'll end up rushing in the end and the quality of the writing will degrade. If I had some more help, we can split the bulk of the writing and hold to the standards

[lethal urchin]

Don't rush, we'll bump the release back as needed to get this in a good state

But yes, more help would be much appreciated

[hushed thistle]

21 PRs merged from 10 authors/co-authors affecting the 0.14/migration-guides directory. This is a major success compared to the state of the guide pre-release for every other release. Probably.

I'll continue helping when I can but I won't be stressing myself about it like in previous cycles.

[undone solstice]

is it just updating the stubs in the migration guides directory for the relevant PR?

[obsidian peak]

Yes, but there's a bit more than that. It's expanding on the original migration guide the PR author wrote, adding examples, explanations, and making sure the migration guide is correct

For instance sometimes things get reverted later. You sometimes need to check that the advice given still applies :)

[hushed thistle]

https://github.com/bevyengine/bevy-website/issues/1386 would be a cool one to start on -- I don't actually want to learn about that ^^

[vernal moss]

I have limited time this week but I will see what I can do

[obsidian peak]

No worries! Alice's comment mostly alleviates my stress :)

[lethal urchin]

We're going to want to do at least one more release candidate as well

There's too many issues / too high of impact

[vernal moss]

Good

[short lake]

And none of them are from me! I wanted to help more, but I'm really happy I didn't actually have to touch anything this release. Or at least, I'm happy the tools I built worked correctly.

[gray moat]

Updating bevy_framepace and hitting

Failed to load SMAA area LUT: UnsupportedTextureFormat("Ktx2")

Seems like a feature is required that wasn't previously.

[bronze stream]

https://github.com/bevyengine/bevy/issues/13728

[gray moat]

Thanks

Found a new, even more exciting crash:

Encountered a mismatched World. This SystemState was created from WorldId(0), but a method was called using WorldId(1).

What now.

Huh.

Resource requested by bevy_core_pipeline::core_3d::extract_camera_prepass_phase does not exist: bevy_render::render_phase::ViewBinnedRenderPhases<bevy_core_pipeline::prepass::Opaque3dPrepass

Might be related, the bevy_pbr feature.

ah, yup https://github.com/bevyengine/bevy/issues/13571

[lethal urchin]

https://github.com/bevyengine/bevy/issues/13825

Lessons for next time: no refactoring work during release candidates T_T

[heady frigate]

Seems like a solid rule, then the people refactoring also have more time to do bug fixes and release notes 😄

[forest forge]

the other option is to revert the refactoring PR...

[lethal urchin]

Yes, but I don't think that actually makes things easier at this point

[forest forge]

well a bit too late as I think the two other PRs have updated after it

[glad osprey]

@lethal urchin I've been doing most of my recent development work depending on Bevy mainline. This includes using a forked version of bevy_mod_picking which updates the dependencies. If I wanted to switch over to the release candidate, is there a way I can use the upstreamed picking now?

[lethal urchin]

No: there's no upstreaming in 0.14

[vernal moss]

my pr hasn't even been merged yet because i havn't had time to fix ci 😭

tonight 100% for sure I will

[soft estuary]

On mac while updating bevy_rapier I noticed that closing the window does not exit the program ; I didn’t look much further but I reproduce it 100% on my branch

(I assume this is the thread for discussing the release candidate ?)

[lethal urchin]

Yep

[lethal urchin]

Hmm that seems like a bug yes

[soft estuary]

Can’t create a thread again so I’ll just post more info about the reproduction: https://github.com/dimforge/bevy_rapier/pull/523 ; example boxes3 on mac doesn’t exit when closing the window, I can open an issue on bevy repo 🙂

[lethal urchin]

Yep issue on the repo please

[forest forge]

not on Rapier, but Bevy examples closes correctly on macOS when closing the window

could you try pointing at the release-0.14.0 branch of Bevy instead of the rc? could be fixed by https://github.com/bevyengine/bevy/pull/13744

[soft estuary]

I gave it more try and I think that came from a misunderstanding on my end, I kept an addition of system event_update_system (which I believe is now not needed because inferred from the event register) ; when removing that extra system, the program exits normally 🎉