-
Notifications
You must be signed in to change notification settings - Fork 984
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Move all examples to a common location #3111
Comments
The proposal sounds fine to me. I don't have a strong opinion here. I agree with adding the |
Circular dependencies are problematic in several ways: - They result in cognitive overhead for developers, in trying to figure out what depends on what. - They present `cargo` with limits in what order the crates can be compiled in. - They invalidate build caches unnecessarily thus forcing `cargo` to rebuild certain crates. - They cause problems with tooling such as `release-please`. To actually break the circular dependencies, this patch inlines the uses of `development_transport` in the examples and tests for all sub-crates. This is only meant to be a short-term fix until #3111 and #2888 are fixed. To ensure we don't accidentally reintroduce this dependency, we add a basic CI that queries `cargo metadata` using `jq`. Resolves #3053. Fixes #3223. Related: #2918 (comment) Related: googleapis/release-please#1662
@thomaseizinger I could help with examples. Do you think they should be in a separate repo or just as autonomous binaries in |
I think having them in the same workspace still makes sense otherwise there is always follow-up work to do in another repository when we make API changes and they can get more easily out of sync. Most importantly, I'd like the examples to be dedicated crates, not just "cargo examples" if you know what I mean. Currently, we need to manually list the examples and activate features otherwise they don't compile. If they are dedicated crates with a manifest, we can just list the features that are necessary for a particular example. This should also be more user-friendly because it can be copy-pasted and has more documentation value. As we do this, I envisioned that we also do some tidy-up to remove some duplication. To start with, we can leave that to a minimum though. I think simply moving all examples into one place already has a lot of value and gives us a better foundation to work with! |
@thomaseizinger Sounds good. I drafter a PR for the |
The
Yes. I'd like to rename that to something like "recommended transport"? For example, in my opinion, it shouldn't support I am not sure how controversial that is so I'd rather not block any of this work on it :) |
Tokio specified what every feature flag does in the lib.rs docs https://github.com/tokio-rs/tokio/blob/master/tokio/src/lib.rs#L305. We can do the same for libp2p.
Sure, it can be done in another PR. IMO the whole method should be abolished in favor of an example with all "recommended" features for others to copy and modify as they see fit. Another option is to rename it to |
That is not a bad idea. I wish that cargo would support adding docs to features. Docs.rs already supports listing all features: https://docs.rs/crate/libp2p/latest/features With listing them again I am worried that we will forget updating that list but maybe that is just something we have to accept. |
Circular dependencies are problematic in several ways: - They result in cognitive overhead for developers, in trying to figure out what depends on what. - They present `cargo` with limits in what order the crates can be compiled in. - They invalidate build caches unnecessarily thus forcing `cargo` to rebuild certain crates. - They cause problems with tooling such as `release-please`. To actually break the circular dependencies, this patch inlines the uses of `development_transport` in the examples and tests for all sub-crates. This is only meant to be a short-term fix until libp2p#3111 and libp2p#2888 are fixed. To ensure we don't accidentally reintroduce this dependency, we add a basic CI that queries `cargo metadata` using `jq`. Resolves libp2p#3053. Fixes libp2p#3223. Related: libp2p#2918 (comment) Related: googleapis/release-please#1662
Related: libp2p#3111. Pull-Request: libp2p#3662.
Description
For reasons such as modularity, the
libp2p
library is divided into several sub-crates. Users however are expected to mostly interact withlibp2p
through thelibp2p
meta-crate.Currently, we have two kinds of examples:
libp2p
crate: https://github.com/libp2p/rust-libp2p/tree/master/examplesI propose to remove all examples from individual crates (including the
examples/
directory from the libp2p crate) and instead, create a set of dedicated binary crates that showcase various examples.It is important that the new examples are dedicated crates!
rendezvous
where you have binaries fulfilling different roles.Motivation
libp2p
. Users often don't navigate down the directory tree to find a particular example of a protocol.libp2p
API without introducing circular dependencies: Avoid circular dependencies in workspace #3053Current Implementation
Examples are all over the place and introduce circular dependencies.
Are you planning to do it yourself in a pull request?
Maybe.
The text was updated successfully, but these errors were encountered: