Setting our vision for the 2017 cycle

I have been thinking about this recently. There are some great learning resources out there:

However, I feel that that The Book and Rust by Example target an audience that is somewhat new to programming in general (less so for Rust by Example). I have been thinking how we can target experienced programmers. What about a “Rust in a Nutshell”? Something along the lines (very vague, and very roughly):

  • A very quick intro to primitives.
  • A moderately deep (while trying to remain concise) tour to the borrow system. The various differences of copy semantics and move semantics should be emphasized here.
  • A thorough explanation of Lifetime analysis, why it’s needed, when it’s needed and common tricks to handle common lifetime analysis problems.
  • A through guide in using the Type system.

I know that there is a lot of overlap with what I just wrote and The Book. But, I feel like that if we target an experienced programming group we can make more assumptions to write a more concise guide. Something with a goal like: This is what you need to know about rust. If you know this, then everything else can be found in the STD documentation (which is quite fantastic).

What do you think?

Edit: I call dibs on the title “Rust in a Crabshell”

15 Likes

I definitely think project infrastructure should be one of the priorities, because having good infrastructure helps adoption of Rust. Without a good set of infrastructure tools, I know many won’t even consider Rust. It’s all well and good to make Rust’s learning curve easier, but if Rust isn’t even being considered serious enough to try to learn, it’s not going to help adoption much. There’s a couple small areas I’d like to utilize Rust at work, but it’s just not going to happen without the a good level of stable infrastructure, which makes me sad :frowning: That’s not to say that there’s not already stuff out there heading the right direction, but I do feel it should be part of the vision to get Rust infrastructure more production ready.

Other than that, I definitely like these vision statements

1 Like

I’ve been thinking that for advanced programmers, we really need a few different guides that take advantage of what you already know. For example, a Ruby programmer is going to come to Rust with quite a different perspective than a Java programmer, who comes to Rust with a different perspective than C++.

I don’t think that means we need to have one guide per language, but a guide that makes sense to people with a scripting language background (Ruby, Python, JS, Lua), another for people with background in a 90s-era typed language with GC (Java, C#), and another for people with background in a “zero cost abstract language” (C, C++) would cover a lot of ground.

Also, instead of trying for full coverage of all languages, we could have shorter guides that cover less ubiquitous features of specific languages. For example, we could write a document that helps a Go programmer understand errors in Rust, a Ruby programmer understand traits from the perspective of open classes and refinements, or a Swift programmer understand Option from the perspective of nil and forced unwrapping.

14 Likes

This definitely matches extremely common sentiments we heard in the survey. Can you elaborate on what kinds of tools you mean by “infrastructure”?

This is pretty interesting – it might be good to talk through a concrete example. I could see this going a couple ways.

  • In some cases, the “right way” to do it in Rust is not to try to mimic inheritance, but rather to use traits in some other way. For those cases, the problem might be best solved by a guide like “If you’re used to inheritance, here’s what to do in Rust instead”.

  • But in some cases, maybe inheritance really is what you need. For that, we really need to finish out our saga of building Rust’s ability to express inheritance-like patterns.

Very much agreed! It’d be great to make progress here, either by making this easier to do at the language level, introducing general libraries for it, or writing more docs guiding you on it.

4 Likes

As I mentioned in my One Year of Rust post I think the following priorities should be considered and I wanted to expand them here:

  • RFC’s and the transparency with the community are a mess. Not everyone has the time or inclination to read them over and this leads to things like “When is MIR landing? Is it turned on?” Some RFC’s were accepted long ago but no work has been done on them. Having a dashboard that shows what RFC’s have been accepted, which ones are actually being worked on, and target dates would go a long way for Rust. Having a place to point users would really help people have a clear understanding with what’s coming down the line.
  • Rust has the possibility to replace C and C++ in the embedded systems department but things like #[no_std] don’t work and having to have a ton of workarounds just to get it to work is frustrating. Workarounds doesn’t make embedded dev feel like a first class citizen at all and not focusing on this area of Rust is in my opinion a huge mistake and a large oversight since we’ve been focusing so much on stability and things like MIR. Going forward into 2017 making it easy to cross compile to various embedded systems is one area I think we should really focus on.
  • As for crates we just don’t have a lot of 1.0 crates. Trying to get people to go 1.0 is probably too hard and not something the core team should focus on. However, I think if we rallied the community to stabilize important crates to 1.0 I think would be highly beneficial. Some crates I think we should get the community to stabilize to 1.0 in the next year would be Ring, Diesel, Iron, and Serde for instance. Large projects that provide critical features should be highlighted, helped in creating a 1.0 roadmap, subdividing those tasks into issues, and then letting the community plow through them to stabilize the crate. The hard part will be identifying the crates we should prioritize for stabilization and working with current project maintainers to setup these roadmaps and issues for users to work on.
  • Tooling is really important and while we have an RFC for IDE support accepted no work has been done on it and I think this is something we should work on actually implementing.
  • Custom Derive is something we need badly because too many crates like Serde depend on it and having to use Syntex to get it to work is god awful to set up. Prioritizing this will greatly benefit being able to use larger libraries in production since they would then be able to compile on stable rather than nightly. Too many of the good libraries are on nightly making the use of stable unreasonable and hard if not impossible to use in production depending on company standards.
  • I think we should help new users learn Rust but I don’t really have any good ideas to throw behind this besides saying we need it.

Between all of these and what was already mentioned I think 2017 will have a solid enough roadmap of things to do both with the community and the core team in terms of things we need to do.

9 Likes

I want to post something more substantial in a bit, but until then:

Interesting, I feel like it’s very not appropriate for that audience! There is not nearly enough hand-holding for that. We do target people who are new to statically typed languages, or systems languages, but not programming generally.

(Opinions can of course differ; I wanted to communicate how i think of it)

4 Likes

I went back and took a look. I agree, I don’t think it’s a good book for people new to programming. And if your intentions were indeed geared towards people who are coming from a dynamically typed language I think you nailed it. That being said, do you think there is room for improvement for targeting programmers coming from a statically typed background? C, C++, Java? And if so, do you have ideas for how to approach such a problem? I would be interested in possibly helping with such a project if there are some good ideas.

2 Likes

Can you say a bit more about what you are thinking of when you say “project infrastructure”? When reading what @aturon wrote, I was primarily thinking of things like bors and our own internal CI infrastructure, but it’s not clear to me how that would help adoption (except indirectly by making Rust better).

I feel like we had worked out a fairly decent story here at some point, but we’ve stalled in terms of pushing the various pieces. Specialization and “fields in traits” were intended to be starting points, for example. I’ve got to revisit the “fields in traits” RFC in any case…

4 Likes

I like these ideas, and also a similar guide mentioned earlier in this thread “If you’re used to inheritance, here’s what to do in Rust instead” kind of guide. Perhaps my concern with this approach was making such guides accessible. Should we just let these guides appear on the interwebs naturally? Should there be a curated list of guides? What’s the story here? And for someone coming from another language, where do they start?

1 Like

If it frees up the core team’s time because more of what they do is automated I could see how that would contribute indirectly to Rust but beyond that I don’t see how it would increase adoption beyond more features being created.

These vision statements are really good, and I think cover all of the important bases.

On learning curve, I think it’s important we also consider significant investment in tooling, i.e. rustdoc. I’ve heard @steveklabnik mention it doesn’t get much love, and that feels like a pity. One example: the Windows docs for std are currently not available online, because rustdoc will only build the docs for the current platform (or really just the currently applicable set of conditional compilation conditions). How are Windows/OS X users supposed to learn std in this situation? Another: how to document module items whose definition depends on conditional compilation stuff? Do I have to copy docs for each platform?

If the current order of vision statement implies prioritization, I would prioritize the FFI story more. In trying to sell Rust, being able to integrate well with already existing/used technology is incredibly important in making an exploration of Rust as a technology low-risk.

One other thing that came up in threads on this forum recently: it would be in an interesting challenge to try to organize a Rust fund to try and help fund the library ecosystem. I came up with a concept around “turning precious metal into Rust”, with a yearly pitch to stated Friends of Rust (I thought up all kinds of puns, too, but forget them) to contribute on the order of 1k/10k/25k to a funding team that would then approve grant proposals from the community. It would maybe hinge on demonstrating the community’s independence from Mozilla, to some extent?

1 Like

Or like making it much simpler & shorter defining an unsecure-but-fast hashing.

This seems a nice and simple idea.

2 Likes

Isn’t this short enough? https://doc.rust-lang.org/std/collections/struct.HashMap.html#examples-3 You just have to use the desired hasher instead.

1 Like

Could you elaborate? What about no_std doesn’t work?

It’s not easy and not short.

So, I haven't spoken with the docs team about all of this yet, given that it was just posted, but here's my own personal thought:

For the docs team, I would hope that we can manage to switch from reactive to proactive.

What do I mean by this? Well, ever since I came on board, I've been in 'reactive mode.' "Here's the language and standard library, get to work." Consider it like a consumer/producer problem:

The "producer" are people working on things: the language, libraries, etc. Once they've produced their code, it goes into the buffer. Then, the consumer is writing the docs: something gets popped off the queue, worked on, and documented.

The problem is, with many more producers than consumers, the buffer fills up. This leads to bugs like https://github.com/rust-lang/rust/issues/20137, and you can see what happened there.

So, what to do? Well, now that it's not just me, I'm hoping that we as a group can finish off the backlog in the buffer. Once we do, we can stop fighting fires and start taking a more pro-active stance on docs. Some of that is tied into all the other goals, for example. So like, let's take one of them: FFI. We could have a whole little mini-book on FFI and Rust, and how to make it good. But I don't have time for that; the standard library still has functions with no docs. This would be the "proactive" mode: we're focusing on what docs the ecosystem needs to have, rather than just catching up on a huge backlog.

The next level is getting rid of the producer/consumer issue entirely: @chriskrycho opened https://github.com/rust-lang/rfcs/pull/1636 , which basically says "nothing can ever go into the buffer". In order to manage that, we as a team will have to help others help us, by getting more people to write docs, even if they don't usually write them. We want to keep high standards, yet not let that block actually shipping.


Now, for some replies:


Could you elaborate on what you mean here? What doesn't work about it?

I think this post by @wycats is a big part of it:

One argument passed for the hasher isn't short enough? What would be your ideal syntax here?

5 Likes

I think this post covers a lot of the problems one runs into when turning off std. I would consider making an OS as bare metal as you could get and something you would run into when working on embdeded development systems which have no OS. One shouldn’t have to use things like ralloc just to get it to work. These are the kinds of problems I meant with workarounds. Like you can use no_std and there are solutions but they’re not baked into Rust without finagling. http://os.phil-opp.com/set-up-rust.html

One thing I wonder, actually - how feasible would it be to (in essence) do “symbolic execution” of #[cfg] directives? Specifically, have rustdoc “branch” on encountering a #[cfg] directive, generate documentation under both, and generate fragments for each such section? That could then allow selecting from a menu of #[cfg] options when reading the docs.

In terms of phrasing this as a vision statement, “Users of any platform should be able to easily read the documentation relevant to a crate as they would actually use it.”

8 Likes