v5.md

Version 5 was not only a complete rewrite, but a complete re-imagining of the library, of its architecture, of its approach, of its goals.

A bit of history: versions 0 through 4 had a pretty simple goal: to work. Notify first started because I wanted to build cargo-watch. I never planned to write a cross-platform library spanning years of work and powering many different applications in the Rust world. I just wanted a tool that would recompile my code when I edited it. As time went on and more and more demand piled on Notify, the limitations of its humble beginnings and approach got to show.

Version 5 started as a technical redesign. And then I burnt out. Then I came back to it and re-imagined Notify with a focus on people instead. With a focus on well-being. Mine and others'.

The overarching goal of Notify is now to make it easy for people. For consumers: easy to use. For power users: easy to customise. For developers: easy to contribute to. For me: easy to manage and maintain.

The truth is:

• I have no idea how the Windows backend works.
• I have no idea how the macOS backend works.
• The polling backend is kind of a wondrous mystery.
• I don't particularly care.
• Most of Notify was built based on me trusting others to know wtf they're doing.

For version 5, I didn't want to change any of that: rather, I wanted to formalise it. Hence the modular design.

Easy to use

• It should be well documented, not just with API documentation but with guides and a clear synopsis.
• Notify users are developers, but their users may not be, so there should also be documentation that's accessible to less technical people that downstream devs can point their users to for common issues.
• The primary interfaces should be idiomatic and not present surprises.
• In most cases, it all should Just Work.

Easy to customise

• Notify should expose some of what it uses to make choices, and offer public interfaces to plug in there, both to extend the defaults, or to replace them completely.
• Customising one aspect shouldn't require tons of boilerplate for all the other knobs.
• Customising is a valid usecase: it should be documented and some of it should be supported. What's not supported should also be documented.

Easy to contribute

• The interfaces of modularity should be well-defined, documented, and useful.
• It should not be necessary to ask anyone before implementing a module. Just go off and do it. It should also not be necessary for users to do something complicated to use a third-party module.
• Everything common needed to build a module should be provided by Notify. Just like users shouldn't get to write excessive boilerplate, so should contributors be avoided that chore.
• There should be pathways for non-techies to contribute. Or for techies to contribute without writing code.

Easy to maintain

• Why should everything be well documented?

  • To avoid people asking in the first place
  • To be able to trivially point people to the right place if they do ask.
  • It's easier to write good docs when not on the spot (i.e. when responding to bug reports).
  • More documentation → less maintainer burden.
    • (There's a balance to everything: don't do too much or it will become a hardship in itself.)

• Why should it be modular?

  • To not have to care about how specific things are implemented.
  • To be able to more effectively delegate, with clearer boundaries.
  • To reduce development, testing, debugging time.
  • To make it possible for others to share the load.
  • To enable interesting experiments and keep motivated without risking core integrity!

• Why should it be idiomatic and low on boilerplate?

  • Cut down on issues people have (and therefore the burden of answering them)
  • Make it easier for people to grok things by themselves and solve their own issue
  • Easier to check, and easier to see when people are doing custom things
  • Easier to get reproductions and help people

• The builds should stay green

  • On all first-tier platforms
  • Things that fail repeatedly should be fixed or ignored with an issue open
  • That makes it easier for pull requests to be evaluated
  • and for actual bugs to be caught.

• Cosmetics don't run in CI

  • No rustfmt
  • No clippy
  • No requirement on running those for PRs
  • They're a "nice to have", but shouldn't add burden, on maintainer nor on contributor.
  • It's trivial to run cargo fmt once in a while when set up for it.
  • It can be a nice distraction to fix clippy checks.

• No unsafe in core

• Lots and lots of trace! logs

• Internals API documentation: the consumer group is smaller, but no less important

See? It's all to make it easier for me.