Mentoring newcomers to the Rust ecosystem

announcements
1

One of the reasons I love open source is the sheer amount of opportunities to learn that it presents. Budding programmers can work on Real Things and make a real impact, becoming better programmers in the process.

Rust already participates in this. We mentor newcomers with bugs and often they go on to become valuable contributors.

I'd like to expand and improve our efforts. I want to create a more accessible mentorship program that helps people find a place to contribute in the entire Rust ecosystem -- not just rustc.

Here's how you can help:

###Crate owners

Do you maintain a crate? Try opening mentored bugs on it!

Servo, Rust, hyper, rustfmt, and clippy already do this. The general modus operandi is to use a label (e.g. "Easy", or "Mentored") that indicates that an issue is a good first bug, and point people to these bugs. Having a CONTRIBUTING.md with other "getting started" tips is useful. If someone picks up a bug, help them work on it! Once they finish, see if you can come up with something more interesting for them to work on.

Easy bugs aren't hard to come up with, either. Often it can just be a tangential fix that you could do in your current PR but decide to file as an easy issue instead. Or simple refactoring tasks.

Easy bugs need not even be code work. Documentation, diagnostics, and other similar things can make for worthy and impactful things to work on!

There's probably going to be a nice "contributing" section on the new website, I'd like to list all such crates there. Leave a comment if you're interested!

###Community members

I'd also like to gather all the folks interested in helping newcomers out in general.

The idea is to help newcomers choose a project and get started there. There's a lot of shyness amongst newcomers, and often they may not ask questions (there's always that fear of getting yelled at for asking questions). If there are some people who explicitly are there to help, this might assuage their fears.

I'm not exactly sure how this would play out. Have a list of email addresses on the site (probably not)? Allot mentors to people who ask? Forum post to ask questions on? Ideas welcome.

###Rustc developers

Finally, rustc itself. I think we do an imperfect job of newcomer onboarding for rustc. If we want the rest of the ecosystem to mentor newcomers, we should set a better example!

Couple of issues I've noticed. Some of them I can fix myself, others need everyone to pitch in:

  • Easy issues aren't always easy: For example, we have a lot of tracking issues marked as "easy". They're not, really. Deciding if something should be stabilized or deprecated requires a lot of work and existing knowledge of the ecosystem. Once a decision has been made, the steps following it are certainly "easy", but such bugs shouldn't be marked as easy from the start. Similarly, there are other issues which are not exactly good first bugs.
  • People should be able to get started on bugs without needing to ask for help: Asking for help is great, but if a bug is going to be marked as easy there should be some pointers to help them get started. Something like "The relevant code is in foo.rs, you'll need to add functionality to bar() to frob the baz" or "Check out [this code] which does something similar". We do this all the time in Servo, and often in clippy -- AFAICT it's quite helpful to the folks who pick up the bugs.
  • Comments and documentation: While some modules like borrowck have epic comment explanations, other sections of code are sparsely commented/documented. If you are working on something, try adding doc comments to the nearby code too. Similarly, if you spend time trying to understand how something works, leave a comment so that the next person doesn't have to!

None of these issues are deal breakers -- I've seen a lot of newcomers have a great experience with their first PR on rustc, and I love it when this happens. But we can do better.

Want to help? Thoughts? Leave a comment!

19 Likes
2

I am generally open to helping people make documentation contributions. If that interests you, let me know!

4 Likes
3

(Didn't want to mix this with the main post)

Our lint repo, clippy already has mentored bugs, so it will obviously be participating. Servo will too.

I can help with documentation and diagnostics contributions to rustc itself, and I can also help with most easy compiler bugs. I've already been pointing people at rust projects which might interest them and will continue to do so :smile:

1 Like
4

I agree, the more people have a chance to get involved with Rust, the better!

I think that we can make it easier for existing contributors to open newbie-friendly easy tickets by providing an "easy ticket template" of some kind. While the CONTRIBUTING.md guide is good for new users, it doesn't take the place of simple checklist reminding the contributor filing an easy bug of just what a newbie won't know yet.

It could be as simple as:

  • What's the problem?
  • How to reproduce it (pre-fill template with links to getting started docs)
  • Where I'd look first to solve it
  • Who to contact for further help (pre-fill template with links to IRC channels, etc.)

I'd like to refine such a template to anticipate the most common newbie questions while making it as easy as possible for busier contributors to file easy bugs. I can also look at extending the rust-highfive bot to add extra information to easy tickets based on their other tags, if that would help reduce the effort involved with filing them.

Servo has a neat tool over at Servo Starters - Whet your appetite with these easy servo tasks (https://github.com/servo/servo-starters) that makes progress toward addressing the "easy issues aren't always easy" problem by sorting issues more sophisticatedly.

P.S. While I'm not really a Rust developer per se, I'm happy to help contributors newer to Git and open source workflows with more general questions!

4 Likes
5

This might be a good discussion in the "What's everyone working on?" thread too, encourage people to mention if they're willing to mentor on their crates. One benefit over just having a directory of crates is that it shows that there is someone working on this right now. It's much more encouraging when you know that you'll have someone to actively collaborate with.

3 Likes
6

That's a good idea! I'll be sure to add a note for next week's post :smile:

7

Stupid question : are there needs for translation? Personally, I know I'd be more comfortable in translation (english->french) tasks to begin with, but I've not seen calls for that and I thought maybe the documentation was prone to evaluate so it wasn't the priority.

8

Well, I'm not sure to fully understand your question so I'll answer as best as I can:

Currently, there's no need for translation on rustc/rustdoc directly (I opened a RFC for i10n but it's not a priority so it might take some time before going further).

However, if you were speaking about french resources, I wrote a french tutorial available here. Contributions on it are very welcome so don't hesitate if you think something could/should be added/modified.

I hope I answered your question(s) ! ^^

9

Someone is translating the book to German, so why not to French?

Please be aware though that tracking changes is a thing to do then.

1 Like
10

Hi everyone, I'm really new to Rust and fairly new to programming, so I figured I'd offer my 2 cents on things that I think would be helpful for people interested in using Rust. A little bit of my background to help add context; I'm primarily self-taught, an introductory Java class in college is the extent of my formal training. My primary languages are C, due to the ease of looking through Linux man pages and strace output to see what's going on, and Python because everyone I've worked with has used Python and they need to be able to read my code. For my career, it's been a mixture of general computer work for almost 5 years, then a switch to penetration testing for the past 5 years. With that out of the way, I'll get into things that I think would be helpful.

To me, the biggest help would be a note in the Rust book that explains the expected pre-knowledge for new rustaceans. For example, is Rust a good first language? Should you be comfortable with object-oriented programming and terms like methods, iterators, closures, constructors, etc., or will you pick the knowledge up along the way? I understand that the Rust book isn't designed to replace a CS degree, but a reference at the bottom of each page that links to something like a blog or wiki article that explains the concepts would be helpful to new, and potentially experienced, programmers who aren't familiar with the concepts. I know the answers to most questions are just a Google search away, but to me I would have more confidence that I'd learned the concepts correctly if I had a resource that was endorsed by the Rust community as being sufficient.

The next thing that would be helpful would be an IRC channel dedicated to new rustaceans, something like #learnrust. I've asked a few questions in the main #rust channel and the people there have been super helpful, but as a new programmer, I'm still hesitant to ask questions, especially ones that I know are super basic. I just feel guilty because I don't have anything to give back for all the help I've received, so having a channel where I know that everyone is either looking for help or looking to help would make me feel more comfortable asking questions that are definitely very basic Rust and probably very basic programming. I think it could also be a good way for new programmers to have a place where people are asking about issues that they will probably encounter.

Sorry about the essay, I just got carried away :slight_smile: Thank you for the great community and all the help I've already received.

6 Likes
11

This is a good point. #rust is notorious for being super helpful, but it's also home to a lot of fairly complex/intimidating discussions about the language. One of my success stories with Firefox mentoring was creating the #introduction channel and marketing it specifically to people just getting started. I also seeded it with experienced developers who like to answer beginner questions, and it's really taken off in the past few years.

6 Likes
12

Hey @bill,

We try to make the book as understandable as possible from a variety of backgrounds, so if there's something specific missing, please let me know. We generally don't link to external things, as

  1. They don't work offline
  2. We can't assure their quality into the future

But filling out more "background" kinds of stuff is an explicit goal.

1 Like
13

Hi @steveklabnik, most of the book was very accessable to me, I almost always have it open in a tab to use a reference while I'm coding, the only section where I felt like I was in completely over my head was Closures. I wasn't sure what was meant by "Anonymous functions that have an associated environment are called ‘closures’, because they close over an environment." I'm not sure what the environment in this context is, or what the benefits are to using an anonymous function over calling a named function. I figured that if I ever needed them, I'd revisit the closure section of the book in the future.

I hadn't considered the points you made about external resources, it would be pretty frustrating to be reading through the book and end up with a dead link when you are trying to get help. Thanks again though, you're one of the people who's been helpful with my questions in #rust :smile:

2 Likes
14

Awesome! Could you file an issue about that, and one each for anything else you find? You're right that that's a bit self-referential...

15

I'm totally on board with this and would love to help. I especially like the idea of mentioning you're looking for collaborators in the "what are you working on" threads, I will be sure to do that in the future!

I've also noticed that some of the E-easy issues on rustc look like they have the possibility to be.... not so easy :wink: I'll try to find some and poke them with clarification questions with an intent to make them more straightforward for someone to pick up or get their effort level increased.

3 Likes
16

Related to your comment on uncommented/undocumented code, having variable names that are full words has always been very useful for me in any language. It took me a while to navigate comfortably around rustc because acronyms are used for almost all variable identifiers. It's easy after you're used to it, but onboarding into that can be very challenging at times. Especially so when the code is really complex.

1 Like
17

Having a section in "This Week in Rust" could also be really helpful. It would give a single point where newbies can look to/be pointed towards a way of getting into any kind of Rust code.

18

That's really unfortunate that the book wasn't very helpful with explaining closures, because they're honestly one of my favorite features of the language!

This thread isn't the best place for a comprehensive tutorial, but if you're still having trouble understanding closures, feel free to make a new thread in this forum asking about them and I or someone else will be glad to help!

There's no shame in having seemingly stupid questions here, we all had ones like them at some point.

19

Yeah, that's my next step too :smile:

20

Thanks for your answer ^^

I had walked into that tutorial before, I might look a bit more into it in the future.

What I meant by asking this is that translation can sometimes, for some people, be a good "first step" since you don't necessary need to have deep knowledge of the language to begin with (well, it depends on what you translate, obviously), and it can allow you to acquire it. I iunderstand it might not be the priority at the moment (lack of internationalisation in Rust, plus the language, thus the documentation, is still evolving) but in the future having some "easy" translation tasks could be a way for newcomers to start contributing to the Rust ecosystem.