Rust Programming Language Rust Linz, 1 Mar 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Rust Linz, February 2021 - Celia Lewis - Getting started with Open Source

Description

A talk showcasing the typical workflow of someone contributing to an open-source project through Github. The talk details the process of forking, branching, finding an issue, fixing the issue in VS-Code with Rust, making a PR, and more through a fun demo that can be revisited post-session. Concludes with an exploration of Embark Studios' several open-source Rust projects (including GPU code in Rust, PhysX in Rust, and more) and how you can start using/contributing to them.

Celia on Twitter: https://twitter.com/celiawrite
Rust Linz on Twitter https://twitter.com/rustlinz
Submit your talk: https://sessionize.com/rust-linz
On the web: https://rust-linz.at

A

um So hey guys, uh my name is celia and I'm gonna give you a little presentation on getting started with open source, rust, um subtitled, get good at open source for the bark studios, rust ecosystem, so kind of a mouthful, um and I'm sorry for the pun. But I had to so. The talk structure for today is we're gonna go over. You know why open source? Why should you care about open source? um As a software engineer as a hobbyist, you know what can open source do for you um after that?

A

We're gonna go through a quick demo that I made for this presentation, which kind of demonstrates an open source workflow using github, um including everything you would do using open source during the day, such as working a repository finding an issue work on using branches, editing on your local machine and then finally pushing to github and creating that pull request. um And then, during that demo, I'm going to highlight you know how to be a pr superstar.

A

So this is just how to create a really good pull request and, finally, we're going to end it off with going over a little bit about embarks, rust ecosystem and how you can participate in it once you're, an expert after this talk.

A

So first up what is a github, um I'm sure everyone here is, for most people are familiar with github um and, if not you're, not alone, I a few years ago, had no idea what github was. I had no idea what open source was. In general, um I was new to computer science, and everyone was telling me to get involved with like an open source project.

A

They said you got to put it in your resume, it's how you get a job, um it's a great way to meet people, and it turns out they were right, but I had no idea where to start. So that's why I kind of wanted to make a presentation that I wish was there when I was first starting out.

A

So why should you do open source? um Well, I think it's really cool, because you get to crack open the software that you use every day. I know most of us, we might use open source software every day, but a lot of us use software that isn't open source and it's kind of a mystery.

A

What's going on, you know in the back end how it's all working and it's kind of amazing when you open up an open source project- and you can see everything that's going on, you know you can see what issues they're working on um what small changes are being made. You yourself can work on something you can crack into the community and start talking to people.

A

So that's why being an open source contributor is so rewarding is for these four points you gain a deeper understanding of the technology. Sometimes it can be a technology you've never used before, like if you've never touched rust joining a community working on a rust project you get to have that mentorship built in you can contribute in a small or large way, which is awesome because you can just fix a few typos, which I know a lot of people love to do or you can.

A

You know, change the whole game and move a whole feature forward. um Again. You can put in your resume it's a it's a great thing to start your software engineering career on or any any career in tech, and finally, you can make connections and find community so a little bit about us. So I work at embark studios, which is a video game studio in stockholm.

A

Sweden, a little far from me in the us, but we're working on two games and also a game creation platform, which is the team that I'm on um and we are obsessed with rust. It's our language of choice totally and we're really um obsessed with creating a rest ecosystem and a community around it, because we maintain a lot of open source rest projects, and you know having people in that community and on our discord and working with everyone to you know maximize what we can do at embark is really important to us.

A

So that's why I get to come here today and why I am just really happy that this role exists so yeah without further ado. Let's get familiar, um I'm sorry again, but we're going to work through a open source workflow using github.

A

The exercise that I did today is how we're going to go from an empty hard drive to literally having no experience using git just having it installed and to actively contributing to this open source project and, as I said, there is one prerequisite which is that you have to have get installed um if you want to follow along.

A

Obviously you can just watch the presentation and not do anything, but if you want to do uh I'm going to link the repository later so if you want to go back and try it yourself, you can do that, but you're gonna need git. That's it just get so cool. Let's talk about the project, so it's an interesting one. So, in this imaginary world I've created there's this open source project called restaurant dash rs um and what this project does.

A

Is it basically allows restaurants who want to use an open source software to display what toppings they want to put on their pizzas? um That's it that's what this little software does and our favorite restaurant um has an open source ordering system using restaurant.rs um but they're running into a strange issue, which is that their toppings are all messed up, as you can see on the right, um customers are ordering tire pizzas and that just doesn't seem right, given that that's not it's not a topping that they um they actually have at the restaurant.

A

So we're gonna check out this repository and see what's going on, okay. So this is the restaurant dash rs repository um if you're new to github. I think this can be a little bit overwhelming at the beginning, but it shouldn't have to be so really. The main things you have to worry about are here's our code right here, um our issues, tab and then pull requests as a contributor, especially as a you know, not a maintainer. These are really all the things you have to worry about.

A

um So if I'm, this person who's completely new to open source- and my friend told me- oh, my god, this restaurant's having this big issue. The first thing I'm going to do is just go to the issues: tab and check out the issue that my friend was talking about. Our chefs are running out of wheels in their cars, so I'm going to say off the bat, not the best issue title.

A

um You know this doesn't tell us a lot about what's actually going wrong in the system, it's more of just complaining about the restaurant, but we're going to touch on later how to make very clear um and concise issue in pr titles. But let's dig in so our friend pizza fan here works at a pizzeria and they use restaurant rs in their ordering system to display the available toppings to customers.

A

So customers are ordering something called tire pizza and they have no idea why, and his brother uh pointed out that the orders started pouring in after a recent pr was merged altering the pizza.rs file. Maybe that's the issue here so already as an open source contributor that points out to us. Okay, the issue is probably in this, and the issue arise when a recent pr was merged. So someone altered the code um in this file and now there's a problem, so we'll know where to look when we start altering the code.

A

So what else do we have here? um We do not offer tire as a pizza topping okay duh, and these are the toppings that should display.

A

So we know what needs to be changed, which is that these are the toppings that should be displaying okay, easy enough right, okay, so as an open source contributor who's new to the thing our first step is, we have the issue down. Now we are going to fork it so you go over here and we are going to fork it to our account, which I'm gonna do my personal account and what does forking do it essentially just creates a copy of the core um repository.

A

It's just creating your own copy so that you can edit it and do your own thing and then eventually, when you're done changing your fixes, you can do the um pull request to then merge your changes with the main. So we're going to go all over that again. But all you have to know is it's your own copy of the the project so now we have it um and what we're going to do next is open up powershell.

A

um Just going to make sure we can see powershell here great, um so.

A

Presentable: okay, so once we're in powershell, what we're going to do is we're going to take the repository that's on github and download it to our computer using git, um so we can edit it on our local machine. So the first thing we want to do is go to this code button here and under https.

A

We are going to copy the code using the clipboard and go back here and write, get clone and then control v to copy it in. Oh, actually, I made a mistake: we're not going to do that, yet it's good practice to make a new folder. Obviously, so I'm going to call this lens and then I'm going to cd into lens.

A

How did you manage to get git on windows, so there's someone's asking on discord I'm going to include actually in the slides. There is a link you can just download git it's an easy install, so it should just take a few minutes and then you can access it in the terminal like powershell, so in uh in lens, we are now going to do the command. I was just talking about git clone awesome, so we see that it is now cloned everything to limbs.

A

We use ls to see. What's in the folder, we now see that our repository is in there, so we're going to cd into that look at our folder again and you'll see that all of the files that we just saw right here on github are now on our computer. It's magic, okay!

A

So what's next well, now that we have everything downloaded it's just time to edit. So what we're going to do is we're going to open visual studio using the code, dot, keyword.

A

Yep, you can still see that cool now, let's check out what's happening so, as we saw in the issue, we saw that our problem was probably going to be in the pizza to rs file. So that's where we're going to head first, but it is important to check out what's happening in maine. So this is a rust program. So maine is now incorporating the pizza library to run this function called available. Toppings, okay! Well, let's see what that actually does if we run it in powershell.

A

So since this is rust, it's super easy we're just going to do cargo run, and here we are. We found our problem, so it's showing the available toppings, our tire tire, tire, tire um cool, and I see another discord thing come in I'll, probably answer it at the end. But thank you for the message. um So I think if you it's a pretty small code base, you can probably already see um the problem, but we're going to go through each part really quickly.

A

So in pizza. pizza.rs we have an enum to start it with the toppings and inside of toppings. There is a variant for each of the different toppings we want to order, um then there's going to be impul for toppings and then under that we're going to have a function called tostring and then finally, there's available toppings, which is the function that, as we know, was being called inside of main.

A

So obviously, that's where um our investigations to start, because that's what's going wrong, so what is available toppings doing well, what it's doing is is storing inside of a variable, um each variant of the toppings enum. So we see for pepperoni for sardines for onions. Each of them are being stored in a variable, t1, t2, etc.

A

So, right here, all of this all it's doing is doing a print statement available toppings and then it is just printing um each of these variables using the tostring function that I've created here. So um now you can probably make an educated guess what's happening it. What it's doing is that, no matter what the variant is, the match function is matching it to a string called tire.

A

So this is a pretty easy fix. Let's just go in and make these correct. Hopefully I spell everything right or else someone else is going to have to do a new pr and fix that and then etc, etc, but cool I'm going to hit control, save.

A

And then let's try cargo running this again great. So we see it's working now available, toppings, pepperoni, sardines, onions, bacon, fantastic, so uh we are halfway there. um So we have now again forked the repository cloned it to our computer. So we can edit it locally. We fix the issue um and now, finally, we are going to um put it back online so that we can create our pull request. So how do we do this?

A

So this is where the git commands come in, so the first git command, we're going to do is called git, add and then I'm going to do a star, which means everything um and I'll explain what that is here. So what git add does is you can think of what's happening as you're stuffing an envelope? So what the envelope is is we're putting all the files that we just changed inside of this envelope um and then we're going to ship it off back to github. So what git add does?

A

Is you put the files in the envelope and then we use git status to see what files are in the envelope? We can see that it is pizza to rs and the final command I like to think about is zipping. The envelope which is going to be git commit um what git commit does. Is it just finalizes that package, so it can be sent up, and one thing a commit does need is a message on it, so the message should say: no. What does this package contain?

A

What does it do and what this does is it fixes the entire issue awesome and you can also do something which is, if you do hit, commit and then dash a you, can skip this and it's just a faster way to do it, but great now, we've added we've committed and it's finally time to push it up. So we just do git push.

A

And there it goes, it is now being sent to github.

A

So if we refresh our fork, we will see that 26 seconds ago um it just received a package from my computer and it has updated the source code um and you'll see the github will display the message that we sent right here so great um now, there's just one last step.

A

I think you remember it's creating the pull request um and a good time is really handy, because it will tell you right here um that this branch is one commit ahead of pizza fan master and what that means is that since I fixed the issue since I've edited the code base now, my repository is further along than the core one, and in order to make the two equal, we have to create a pull request so that my repository can be merged back into the main one. So that's exactly what we're going to do.

A

So I hit pull request, and now it gives you a screen where it handily shows you what's been removed the deletions and then what's been added awesome. So then, finally, we're just going to hit hit, create pull request and here's the best screen ever we're finally ready to type it up. So what I'm going to do is leave this very quickly to just go back to the presentation and talk about. Oh it'll load.

A

Writing a good pr. So how do you become a pr superstar?

A

There's a few just very quick, um important parts, which is clarity, um so you just want to be very clear about what issue you tackled and you know how you did it but also be concise. You know they don't need to know every detail of how you fixed it. You know someone who's looking at it from maybe a non-technical perspective, who's, just the code maintainer or because there's so many different roles in open source. But not everyone wants to know exactly.

A

You know what function did what, unless it's related relevant to uh what you fixed, but sometimes you can just give a brief um and semi-detailed review and, as I mentioned relevance, you know if you are fixing one issue. You don't want to mention another issue in your pr, because that can confuse the person um who's. Reviewing it, so you just want it to be clear, concise and relevant, so someone who's, maintaining the project can quickly go.

A

You know what this solves the problem: let's merge it and some very quick and relevant to github tips for becoming a pr superstar. um We want to keep the pr title under 65 characters. um This avoids wrapping and, like the text being cut off, so you can, um you know easily see it in an email or, however, you're receiving um it in your inbox. It just makes it easier for readability and you can add the details in the body of the pr, so you don't have to have like 18 different things happening in the subject.

A

Next super important is link the issue that has been addressed so, if you've addressed, you know, issue the tire issue we're going to um put that inside of the pr so that it can know. Github can know innately to close that issue once the um thing has been merged, so you can use certain keywords to show github that you have done this, which is fixes and resolves and also a few others.

A

I think um if the pr is unfinished or someone you know gives you some feedback and they say you know what I think this needs a little bit more work. There's an error here or there's something wrong here. You can convert it to something called a draft pr which is exactly what it sounds like it's just a pr that needs rework, so it's it won't be merged automatically and then finally, the most important point, I think, is that short impactful pull requests are almost always better than long and messy pull requests.

A

So there's a lot of issues in a repo and you look at a few and you're like you know what I can solve all these. I'm a super cool expert software engineer and you go into the code and you solve a bunch of things at once and you do a lot of great work and all of it works and it's awesome.

A

And then you create a pull request and you type up everything you did while that may be cool for you, someone who's coming at that point, knowing nothing of what you did. um It's really hard for them to read.

A

All of that and make sure that you addressed every single issue um as well as you can, because if they can get lost in all the texts- and this goes back to our other point- where conciseness is really key, um so the best thing you can do is if you're going to address an issue, make a pr for that issue and then a pr for the other issue and a pr for the other issue, so that someone doesn't have to do all this work at once, and multiple people can address different pr's.

A

So it's good for a lot of different people for a lot of different reasons, so short impactful over long and messy, and then we're going to go back to the pull request and give it a better title because fixes tire issue isn't the best, so I'm going to say, makes available toppings function and again this probably isn't perfect. Either I'm doing it on the spot, but you can always revise it later or clarify. If someone has a question present the correct toppings.

A

So we set fixes, then we're going to look at it. Our chefs are running out of wheels in their car. That is the issue fixes number seven um by changing the and we can sometimes use a code block to reference a function. So I'm going to do available, toppings function to correctly return the strings, pepperoni, onions bacon.

A

What was the last one uh and sardines?

A

Previously? It was returning the tire, no matter what topping was chosen great. So this is super simple um gets to the point. It fixes fixes this issue by changing this function. To correctly, do this, instead of what it was doing before awesome, so we're all set we're going to create our pull request.

A

Cool, so congratulations um you are now done, I mean I guess I did it, but if you, if you followed this all the way through, you went from having no experience um using github using git to fixing an issue and then creating a pull request as an open source contributor. You are done with your role. um The code maintainer can now go into this pull request, review it make some changes.

A

They can leave a comment here. You know, maybe you should fix this or add this. They can review the files that have been changed here and then they can choose to merge it, which is awesome so yeah. It can be that simple.

A

So that's great we're going to oh one, more thing I forgot to mention, but when you're working on an issue um it can be good to, I should have done this before I made the pr but say you know what I'm going to try this issue.

A

This is just a good practice, because, if there's a bunch of people who want to try an issue, you don't all want to be doing the same thing, and it also lets the people who maintain the code, know that someone's working on it that they might have someone to pair a program with, or it's basically just good communication.

A

Awesome so now we have successfully done um and solved a pizza crisis. It's gonna we're gonna, look at a few projects that brooke has to offer.

A

So I'm just gonna discuss very briefly um a few embark projects. We maintain a lot, but I'm gonna go over something called texture synthesis, um one called rust, gpu and physics rs, but, as I said there are so many we won't cover today. um These are all in rust, all um repos that we maintain. So you know if if these don't fit the bill for you check out some others so much there, I have no idea what all these are, but there's just so much great. So the first one. This is one of my favorites.

A

That we maintain is something called texture synthesis.

A

So texture synthesis is a lightweight rest api for example-based image generation, and if that is confusing to you, it was to me as well. So what it really means is it's combining pictures to make new pictures. um Two plus two equals four, so you can try it yourself.

A

um All you need to do is create a new rest project in your favorite ide, visual studio or otherwise. um Then you can add texture synthesis as a dependency, so, if you've coded with rest before you just go to crates to, I o look up texture synthesis um and then add it to your project and then you can pop in your own images and combine them into cool new compositions right in the command line. So if you look over to the right, this is what's going on.

A

You use these three images you put in the code that we have. We have sample code on the github for texture synthesis you put in that code. Put these three images in a folder run a little script on the command line, and you have generated a whole new image, and this can this produces some really crazy results. So I recommend doing this on your own pictures and showing your friends and okay. If you did that and you're like this is awesome, I want to do more.

A

You can become a contributor because you know that's what I'm talking about today. It's like, if you love a software or you, you think it's really cool but you're like wait. What if we did this or I want to try fixing something, um go for it, I'm starting with this um this repo, but it doesn't have the most issues, the ones we're going to discuss, but this one is open.

A

It has 10 open issues um and feel free to tackle one or create your own, and this is an important point remember to create an issue before you work on something. So if you're working on texture, synthesis or any open source project, if you're working with the system- and you say you know what I see this tiny issue- I want to make a pr for it.

A

If it's really really small and you think it doesn't require a whole issue to explain why you want to fix it example being a typo in documentation, um just go go for it create a pr. That's why I said typically, but if it is something that's even a little bit bigger, a good practice is just to create an issue. Even if it's a really small issue just outline what's wrong and then do your pr, even if you've come up with a pr first, because chances are someone might notice something you don't about the issue.

A

They could even point out that it isn't true, so it's really good to make an issue, discuss it a little bit and then get into coding. It's also great. If someone wants to tackle the issue that you don't want to tackle, so you can raise an issue and say you know what I don't want to deal with this awesome, so that was texture synthesis.

A

Another one I want to cover is physics to rs. So what is physics rs? um It is a wrapper over um the physics uh um physics engine by nvidia, um which is done in c plus plus, but we are wrapping over it with rust, which, with one of our engineers uh nicknamed an unholy fusion, um he did a whole talk on it that you can watch that I can link to as well. But you know why should you use this um well what's great about this?

A

Is you can add your own physics engine to your rust project and since it's an industry standard, it's um it's feature rich. It's super reliable and it's really cool because you get to see how we did a c plus plus wrapper to interact with rust. So, if you're interested in either of those languages, it's really cool how you can see them connect. This can apply to connecting you know any other two languages.

A

And then, finally, if you want to just go super simple with it, you can use this to create physics in the command line. So you can see on the right. It's a tiny ball, jumping all over the command line. So there's a lot of things you can do with uh phys x.

A

Finally, um the last little project I'm going to cover today is called rust gpu. This is our recently announced um project. It's really big, really popular right now um and we're really excited about it. So why is it cool? Well, rush review is basically a project to make rust a first party language for gpu code. um Those are the um those of you who are familiar with gpu code, it's basically or who are not familiar. um Shader languages or gpu code is what you do to make uh things like on the right here.

A

It's what how things look and appear in game engines and on your computer. So typically, these languages are just gl, sl or hs hl sl, um which are very you know, kind of niche languages that you wouldn't get exposure to until unless you were explicitly working on shader code. So this has just disadvantages. Like you have to specifically want to um create shaders and do shader coding for you to explore these languages, but, let's say you're, just a rust, um you're someone who's a hobbyist rust programmer and what, if you want to make a shader?

A

Well now you can so that's what we're working towards um stuff you can do right now is rush. Gpu is in a state where you can already start creating simple shaders using rust. You can share them, which is something that you can. You know start doing. If you don't even want to extend the program, so you can do that right now and share them on our discord or twitter or whatever, um and if you want to delve deeper, you can solve open issues like implementing loops and switches.

A

um It's a very active community, so you can jump into our discord and already start talking about it and, as I said, it's a big thing right now, so where our texture synthesis was at 10 issues, there's over 70 open issues to tackle with rest gpu, and this is all it's all happening. You know every day um things are always changing.

A

uh So yeah, as I said again, it's like frequent discussion on discord. You can jump in see. What's going on, you can even just jump into the comments uh going on any open issue. Look at a pr um there's, just so many different ways to get involved and getting involved in early stages of early stages of a project is a great place to be because there's just so much ability for you to make change and really be impactful with the project, and it's really cool because you get to watch it grow and evolve.

A

You know every new release of rush gpu invents a really cool new feature, and finally, this is just a sample. You know, as I was saying in the beginning, when I had no idea what open source was or what github was. I think what would have made me more interested is just knowing that there was a project that was really aligning with my interests. You know when I came to embark. You know game development was always something I cared about so now.

A

Knowing that open source game development was a huge part of what embark did that got me? Super energized about getting involved with open source so find something that really aligns with your interests. If it's in the rust ecosystem creates to io is a great place to start even looking on just github for rest projects and then, of course, if you want to jump into our ecosystem, I'm always here to answer questions about it, and this is our bonus. Fun fact to end off the presentation.

A

The restaurant that I mentioned in the demo was inspired by a restaurant that does exist and it's not a coding mistake. This picture is actually from the restaurant where they serve thai pizza and I'm not sure what this is, but that um and even pumpkin pizza, it's called pizzeria batte popo and it's in brazil. Apologies for the pronunciation, but it's a great place, and you should definitely check it out if you're over there um and finally yeah this presentation should only be the beginning.

A

You know if you're new, to open source like I hope this is just a first step, a second step, a third step. There are so many cool rush projects to explore in embarks ecosystem and beyond and any other language. There's just so much stuff on github, um so yeah. Thank you so much for listening and I'm gonna link the link to both this project and bark embark. Studios github account as well as our discord. If you want to start talking about rush gpu or any of our other projects, but yeah thanks so much.

A