Better release notes.

bake.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+# Update the project documentation with the new version number.
+#
+# @parameter version [String] The new version number.
+def after_gem_release_version_increment(version)
+	context['releases:update'].call(version)
+	context['utopia:project:readme:update'].call
+end

gems.rb

@@ -16,6 +16,7 @@
 	gem "bake-modernize"
 
 	gem "utopia-project"
+	gem "bake-releases"
 end
 
 group :test do

readme.md

@@ -31,6 +31,17 @@ Please see the [project documentation](https://socketry.github.io/async/) for mo
 
   - [Debugging](https://socketry.github.io/async/guides/debugging/index) - This guide explains how to debug issues with programs that use Async.
 
+## Releases
+
+## See Also
+
+  - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.
+  - [async-websocket](https://github.com/socketry/async-websocket) — Asynchronous client and server websockets.
+  - [async-dns](https://github.com/socketry/async-dns) — Asynchronous DNS resolver and server.
+  - [falcon](https://github.com/socketry/falcon) — A rack compatible server built on top of `async-http`.
+  - [rubydns](https://github.com/ioquatix/rubydns) — An easy to use Ruby DNS server.
+  - [slack-ruby-bot](https://github.com/slack-ruby/slack-ruby-bot) — A client for making slack bots.
+
 ## Contributing
 
 We welcome contributions to this project.
@@ -48,12 +59,3 @@ In order to protect users of this project, we require all contributors to comply
 ### Community Guidelines
 
 This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.
-
-## See Also
-
-  - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.
-  - [async-websocket](https://github.com/socketry/async-websocket) — Asynchronous client and server websockets.
-  - [async-dns](https://github.com/socketry/async-dns) — Asynchronous DNS resolver and server.
-  - [falcon](https://github.com/socketry/falcon) — A rack compatible server built on top of `async-http`.
-  - [rubydns](https://github.com/ioquatix/rubydns) — An easy to use Ruby DNS server.
-  - [slack-ruby-bot](https://github.com/slack-ruby/slack-ruby-bot) — A client for making slack bots.

releases.md

@@ -0,0 +1,24 @@
+# Changes
+
+## Next
+
+### Better Handling of Async and Sync in Nested Fibers
+
+Interleaving bare fibers within `Async` and `Sync` blocks should not cause problems, but it presents a number of issues in the current implementation. Tracking the parent-child relationship between tasks, when they are interleaved with bare fibers, is difficult. The current implementation assumes that if there is no parent task, then it should create a new reactor. This is not always the case, as the parent task might not be visible due to nested Fibers. As a result, `Async` will create a new reactor, trying to stop the existing one, causing major internal consistency issues.
+
+I encountered this issue when trying to use `Async` within a streaming response in Rails. The `protocol-rack` [uses a normal fiber to wrap streaming responses](https://github.com/socketry/protocol-rack/blob/cb1ca44e9deadb9369bdb2ea03416556aa927c5c/lib/protocol/rack/body/streaming.rb#L24-L28), and if you try to use `Async` within it, it will create a new reactor, causing the server to lock up.
+
+Ideally, `Async` and `Sync` helpers should work when any `Fiber.scheduler` is defined. Right now, it's unrealistic to expect `Async::Task` to work in any scheduler, but at the very least, the following should work:
+
+```ruby
+reactor = Async::Reactor.new # internally calls Fiber.set_scheduler
+
+# This should run in the above reactor, rather than creating a new one.
+Async do
+  puts "Hello World"
+end
+```
+
+In order to do this, bare `Async` and `Sync` blocks should use `Fiber.scheduler` as a parent if possible.
+
+See <https://github.com/socketry/async/pull/340> for more details.