felixrabe · June 21, 2019 20:17 · Jun 21, 2019 · Jun 21, 2019 · Jun 21, 2019 · Jun 21, 2019
diff --git a/020.md b/020.md
@@ -82,7 +82,7 @@ If you are interested in Rust becoming a larger force in graphics ecosystem, ple
 issues below and find one you can contribute to! We encourage all types of contributions, so go out and
 write, test, review, and submit PRs, add and review documentation, and whatever else you would like to
 do. No matter what you do, your time would be very much appreciated, and would result in widespread
-improvements across the Rust community.
+improvements across the Rust GUI community.
 
 ## High-level issues:
 

diff --git a/020.md b/020.md
@@ -70,9 +70,9 @@ However, we lack the personnel necessary to implement those changes!
 ## A call for help
 
 That segues nicely into the second point I'd like to bring up: for such a core piece of infrastructure
-in the Rust ecosystem, we have astonishingly little manpower. Only three of the seven platforms we support
-have active maintainers: X11, macOS, Android, iOS, and WASM are all largely unmaintained, despite their
-importance! Additionally, Glutin is currently maintained by just a *single* person, despite being a project
+in the Rust ecosystem, we have astonishingly little manpower. Four *(TODO: five?)* of the seven platforms we support
+lack active maintainers: X11, macOS, Android, iOS, and WASM are all largely unmaintained.
+Additionally, Glutin is currently maintained by just a *single* person, despite being a project
 no lone individual has the time to handle. This had led to a great deal of issue buildup on those platforms,
 since we lack contributors with enough time to debug and resolve issues on those platforms. Major new features
 and API improvements can't land on `crates.io` since we currently can't implement them across all platforms -

diff --git a/020.md b/020.md
@@ -56,7 +56,7 @@ event_loop.run(move |event, _, control_flow| {
 });
 ```
 
-This release also cleans up Winit's API, universally improving both its internal consistency and its
+This release also cleans up Winit's API, improving both its internal consistency and its
 consistency with the rest of the Rust ecosystem.
 
 ## Why an Alpha release?

diff --git a/020.md b/020.md
@@ -34,7 +34,7 @@ let timer_length = Duration::from_secs(1);
 
 event_loop.run(move |event, _, control_flow| {
     match event {
-        // When the event loop initially starts up, queue the timer.
+        // When the event loop starts running, queue the timer.
         Event::NewEvents(StartCause::Init) => {
             *control_flow = ControlFlow::WaitUntil(Instant::now() + timer_length);
         },

diff --git a/020.md b/020.md
@@ -30,7 +30,7 @@ let event_loop = EventLoop::<CustomEvent>::new_user_event();
 // to the Winit event loop from any thread.
 let event_loop_proxy = event_loop.create_proxy();
 
-let timer_length = Duration::new(1, 0);
+let timer_length = Duration::from_secs(1);
 
 event_loop.run(move |event, _, control_flow| {
     match event {

diff --git a/020.md b/020.md
@@ -16,7 +16,8 @@ the project.
 
 The highlight of this release is a major overhaul of Winit's Event Loop API. This
 change vastly improves Winit's stability and introduces quality-of-life upgrades, such as
-native timer support and an API for injecting custom user events into the Winit event loop. For example:
+native timer support and an API for injecting custom user events into the Winit event loop.
+For example: *(TODO: Link to full example on GitHub.)*
 
 ```rust
 #[derive(Debug, Clone, Copy)]

diff --git a/020.md b/020.md
@@ -26,7 +26,7 @@ enum CustomEvent {
 
 let event_loop = EventLoop::<CustomEvent>::new_user_event();
 // `EventLoopProxy` allows dispatching custom events
-// to the main Winit event loop from any thread.
+// to the Winit event loop from any thread.
 let event_loop_proxy = event_loop.create_proxy();
 
 let timer_length = Duration::new(1, 0);

diff --git a/020.md b/020.md
@@ -25,8 +25,8 @@ enum CustomEvent {
 }
 
 let event_loop = EventLoop::<CustomEvent>::new_user_event();
-// `EventLoopProxy` allows you to dispatch custom events to the main Winit event
-/// loop from any thread.
+// `EventLoopProxy` allows dispatching custom events
+// to the main Winit event loop from any thread.
 let event_loop_proxy = event_loop.create_proxy();
 
 let timer_length = Duration::new(1, 0);

diff --git a/020.md b/020.md
@@ -9,7 +9,8 @@ programming in Rust using Glutin (or dependent projects including gfx-rs, Glium,
 we've been the ones making the windows actually show up on your desktop.
 
 This announcement details the major changes since Winit 0.19. Also, we are looking for new contributors!
-Now is a good time to join the project, read on for details.
+If you are interested in working on the foundations of Rust's GUI story, now is a great time to join
+the project.
 
 ## The new event loop
 

diff --git a/020.md b/020.md
@@ -1,3 +1,5 @@
+# Winit 0.20 Alpha 1
+
 Hello, all!
 
 I'm one of the maintainers of Winit, the main pure-Rust window creation library. Even if
@@ -6,9 +8,10 @@ Alacritty being the best-known applications that depend on our codebase. If you'
 programming in Rust using Glutin (or dependent projects including gfx-rs, Glium, and Amethyst)
 we've been the ones making the windows actually show up on your desktop.
 
-There are a few important announcements I'd like to make:
+This announcement details the major changes since Winit 0.19. Also, we are looking for new contributors!
+Now is a good time to join the project, read on for details.
 
-# Winit 0.20 alpha 1 and the new event loop
+## The new event loop
 
 The highlight of this release is a major overhaul of Winit's Event Loop API. This
 change vastly improves Winit's stability and introduces quality-of-life upgrades, such as
@@ -62,7 +65,7 @@ There are a few reasons we're introducing this as an alpha:
 
 However, we lack the personnel necessary to implement those changes!
 
-# A call for help
+## A call for help
 
 That segues nicely into the second point I'd like to bring up: for such a core piece of infrastructure
 in the Rust ecosystem, we have astonishingly little manpower. Only three of the seven platforms we support
@@ -93,10 +96,10 @@ improvements across the Rust community.
     - Android
     - iOS
 
-# FAQ
+## FAQ
 
 
-## Why remove `poll_events` completely?
+### Why remove `poll_events` completely?
 
 `poll_events` only functions as expected on Linux.
 
@@ -116,7 +119,7 @@ amounts of stability and UX problems, and moving to the new event loop model is
 fix those issues without creating an unstable tower of hacks.</sup>
 
 
-## Since `poll_events` is dead, is there any sort of replacement?
+### Since `poll_events` is dead, is there any sort of replacement?
 
 Yep! The `run_forever` API has been renamed to `run`, and received a few major usability upgrades:
 1. You now receive an event when the platform event queue has been drained, allowing you to bundle
@@ -130,7 +133,7 @@ These new features make `run` actually usable in a real application, and should
 for `poll_events`' removal.
 
 
-## Why does the new `run` function not return?
+### Why does the new `run` function not return?
 
 It was the only way for us to expose a single API that more or less behaves the same way on all
 platforms.
@@ -145,7 +148,7 @@ necessary, since it breaks cross-platform compatibility and can lead to subtle b
 platforms if used improperly.
 
 
-## Why break the API's backwards compatibility now?
+### Why break the API's backwards compatibility now?
 
 There were several small details in Winit's public API that we weren't happy with, but required
 breaking changes to fix. Since we were already breaking downstream applications with the new event

diff --git a/020.md b/020.md
@@ -9,8 +9,9 @@ we've been the ones making the windows actually show up on your desktop.
 There are a few important announcements I'd like to make:
 
 # Winit 0.20 alpha 1 and the new event loop
-The highlight of this release is the final major overhaul of Winit's core Event Loop API. This
-change vastly improving Winit's stability and introduces a few quality-of-life upgrades, such as
+
+The highlight of this release is a major overhaul of Winit's Event Loop API. This
+change vastly improves Winit's stability and introduces quality-of-life upgrades, such as
 native timer support and an API for injecting custom user events into the Winit event loop. For example:
 
 ```rust
@@ -79,6 +80,7 @@ do. No matter what you do, your time would be very much appreciated, and would r
 improvements across the Rust community.
 
 ## High-level issues:
+
 - [Sign up on a testing list for any platform we support](https://github.com/rust-windowing/winit/wiki/Testers-and-Contributors)
 - [Gamepad support on all non-Windows platforms:](https://github.com/rust-windowing/winit/issues/944)
 - [X11 bugfixing](https://github.com/rust-windowing/winit/issues?utf8=%E2%9C%93&q=is%3Aopen+label%3A%22platform%3A+X11%22+label%3A%22type%3A+bug%22)

diff --git a/020.md b/020.md
@@ -1,7 +1,7 @@
 Hello, all!
 
 I'm one of the maintainers of Winit, the main pure-Rust window creation library. Even if
-you haven't used it directly, you've probably heard of projects that depends on it - Servo and
+you haven't used it directly, you've probably heard of projects that depend on it - Servo and
 Alacritty being the best-known applications that depend on our codebase. If you've done any graphics
 programming in Rust using Glutin (or dependent projects including gfx-rs, Glium, and Amethyst)
 we've been the ones making the windows actually show up on your desktop.

diff --git a/020.md b/020.md
@@ -1,6 +1,6 @@
 Hello, all!
 
-I'm one of the maintainers of Winit, the main pure-Rust window creation library written. Even if
+I'm one of the maintainers of Winit, the main pure-Rust window creation library. Even if
 you haven't used it directly, you've probably heard of projects that depends on it - Servo and
 Alacritty being the best-known applications that depend on our codebase. If you've done any graphics
 programming in Rust using Glutin (or dependent projects including gfx-rs, Glium, and Amethyst)

diff --git a/020.md b/020.md
@@ -79,22 +79,18 @@ do. No matter what you do, your time would be very much appreciated, and would r
 improvements across the Rust community.
 
 ## High-level issues:
-- Sign up on a testing list for any platform we support: https://github.com/rust-windowing/winit/wiki/Testers-and-Contributors
-- Gamepad support on all non-Windows platforms.
-- X11 bugfixing (link to list)
-- macOS bugfixing (link to list)
-- Android's Eventloop 2.0 implementation
+- [Sign up on a testing list for any platform we support](https://github.com/rust-windowing/winit/wiki/Testers-and-Contributors)
+- [Gamepad support on all non-Windows platforms:](https://github.com/rust-windowing/winit/issues/944)
+- [X11 bugfixing](https://github.com/rust-windowing/winit/issues?utf8=%E2%9C%93&q=is%3Aopen+label%3A%22platform%3A+X11%22+label%3A%22type%3A+bug%22)
+- [macOS bugfixing](https://github.com/rust-windowing/winit/issues?utf8=%E2%9C%93&q=is%3Aopen+label%3A%22platform%3A+macOS%22+label%3A%22type%3A+bug%22+)
+- [Android's Eventloop 2.0 implementation](https://github.com/rust-windowing/winit/issues/948)
 - iOS features and bugfixing (link)
 - Maintainers for the following platforms:
     - macOS
     - X11
     - Android
     - iOS
 
-## Nitty-gritty problems:
-
-(embed https://gist.github.com/Osspial/fddc1fdcbd65a0f6510c9669b21b4901)
-
 # FAQ
 
 

diff --git a/020.md b/020.md
@@ -0,0 +1,160 @@
+Hello, all!
+
+I'm one of the maintainers of Winit, the main pure-Rust window creation library written. Even if
+you haven't used it directly, you've probably heard of projects that depends on it - Servo and
+Alacritty being the best-known applications that depend on our codebase. If you've done any graphics
+programming in Rust using Glutin (or dependent projects including gfx-rs, Glium, and Amethyst)
+we've been the ones making the windows actually show up on your desktop.
+
+There are a few important announcements I'd like to make:
+
+# Winit 0.20 alpha 1 and the new event loop
+The highlight of this release is the final major overhaul of Winit's core Event Loop API. This
+change vastly improving Winit's stability and introduces a few quality-of-life upgrades, such as
+native timer support and an API for injecting custom user events into the Winit event loop. For example:
+
+```rust
+#[derive(Debug, Clone, Copy)]
+enum CustomEvent {
+    Timer,
+}
+
+let event_loop = EventLoop::<CustomEvent>::new_user_event();
+// `EventLoopProxy` allows you to dispatch custom events to the main Winit event
+/// loop from any thread.
+let event_loop_proxy = event_loop.create_proxy();
+
+let timer_length = Duration::new(1, 0);
+
+event_loop.run(move |event, _, control_flow| {
+    match event {
+        // When the event loop initially starts up, queue the timer.
+        Event::NewEvents(StartCause::Init) => {
+            *control_flow = ControlFlow::WaitUntil(Instant::now() + timer_length);
+        },
+
+        // When the timer expires, dispatch a timer event and queue a new timer.
+        Event::NewEvents(StartCause::ResumeTimeReached{..}) => {
+            event_loop_proxy.send_event(CustomEvent::Timer).ok();
+            *control_flow = ControlFlow::WaitUntil(Instant::now() + timer_length);
+        },
+
+        Event::UserEvent(event) => println!("user event: {:?}", event),
+
+        Event::WindowEvent { event: WindowEvent::CloseRequested, .. } => {
+            *control_flow = ControlFlow::Exit;
+        },
+
+        _ => ()
+    }
+});
+```
+
+This release also cleans up Winit's API, universally improving both its internal consistency and its
+consistency with the rest of the Rust ecosystem.
+
+## Why an Alpha release?
+
+There are a few reasons we're introducing this as an alpha:
+1. All implementations still need thorough testing, and some platforms still have major, application-breaking bugs.
+2. We'd like to merge an overhaul of Winit's HiDPI API, but the overhaul is only implemented on Windows.
+
+However, we lack the personnel necessary to implement those changes!
+
+# A call for help
+
+That segues nicely into the second point I'd like to bring up: for such a core piece of infrastructure
+in the Rust ecosystem, we have astonishingly little manpower. Only three of the seven platforms we support
+have active maintainers: X11, macOS, Android, iOS, and WASM are all largely unmaintained, despite their
+importance! Additionally, Glutin is currently maintained by just a *single* person, despite being a project
+no lone individual has the time to handle. This had led to a great deal of issue buildup on those platforms,
+since we lack contributors with enough time to debug and resolve issues on those platforms. Major new features
+and API improvements can't land on `crates.io` since we currently can't implement them across all platforms -
+gamepad support being the most significant (although certainly not only) example.
+
+If you are interested in Rust becoming a larger force in graphics ecosystem, please take a look at the
+issues below and find one you can contribute to! We encourage all types of contributions, so go out and
+write, test, review, and submit PRs, add and review documentation, and whatever else you would like to
+do. No matter what you do, your time would be very much appreciated, and would result in widespread
+improvements across the Rust community.
+
+## High-level issues:
+- Sign up on a testing list for any platform we support: https://github.com/rust-windowing/winit/wiki/Testers-and-Contributors
+- Gamepad support on all non-Windows platforms.
+- X11 bugfixing (link to list)
+- macOS bugfixing (link to list)
+- Android's Eventloop 2.0 implementation
+- iOS features and bugfixing (link)
+- Maintainers for the following platforms:
+    - macOS
+    - X11
+    - Android
+    - iOS
+
+## Nitty-gritty problems:
+
+(embed https://gist.github.com/Osspial/fddc1fdcbd65a0f6510c9669b21b4901)
+
+# FAQ
+
+
+## Why remove `poll_events` completely?
+
+`poll_events` only functions as expected on Linux.
+
+All other platforms break in some way with applications built around `poll_events` - some breaking 
+in subtle ways, others breaking completely. For example, when a user resizes the application's
+window, Windows* and macOS freeze the main event loop completely if the event loop uses
+`poll_events`. On the more extreme end, Mobile and Web platforms don't ever return from
+`poll_events`, completely breaking any application that relies on `poll_events` functioning.
+
+As much as we'd like to expose `poll_events` as an API, the reality is that we cannot expose it
+without fundamentally lying about its cross-platform functionality.
+
+<sup>* You might notice that calling `poll_events` on Windows in legacy Winit *doesn't*
+freeze the event loop. This is because legacy Winit **spawns an entire background thread to run
+the Windows event loop** in order to hide the freezing behavior. This has caused innumerable
+amounts of stability and UX problems, and moving to the new event loop model is the only way to
+fix those issues without creating an unstable tower of hacks.</sup>
+
+
+## Since `poll_events` is dead, is there any sort of replacement?
+
+Yep! The `run_forever` API has been renamed to `run`, and received a few major usability upgrades:
+1. You now receive an event when the platform event queue has been drained, allowing you to bundle
+   your application logic into a single event handler.
+2. New windows can be created within the event handler closure, using the `EventLoopWindowTarget`
+   field.
+3. You can now set timers in the event loop, adding proper support for framerate limiters and other
+   timer-based functionality.
+
+These new features make `run` actually usable in a real application, and should more than compensate
+for `poll_events`' removal.
+
+
+## Why does the new `run` function not return?
+
+It was the only way for us to expose a single API that more or less behaves the same way on all
+platforms.
+
+Admittedly, it isn't necessary on desktop platforms (Windows, macOS, and Linux). However, Android,
+iOS, and WASM all require the host platform take exclusive control over the application's event
+loop, and this API allows us to expose that behavior under the same API as our desktop backends.
+
+If, for whatever reason, you absolutely *must* be able to return from the `run` function, we expose
+[`run_return`](LINK TO DOCS) on our desktop platforms. We'd discourage using that unless absolutely
+necessary, since it breaks cross-platform compatibility and can lead to subtle bugs on desktop
+platforms if used improperly.
+
+
+## Why break the API's backwards compatibility now?
+
+There were several small details in Winit's public API that we weren't happy with, but required
+breaking changes to fix. Since we were already breaking downstream applications with the new event
+loop API, we decided to try bundling all our desired breaking changes into a single release instead
+of painfully staggering them out over several point releases. This will make upgrading to 0.20 a
+bit more of a hassle, but should make the API significantly easier to use going forward.
+
+Unfortunately we didn't quite manage to include all the breaking changes we wanted this release, but
+breaking changes in the future should be significantly less disruptive and will be bundled with
+major feature releases.
No results found