 going to be talking about how to contribute to Elixir and Phoenix. And this is a beginner level talk aimed at people who have never contributed before, really never been involved in an open source, open development project before. So first things, we're going to be talking about building things from source. And there's necessarily going to be a lot of shell commands and output on the screen. Don't try to scribble it all down. That's my blog and there's a page of talks. There are a couple of blog posts that go over how to build Elixir from source, how to build Phoenix from source. I'll show it on the screen because I want you to see that it's easy, that it's possible, that you can do it. But I would love to run this as a workshop where you have tasks to complete and you can actually do it and we can walk around and help you if it doesn't work. Maybe next year. And a little about me. My name is Wendy Smoke. I got involved in open source and open development way back. I had to look this up in 2005 at the Apache Software Foundation. And I got involved the same way I'm going to encourage you to get involved, which is by asking questions, answering questions, fixing up the documentation. And while I was at Apache, I was having so much fun in Java that I completely skipped over Ruby. And I remember going to talks by Neil Ford and he said, you really need to learn this thing. And I was like, oh, Java is way too much fun. So I missed that entirely and then I was away from technology for a while. And lately I was kind of looking for something new and something new to learn. I looked at Closure. I didn't really want to be on the day of VM anymore. And so this Elixir thing happened. I think it was maybe back in July. I picked it up, started playing with it. I started asking questions and I've even answered a few and I've fixed up the documentation a little. And so I'm really excited to see where this is going to go from here. When I talk to people about getting involved in open source, usually I have to stop and say things about watching out for the project culture, hanging out in the mailing list, making sure there aren't any toxic personalities that are going to make your life miserable. And just thinking about where you're going to invest your time before you kind of dive in. This happened back when Ron Jeffries, who's the signer of the Agile Manifesto, was casting about looking for something new for himself to learn. And of course everyone was saying go, Closure and Elixir. And I just said that others can give technical reasons why the Erlang VM is the best thing for concurrency or whatever. But I haven't been this happy in a community since I was involved at Apache all those years ago and that's something special. I can't put my finger on it, but it seems like we've got just a really good group of people that have gathered around this technology and I'd really like it to stay that way and it's incumbent on all of us to keep it that way. So why would you want to do this? Presumably you have a day job or you're in school and you work all day. So why would you want to come home and work more and not get paid for it? So maybe you want something that it maybe you are lucky enough to be using it in production and so many people raised their hands earlier and you need to do something that it doesn't do and this is the old scratcher on itch motivation. So you make something you make it do something it doesn't do and you contribute it back in the world's a better place. Maybe like me you want to just learn something new. Functional programming is all the rage these days, right? So you want to learn this new thing that's been around for a while. Making new friends. I've met so many people working online. I go off to conferences and my husband's like you don't know these people. Yes, I do. I've known them for years online. I've just never met them. And back to the practical point, building your resume. This stuff doesn't look half bad when you put it on your resume. So the skills you learn interacting with open source communities, debugging other people's code can be really attractive to employers. So that's not something to dismiss. As far as once you've decided that you want to contribute, what are some things you can do once you're here? So I come back to asking questions. If you're stuck on something, chances are someone else is too. And they may not have the time or be brave enough to put that out there in public. So if you take the time to research your question, get a good question out there, and put that on the mailing list, that is a really big contribution because someone will come along and answer it. And as you learn more, you'll find that next week someone will ask the same question you were confused about the week before. I know that. And like Jessica said last night, thanks so much to Jessica and Jose this morning for making these points already, that the experts are not the best people to answer the questions from new people. Or even to write the documentation. Because when the experts explain things, they tend to leave stuff out or they put things in order because they don't know what you don't know yet. So for a language and a framework and the surrounding technologies, this new, writing it down is one of the most important things you can do and contribute. Another really fun thing to do is reproduce issues. So if you're on IRC or Slack or on the mailing list and someone else posts a problem, you can try to reproduce it. And back to resume skills, debugging other people's code is something that's really, really useful. So if you can take a small snippet of a problem that may not even be that well described and figure out what's wrong, you can definitely use that skill later. And when you maybe you look at it and it's just a typo. So you can help get that person past their their issue. They just needed another set of eyes on it. Maybe you'll get to the point where you can make improvements. And it's important to note that this is not just code. This is not just submitting a patch to Elixir that fixes a bug. This is all the little things around it. I went to a talk on AXRM yesterday. So that is not committed to Elixir, but it's part of the ecosystem. And it's a really useful tool that we need to do reproducible releases. So maybe you'll come up with something to add to the ecosystem. And like Jose said, they're often pretty conservative about what actually goes into the framework and the language itself. So if you come up with a really great idea, implement it as a separate thing, let people test it out, beat on it, find where it can be improved. And then maybe it'll get merged in later. Maybe it'll stay as a separate thing. But don't think that just because you're not committing to Elixir core that you're not contributing. And then getting to the point where maybe you are adding maybe your new thing does actually get merged in and then you're officially part of Elixir. On the topic of asking questions, this is the first part where you can kind of make a misstep and end up in the wrong place and kind of get told that you're doing it wrong. So back when I started doing this, we had mailing lists, and that was pretty much it everything he had a question, you went to the mailing list. That's where everything was we still have that. But now it's Google groups, which is the old news groups that got combined. So there are two for each of the big projects. There's Elixir talk and Elixir core and then Phoenix talk and Phoenix core. If you're asking a user level question, you belong on the talk list. That's kind of the first place that you may show up on the issue if you ask on the issue tracker or you show up on the core list, people are really nice and they'll probably answer you but they may tell you that go over to the talk list. So that's something that you can just know before you show up in the wrong place and get not really recommended. But you know, it cannot can be not a great first experience if you do it wrong in public. And now we have Slack and IRC. Of course we had IRC has been around forever but especially at Apache it wasn't really used for user support and questions. Stack overflow is where all my answers come from. There's something on Reddit. I don't even have a login and someone mentioned code wall. There's all these places now that you can ask questions. So it does get pretty scattered. These are only the English language ones that I'm vaguely aware of. I'm pretty sure it's duplicated in other languages and I'm not even aware of where those are. So when you start answering questions, you can certainly reply wherever it is that the person asked. But consider that if you're on Slack or IRC, those wonderful answers will disappear because Slack we don't have the archives for. IRC is logged but it's not threaded and it's really hard to search. So if you have gotten a great answer or posted a great answer, often people will post a gist or a pace pin of their question. They don't ever update it. So one of the great things you can do is grab that you can actually fork the gist and fill it in and with the question and answer and it's a really quick way to just capture it. The projects have wikis attached to them, a lot of them on GitHub and if it's not turned on you can ask them to flip it on. I have one on my own personal website and I'll do the same thing if there's a great conversation on IRC I'll just like copy it and paste it to a page on my wiki because someday I'll go back and document it, which hasn't really happened but at least it's there and I'll find it again. You can blog several people have mentioned this if you don't have one already, start one. Jeremy Singleton did a really great blog post recently where he didn't understand something and he asked Chris and Chris patiently explained to him what was going on and had him go through some exercises. Well he wrote that up as a blog post and said I was confused about this and here's what Chris had me do and here's when the understanding started to dawn and then here's the final thing that was true and that is great to have out there. The reason I'm up here today is probably because of my blog where I've posted all my ramblings about things I didn't understand and how I kind of stepped through and figured out some of the things and then my favorite the official documentation. So we're going to look at how to make your first contribution to the documentation without ever leaving your browser. This is the first kind of easy win that you can do. We're going to start with the Phoenix guides and the link that the arrow is pointing to is the guides and if you click in there I've clicked it on the community page. So this talk is all about kind of develop our onboarding how to make it easy to get in and I was focused on that last line which says if you have a question about the docs open an issue or send a pull request. I thought well we've just finished telling people that if they have a question they should ask on the mailing list so I wanted to fix that and this particular page is important because open source projects are essentially competing for your leisure time. There is there are plenty of other things that you could be doing. My sadly neglected summer garden after I discovered Elixir is a testament to that because I kind of never went out there and we did it again. So or maybe someone is getting up one hour early they committed to like getting up in the morning and spending an hour learning Elixir while the house is quiet and that's all the time they have. If they get stuck and wander away we may lose that contributor. So as you're as you're new to the project anything you can do to help the next person who is new have a smoother onboarding experience is great. So and also that page doesn't even say where the document where the source code for the guides actually is. So that could that could have stopped someone cold if they didn't already know about GitHub and where these things are. So to make my change I discovered preparing this talk that that little pencil in the GitHub UI is a magic button. It will behind the scenes fork and branch and do all that for you so you don't really have to worry about it. And it's saying edit this file in your fork of this project. I've used it in my own projects to just kind of make a little typo change but I never realized what happens if you clicked it in someone else's project. So it'll handle all that for you behind the scenes. If you don't already have a fork which is your copy of the repository it'll do that for you. And every time you click it it branches up to like the very latest. So submitting a change will write to a new branch in your fork. So having clicked the magic button GitHub is going to handle making a copy of everything for me. I can make my changes and then click the preview. Both my hands are full now so still no? Okay we'll try this. And I can see the changes that I've made. I actually changed a few more things than the bottom line but it'll let you see what you've changed. And if you scroll down to the bottom of that page you'll get to propose your file change. So you write a short description about what it is you're changing. This turns into the commit message. You're still working in your own copy so no one knows you're doing this yet. I think it is visible but you haven't announced your intentions yet. So once you click the create pull request button now you're now you're working on the thing that you're going to announce to the community. So you can put in a description here. So if you're fixing an example explain what was confusing because there are plenty of places, good with this, so there are plenty of places in the documentation where things are technically correct but like I was talking about before when the experts are writing documentation they don't know what you don't know at that point because they've got all the information in their head. So I've fixed a couple of things where it was absolutely correct it's just that that topic wasn't introduced until the bottom of the page so a new person reading it is kind of not real sure what's going on. So now when you click create pull request now it actually exists and the documentation team knows that you want to make this change and it's in the list. I actually had to find one to do so that I could take these screenshots because the Phoenix Guides team are so on top of pull requests that they merge them or comment on them right away and that list is usually empty and if all goes well then they say thank you and they and they merge it in and you get hearts on your this is Sturzay's thing so you'll get you've got your colored hearts on your as a comment on your pull request and you get listed as a contributor and then you get to celebrate on Twitter but sometimes they want to change or it's not quite right if you if it's your first time and you get to this point then ask for help because the ways of get are incomprehensible sometimes they will ask you for things like can you please squash your commits well if you're brand new to get and you don't quite know what that means it can be kind of off-putting so just ask if you don't want to ask on your pull request email me with a link to it and I will help you figure out the right things to type to make get happy I have I saw my cheat sheet and let's see so that that that's making your first patch of the documentation without needing to ever leave your browser so if you're just reading something and even if you're off developing something this is an easy way to just get something quick in there without the whole checking out and fetching and merging and all that stuff that goes along with it so another thing you can do is reproduce issues and you can just reproduce if someone comes along and says this I did a and b happened and I expected see you can work through their steps and reproduce it and try to help them figure out what's gone wrong at some point someone's going to say I think that's fixed on master I think and I think that's already fixed so can you try that on master and see if it's still is a problem so we'll look at phoenix assuming you have an existing project that already has a mix.exe file the first thing you can do is just open up your mix.exe file and swap out the phoenix dependency and point it straight at github and then tell mix to go get your dependencies and that's going to pull down the latest and greatest source code for phoenix and you saw me go from like 0.14 to 1.0.3 now that may not work it depends on what else has changed and it's also possible that the change you're looking for wasn't actually in phoenix so the next thing you can do to try out some issue that you need to see whether it works or not in phoenix is to start a brand new project with the bleeding edge of phoenix and phoenix comes in two pieces there's the installer the thing you typically install and then the actual set of phoenix libraries so this is a bit of the phoenix read me which is in the source code and has some instructions and why things are the way they are i've i made several of these changes while i was trying to figure out why things didn't work the way i expected them to so the first thing we'll do is clone the phoenix source which looks like usual you have to change into the installer directory to do this it doesn't work anywhere else you've got to be in that directory and if you're in that directory and you check what version of the phoenix installer you're using maybe it says 1.0.2 there's a trick here because if you have previously followed the installation instructions and installed phoenix you're actually using the one that is installed over under your home directory so if you're going to work on the bleeding edge in the installer directory and try out a brand new phoenix project you actually have to remove there's a mixed uninstall command but that is the easiest way to just get rid of it and now when you type mix phoenix new you're actually using the code in the directory you're sitting in and this is a the usual command mix phoenix new the test the name of the project that you want to generate that project has the path to that project has to be within the phoenix checkout we'll see why in a minute and that dash dash dev switch is the secret so this is what gives you a phoenix project that uses the very latest phoenix code and it will do its usual thing and prompt you to install dependencies and if you drop into your new project and look at the mix.exe file this is what the dash dash dev switch got you uh it defined phoenix with a relative path so now you have your bleeding edge project pointed at the bleeding edge of phoenix source code and that override will keep anyone else from changing you and then you can start it and the usual at this point you can drop into that you're in the directory you can try out whatever thing wasn't working with whatever issue the person was having whatever new feature you want to try out and you can try to reproduce it and take a look but what if the issue wasn't in phoenix but was kind of in the language itself so we'll look at how to build elixir itself so you you heard josey talk about all those new things that might be coming one dot master is now set at one dot two dot oh dash dev and that's where those things are going to be landing so if you're interested in trying out those new things or possibly participating in uh in developing them this is where you'll need to be back to the elixir website the installation instructions have a bit on compiling from source these by virtue of me being on a mac these instructions all work on mac people are doing this on windows so if you're interested in that post on the mailing list and one of the people who are familiar with it will pipe up and help you so again we're going to grab the elixir source code and then drop into the directory building elixir is a little different that it's not mixed because elixir doesn't yet bootstrap i'm not sure where if that's even on the list but it's make clean test that was on the the read me it's going to spit out tons of output at the end i'm not syntax highlighted but all the dots should be green if all the dots are not green you should probably open an issue or come ask at that point you've built it so then you need to fix up your depend your environment so right now you if before you do this you've probably got elixir installed from a package manager or however you got it originally this will put elixir on your path kind of in front of everything else and once you do this then yeah it's important to put it on the front so you can check which elixir that should be pointed at your at the path to the source code you checked out if it's not you're still you may still be using the installed one which is not the one you want and then elixir dash fee will tell you one dot two dot oh dot dev right now this minute so right now the codon master has never had a release there's a branch for the the one dot one that is still doing patch releases as a an aside now that you know how to build elixir from source you can test release candidates this is really important because the core developers cannot cover all the possible edge cases that you've invented in your applications and it's really useful when the developers say we're going to do a release here's a release candidate if you can test it out and just let them know whether it works otherwise they do one dot one dot oh and then they have to turn around and do one dot one dot one really quick because someone found something in production or you know when they tested it out ready to deploy it that it could have been fixed earlier so it's the same get clone you specify a branch which is really a tag here's get being weird again and I give it a directory to go into that's the third line because if you don't give it a directory to go into it's going to default to elixir you probably already have one of those and i'm only showing the output because it gives you this ominous warning about being an attached head state which you can safely ignore for these purposes then the usual this it's the same bill command in the same output and then fix up your environment the same way so at this point you're pointed at that release candidate and you can test things out and let the developers know and report back either way say I tried it and it worked because the silence they don't know whether anyone tried it out or not now still in elixir if you're fixing up something in the documentation elixir has a ton of doc tests in the in the source code itself so you may be working on those and those aren't quite the same as the phoenix guides you actually need to if you're working on those you need to actually build elixir and then also build the documentation so you have to do both because the doc tests are run as part of the tests and so if you've been messing with the documentation you need to make sure that you didn't break the build and then you need to build the doc so that you can take a look at your changes and make sure that they look the way you want them to do and if you're submitting a patch for the language you may have written your own documentation versus just fixing up something that's already there so we'll see how to build it another little snippet from the readme which has a bunch of commands that you can copy and paste we'll look through them if you were following the directions you're in the you're in the elixir directory and you need to jump up one this this caught me out while I was trying to prepare this I was following I pasted everything on the readme and it didn't work so I determined that it was missing a bit that you need to actually back up one and then in order to build the documentation you need to have xdoc this this is predicated on building the latest of everything with the latest of everything so we're going to check out xdoc and drop into the xdoc directory what this is doing is using the mix that we just built when we built elixir a few minutes ago to build xdoc so this is all this was all written when nothing actually existed yet so you kind of have to once you get into it you can figure out what you already have installed you you you may be perfectly fine using the mix that's already available but it just depends on what you have on in your environment already I thought this was interesting because that do is not the elixir language do it's a mix task called do so in addition to learning all kinds of things about debugging other people's source code I learned new things that I didn't know were possible just because these are you know the experts writing the readmes and they're using all the shortcuts that I didn't know existed so that that mix test do takes a list of of tasks so instead of making two different lines you can combine that so maybe you can use that in your own in builds and again bunch of output so that was building xdoc now up change directory up and over back to elixir and make docs and this will do its thing because elixir like jose said is made up of I can't remember the exact list but elixir itself and mix and the other bits you actually end up with a list with doc sets for several different things so you'll get there's the list that I can't remember ex elixir xunit those are all separate documentation sets and if we take a look that those are the beautiful xdoc format documentation which points out another thing that all contributions are not source code the xdoc team did amazing work on this figuring out there were discussions about which font weight to use and how far to indent things to make the visual experience just what it needed to be those are things that I can't do but I'm glad that other people do them and contribute because now when I build my own project documentation it'll look that great too other things that you can do are I was thinking while listening to some of these talks that some of you I know know how to do animations of concepts and if that's your thing and you know how to animate the concept of some of these complicated things and distributed computing do that and contribute it and then people who want to give talks can can use them so whether you're fixing issues or adding features these are all kind of things you might get to it'd be great if everyone out there was you know developing lots of complicated elixir code but I never will I can probably count on one hand the number of patches I've sent in that actually touch source code for me it's doing things like this it's helping with the documentation to make it easier for other people so don't think that because you're not writing a bunch of source code you're not contributing everyone who's coming who's talking about it trying to convince your coworkers to use elixir is helping so whatever skills you bring or that you want to learn if you come and ask a really great question that gets someone else thinking about it maybe they learn something and then they teach you that's all community building and it's really really important so I'd love to see this community stay open and welcoming like it has been for me so far so I want to say thanks to the conference for inviting me and charge if I were I work for paying for my travel and time to be here the couple of blog posts I mentioned are there you'll find you'll be better off going to my my blog and clicking on them you can find me all of these places elixir talk would be the or phoenix talk depending on what it is would be the best place because I'd love to have more conversations on the mailing list like I said there are so many places to ask questions and they get scattered come on the mailing list and contribute and participate there but if you don't want to talk in public and you're you have a question about any of this feel free to email me I'll do my best to find you the right person who can help my blog follow me on twitter and I'm usually in the IRC and Slack rooms if although I do have a day job so I tend not to participate too much during the day but ping me and I'll come back and answer later if I can and most of all have fun so if it's not fun why are we doing it so I'm hoping to see everyone on the mailing list and contributing next year I want to see someone else up here giving this talk thank you