Include example cargo.toml with examples

[Qwertie-]

The example given in the readme seems to be not trivial to run.

With these in my cargo.toml, I am still not able to run the example as it gives me errors

matrix-sdk = "0.4.1"
tokio = { version = "1.14.0", features = ["full"] }

error[E0432]: unresolved imports `matrix_sdk::config`, `matrix_sdk::ruma::events::room::message::SyncRoomMessageEvent`
 --> src/main.rs:3:13
  |
3 |     Client, config::SyncSettings, Result,
  |             ^^^^^^ could not find `config` in `matrix_sdk`
4 |     ruma::{UserId, events::room::message::SyncRoomMessageEvent},
  |                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ no `SyncRoomMessageEvent` in `ruma::events::room::message`

I assume these errors are either a package missing or the example is outdated.

Edit: So I got to the bottom of this. The package on crates.io is much older than the git version so the example on git is not compatible with the package on crates.io. Perhaps the example could recommend using the git version of the package?

[poljar]

The examples run as part of CI and thus should never be outdated. As you noticed the other direction can happen, the examples on the git repo will always match what's in the git repo but you may use an older released version of the sdk.

The README is part of the crate docs, if you're using a released version of the crate please use the released version of the docs/examples: https://docs.rs/matrix-sdk/0.4.1/matrix_sdk/index.html#examples.

Things should stabilize in the future and this will become a non-issue.

[Qwertie-]

That sound fair. Do you think it would be worth adding a line or something explaining to use the git version if using the github readme? Would just make it a little clearer I think since usually you would use the github examples with the crates release.

[poljar]

The README.md files are used for the crate docs, so that line will be included in the crate docs as well. Not sure if that's desirable.

I guess we can include such a line and remove it once things stabilize.

[jplatte]

I think we should do the same thing here as in axum and Ruma and have an examples directory in the crate root, with examples/* being part of the Cargo workspace. Then every example clearly shows how it depends on the main crate (as a path dependency within the repo), what features it activates and what other crates it depends on.

We might also want to include a separate examples/README.md file which mentions how to go to the examples as they were at the time of the latest release (and maybe gives a summary of what the individual examples contain?).

[poljar]

The examples now all contain a Cargo.toml file, the dependency on the SDK in the Cargo.toml file also warns you about the version mismatch between Git and a release.

I think that this should be good enough.