rust-windowing / rust-windowing/winit

Event lifecycle docs (contribution volunteer)

Open
#2,736 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

S - docs
Dominant language
Rust
Stars
6.2k
Forks
1.3k
Avg merge
2d 19h
Merged PRs (30d)
9

Description

One thing I struggled with when starting with winit is a clear idea of the "lifecycle" of an event loop. That is: what's the order of events I can expect to be dispatched to the EventLoop::run closure? I would like to contribute some docs to this if you'd be amenable.

I think this problem is particularly important for winit because - as a new user - you're immediately made aware that winit is being very careful about cross-platform behaviour (being required to pass a move closure to run which entirely hijacks your main thread makes this clear), but one of the core aspects of that behaviour isn't immediately clear.

I realise most of this information is already in the docs - across the root docs, Event, and ControlFlow docs. I think all of those are appropriate docs for where they are, but propose an additional section in the root docs specifically to teach new users the high-level of what to expect from events. Ideally with a simple flowchart showing the most common orders of events (see, for example, this from the android docs).

I'd be happy to draft something, but wanted to check that it would be desirable first. Also, since I still don't fully understand this topic, it would require some careful review.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the existing root event-handling documentation alongside the Event and ControlFlow docs linked in the issue. Map the high-level event-loop lifecycle and common event orders across the documented platforms, then draft an additional root-docs section with a simple flowchart. Done means the lifecycle is explained clearly for new users and the content receives careful review.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.