Documentation update (#1618)

.github/workflows/build.yml

@@ -4,11 +4,14 @@ on:
   pull_request:
     paths-ignore:
       - "**.md"
+      - "**.mdx"
   push:
     branches:
       - master
     paths-ignore:
       - "**.md"
+      - "**.mdx"
+
   schedule:
     # runs the CI everyday at 10AM
     - cron: "0 10 * * *"
@@ -68,6 +71,11 @@ jobs:
           if test -d "integration/build_yaml"; then
             flutter pub get integration/build_yaml
           fi
+      - name: Install dependencies (website/third-party)
+        run: |
+          if test -d "third-party"; then
+            flutter pub get third-party/cosmic_frontmatter
+          fi
 
       - name: Check format
         run: dart format --set-exit-if-changed .

.gitignore

@@ -53,3 +53,6 @@ lib/generated_plugin_registrant.dart
 # Exceptions to above rules.
 !/packages/flutter_tools/test/data/dart_dependencies_test/**/.packages
 .vscode/settings.json
+
+node_modules
+package-lock.json

CONTRIBUTING.md

@@ -0,0 +1,122 @@
+## Contributing to Riverpod
+
+So you want to contribute? Awesome! Contributions are welcomed.  
+Before we get started on setting up the development environment, check out
+our [Code of conduct](./CODE_OF_CONDUCT.md).  
+You will also want to join our [Discord](https://discord.gg/Bbumvej) to chat.  
+Feel free to ping @rrousselGit there for questions related to contributing.
+
+With that out of the way, the way to contribute may vary depending on what you
+want to contribute to.  
+There are a few ways to contribute to the Riverpod ecosystem:
+
+- Documentation work (adding new articles, fixing typos, translations).  
+  This is the easiest and recommended way of contributing.
+  There is generally a low barrier to entry with such contributions.
+
+- Tooling work.
+  You could work on side-tools for Riverpod, such as adding new lint rules
+  or working on a migration CLI or devtool, etc...
+  This is more technical, but code quality won't matter too much.
+
+- Contributing to Riverpod itself.
+  This is the hardest part. Adding new APIs will be generally very difficult,
+  as we'll need to have an extensive discussion about that new API first.  
+  If you want to contribute to Riverpod itself, it is recommended to work
+  on bug fixes instead.
+
+**It is highly encouraged to make an issue before creating your PR**  
+This is especially crutial for larger work.  
+You do not need to spend a lot of time making that issue. The important is:
+
+- Mention that you want to contribute
+- Explain a bit what you want to do.
+
+Making an issue is important to discuss what needs to be done.  
+You wouldn't want to spend tens of hours working on something, only to
+have your PR rejected because we disagree on the direction taken.
+An discussion may slow down the work initially, but it can save you from a lot
+of frustration.
+
+## Documentation work
+
+Riverpod's documentation uses [Docusaurus](https://docusaurus.io/fr/docs).  
+This framework is responsible for various features of the website. Check out
+its documentation, as it may have the answer to your questions.
+
+Documentations are written in "mdx", which is a combination of Markdown and JSX.  
+If you are familiar with Markdown, this should be reasonably easy to pick up.
+Feel free to look at existing pages to see how they work.
+
+### Installing the website locally
+
+The docs uses [node](https://nodejs.org/fr) and [yarn](https://yarnpkg.com/).  
+You will need to install install both and run:
+
+```sh
+yarn install
+```
+
+Then, you can start the documentation locally with:
+
+```sh
+yarn dev
+```
+
+Finally, head to `localhost:3000`
+
+### Adding new language
+
+Riverpod supports multiple languages.  
+To add new languages, it is recommended to follow the [i18n](https://docusaurus.io/fr/docs/i18n/introduction)
+documentation of Docusaurus.
+
+The english documentation is hosted in [`/website/docs`](https://github.com/rrousselGit/riverpod/tree/master/website/docs).  
+Translations are hosted in [`/website/i18n`](https://github.com/rrousselGit/riverpod/tree/master/website/i18n).
+
+### Working on packages
+
+### Updating english docs
+
+English docs are the source of truth for Riverpod docs. As such, translations
+may get "out of date" for a period of time.  
+To make it obvious for users that a translated page may be out of date, Riverpod's
+website supports showing a warning banner at the top of the translation pages.
+
+To support in a maintainable way, when editing english docs in a way that requires
+translations to be updated, the english's "version number" needs to be bumped.  
+**This does not need to be done when fixing typos**
+
+To bump the version number of a page, you should either add or update
+a `version: nbr` at the very top of the file.
+
+For example:
+
+```md
+---
+title: This is an example
+version: 2
+# ^ This number needs to be incremented.
+# Doing so will show an outdated banner on all translations of this page.
+---
+
+Some content
+```
+
+#### Adding code snippets
+
+Unless agree otherwise, all code snippets inside docs need to be placed in a `.dart` file
+and then imported in `.mdx` files.  
+This is important to enable static analysis of the code snippets, such that when
+a breaking change happens, all associated snippets in the documentation that
+need updating will be highlighted.
+
+You can check out the [Getting Started] source for an example on how to do this.
+
+At the same time, if you are working on a branch of the documentation
+where the toggles for enabling/disabling code-generation and hooks are supported; then
+your code snippets should support those.  
+This is done by having a separate `.dart` file for each possible scenario.  
+Again, look at the [Getting Started] for an example.
+
+[Getting Started]: https://github.com/rrousselGit/riverpod/blob/rework-flow/website/docs/introduction/getting_started.mdx

README.md

@@ -20,108 +20,64 @@
   <img src="https://github.com/rrousselGit/riverpod/blob/master/resources/icon/Facebook%20Cover%20A.png?raw=true" width="100%" alt="Riverpod" />
 </p>
 
-A state-management library that:
+<p align="center">
+<img src="https://github.com/rrousselGit/riverpod/blob/master/resources/icon/Facebook%20Cover%20A.png?raw=true" width="100%" alt="Riverpod" />
+</p>
+
+---
 
-- catches programming errors at compile time rather than
-  at runtime
-- removes nesting for listening/combining objects
-- ensures that the code is testable
+A reactive caching and data-binding framework. https://riverpod.dev  
+Riverpod makes working with asynchronous code a breeze by:
+
+- handling errors/loading states by default. No need to manually catch errors
+- natively supporting advanced scenearios, such as pull-to-refresh
+- separating the logic from your UI
+- ensuring your code is testable, scalable and reusable
 
 | riverpod         | [![pub package](https://img.shields.io/pub/v/riverpod.svg?label=riverpod&color=blue)](https://pub.dartlang.org/packages/riverpod)                 |
 | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
 | flutter_riverpod | [![pub package](https://img.shields.io/pub/v/riverpod.svg?label=flutter_riverpod&color=blue)](https://pub.dartlang.org/packages/flutter_riverpod) |
 | hooks_riverpod   | [![pub package](https://img.shields.io/pub/v/riverpod.svg?label=hooks_riverpod&color=blue)](https://pub.dartlang.org/packages/hooks_riverpod)     |
 
-Welcome to [Riverpod]!
-
-This project can be considered as a rewrite of [provider] to make improvements
-that would be otherwise impossible.
+Welcome to [Riverpod] (anagram of [Provider])!
 
-For learning how to use [Riverpod], see its documentation: https://riverpod.dev
+For learning how to use [Riverpod], see its documentation:  
+\>\>\> https://riverpod.dev <<<
 
 Long story short:
 
-- Declare your providers as global variables:
+- Define network requests by writing a function annotated with `@riverpod`:
 
   ```dart
-  final counterProvider = NotifierProvider<Counter, int>(Counter.new);
-
-  class Counter extends Notifier<int> {
-    @override
-    int build() => 0;
-
-    void increment() => state++;
+  @riverpod
+  Future<String> boredSuggestion(BoredSuggestionRef ref) async {
+    final response = await http.get(
+      Uri.https('https://boredapi.com/api/activity'),
+    );
+    final json = jsonDecode(response.body);
+    return json['activity']! as String;
   }
   ```
 
-- Use them inside your widgets in a compile time-safe way. No runtime exceptions!
+- Listen to the network request in your UI and gracefully handle loading/error states.
 
   ```dart
-  class Example extends ConsumerWidget {
+  class Home extends ConsumerWidget {
     @override
     Widget build(BuildContext context, WidgetRef ref) {
-      final count = ref.watch(counterProvider);
-      return Text(count.toString());
+      final boredSuggestion = ref.watch(boredSuggestionProvider);
+      // Perform a switch-case on the result to handle loading/error states
+      return boredSuggestion.when(
+        loading: () => Text('loading'),
+        error: (error, stackTrace) => Text('error: $error'),
+        data: (data) => Text(data),
+      );
     }
   }
   ```
 
 See the [FAQ](#FAQ) if you have questions about what this means for [provider].
 
-## Migration
-
-With the release of version 1.0.0, the syntax for interacting with providers changed.
-
-See [the migration guide](https://riverpod.dev/docs/migration/0.14.0_to_1.0.0/) for more information
-
-## Index
-
-- [Migration](#migration)
-- [Index](#index)
-- [Motivation](#motivation)
-- [Contributing](#contributing)
-- [FAQ](#faq)
-  - [Why another project when provider already exists?](#why-another-project-when-provider-already-exists)
-  - [Is it safe to use in production?](#is-it-safe-to-use-in-production)
-  - [Will this get merged with provider at some point?](#will-this-get-merged-with-provider-at-some-point)
-  - [Will provider be deprecated/stop being supported?](#will-provider-be-deprecatedstop-being-supported)
-- [Sponsors](#sponsors)
-
-## Motivation
-
-If [provider] is a simplification of [InheritedWidget]s, then [Riverpod] is
-a reimplementation of [InheritedWidget]s from scratch.
-
-It is very similar to [provider] in principle, but also has major differences
-as an attempt to fix the common problems that [provider] face.
-
-[Riverpod] has multiple goals. First, it inherits the goals of [provider]:
-
-- Being able to safely create, observe and dispose states without having to worry about
-  losing the state on widget rebuild.
-- Making our objects visible in Flutter's devtool by default.
-- Testable and composable
-- Improve the readability of [InheritedWidget]s when we have multiple of them
-  (which would naturally lead to a deeply nested widget tree).
-- Make apps more scalable with a unidirectional data flow.
-
-From there, [Riverpod] goes a few steps beyond:
-
-- Reading objects is now **compile-safe**. No more runtime exception.
-- It makes the [provider] pattern more flexible, which allows supporting commonly
-  requested features like:
-  - Being able to have multiple providers of the same type.
-  - Disposing the state of a provider when it is no longer used.
-  - Have computed states
-  - Making a provider private.
-- Simplifies complex object graphs. It is easier to depend on asynchronous state.
-- Makes the pattern independent from Flutter
-
-These are achieved by no longer using [InheritedWidget]s. Instead, [Riverpod]
-implements its own mechanism that works in a similar fashion.
-
-For learning how to use [Riverpod], see its documentation: https://riverpod.dev
-
 ## Contributing
 
 Contributions are welcomed!
@@ -134,60 +90,6 @@ Here is a curated list of how you can help:
 - Update the documentation / add examples
 - Implement new features by making a pull-request
 
-## FAQ
-
-### Why another project when provider already exists?
-
-While [provider] is largely used and well accepted by the community,
-it is not perfect either.
-
-People regularly file issues or ask questions about some problems they face, such as:
-
-- Why do I have a `ProviderNotFoundException`?
-- How can I automatically dispose my state when not used anymore?
-- How to make a provider that depends on other (potentially complex) providers?
-
-These are legitimate problems, and I believe that something can be improved to fix
-those.
-
-The issue is, these problems are deeply rooted in how [provider] works, and
-fixing those problems is likely impossible without drastic changes to the
-mechanism of [provider].
-
-In a way, if [provider] is a candle then [Riverpod] is a lightbulb. They have
-very similar usages, but we cannot create a lightbulb by improving our candle.
-
-### Is it safe to use in production?
-
-Yes.
-
-[Riverpod] is stable and actively maintained.
-
-### Will this get merged with provider at some point?
-
-It is possible. Some experiments are being made that could make this
-doable. But their outcome isn't clear yet.
-(no link to an issue to avoid putting unnecessary pressure on the people
-involved)
-
-If those experiments are successful (although unlikely), then Provider
-and Riverpod could be fused.
-
-### Will provider be deprecated/stop being supported?
-
-Maybe.
-
-Provider has numerous flaws that can't quite be fixed. At the same time,
-Riverpod has proven to fix many of those.  
-As such, deprecating Provider is being considered.
-
-The only inconvenience of Riverpod is the need for a "Consumer",
-which Provider doesn't need.
-But some alternatives are being investigated to maybe remove this constraint.
-
-Whatever the decision is, a migration tool is planned to help assist
-migration from provider to [Riverpod]. Along with whatever other tool necessary to help.
-
 ## Sponsors
 
 <p align="center">