Contributing to Ember: The Inside Scoop
CC Attribution - ShareAlike 3.0 Unported:
You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor and the work or content is shared also in adapted form only under the conditions of this
Jackson, Robert
Confused about how the release process works? Curious what the heck feature flags are? Wondering which commit prefix you should use for your latest pull request? This talk will answer these questions (and many more). It will include insights into the release process, feature flagging, the build process, which commit prefixes to use, and how to create custom builds with features enabled by default.
 Alright, so I'm going to talk about how do you contribute to Ember? What do you need to know? How can you help? And how can we make this better? So first of all, a little bit about me. I am on the Ember Release Management Team, Frequent Contributor, and just basic open source software addict. I work at Dockyard. We are hosting the WikiGood Ember conference, so hopefully a very, very good conference. It will be up in Boston in the summer, right? So you can also contact us. We do full stack web development, Ember, Grails, whole stack stuff, so end design. So first of all, why is Ember awesome? So because we all know it's awesome, we're all here. It's clearly the best. So why is it awesome? So it's really simple. The answer is very clear. You go to the website, it's obvious. Tomster, right? Oh wait, sorry. So Ember is basically a collection of concepts and ideas, and as Tom and Yehuda said at Fluent, basically it's possibly the only JavaScript framework, self-identified framework. So this gives you assumptions. It makes you faster. It can make you develop quicker. It can get things going better without having to do a bunch of boilerplate or rewrite all your code and all this stuff. Obviously we know this. So that's great. But what really makes Ember awesome is the community. So it's you guys here. It's everyone in IRC. It's the Twitterverse. It's all of you that are contributing back and making it better all the time. So in light of that, we need your ideas. We need your contributions. We need your thoughts. That's how we can all get better. We can all move forward and launch ourselves into the next era, if you will. So currently there's 334 contributors to the Ember repo. There are 430-something people here. So I expect 100 pull requests after my talk, the end of the day. I got a big green button I can push now, so we're good to go. Okay, so what can you do to help out? So the first thing for anybody who's getting started as a beginner or relatively new to Ember, your perspective is actually very, very needed. The core team folks now, myself I guess, and all of the sort of advanced Ember developers kind of know the ins and outs of things, know some of the conventions. They're obvious to us. But as a newcomer, these things that are obvious to us that we just assume and take for granted, you don't know. So you're reading the docs, you're reading the guides. These things are your entry point into how to figure out what these conventions are. And there's a typo. There's something wrong. Something doesn't make sense. So that's the first and easiest place for you guys to get involved and make things better. So I know a whole group of people have been working hard on the docs, on the API docs, the guides, the cookbooks, the whole website. It's a wonderful thing and it can only get better and it's going to get better because of you guys in your proof reading. There's no way that also on the release team or core team or anybody can read through all of the docs anytime we do a release. It's not possible. So we need to crowdsource this and make it better. So the next thing that you can do is as you're going through developing your application, you can, you know, you find bugs. You have issues. You run across roadblocks, file issues, create pull requests for bug fixes. You know, there may be something that other people haven't seen yet. Maybe there's something that can be clarified in a better error message, better assertions. Tom, actually, Yehuda said earlier that bad docs are a bug. So same thing with bad error messages. So the error messages really are basically just another form of documentation to guide the developer through at design time how to make things better. So the last thing that I'm going to talk about is submitting new features, new APIs, changing existing APIs in backwards, compatible ways, and how to go forward and add these features and what that process looks like. Okay. So let's first talk about documentation. So helping with the docs is sometimes painful. The process is not as simple as it could be. The, you know, most of the time you're going to get nitpicked and kind of bike shed on the actual verbiage and wording of what you put in there. And it feels bad, right? So I want to say, since it's often thankless, I want to say thank you, right? So you guys, again, you're making it better and we need to continue. We need to continue with this. So basically, when you find something you've seen something's wrong as typo, something is not explained very well, you're going to submit a pull request, right? So if it's a typo or an issue in the guides, you're going to put it to the guides' website. I'm sorry, the guides repo. So that's ember.js slash website. If it's something in the API docs, you're going to submit a pull request to the main repo. So the key here is how you prefix your commit. So when you submit your pull request, the way that you're going to identify to us when this thing is merged to be able to make sure that this gets backfed into all of the right channels, the beta channel and the release channel and whatnot and get the website updated, is by prefixing your commit. So we're going to talk a little bit about this. It's actually really simple. So there's a whole bunch, there's actually a bunch of specific details on these prefixes, but the pattern is all the same. So in this case, if it's a documentation thing that only applies to Canary or Master, you're going to just say doc. You're going to put it in brackets, you're going to say doc. That's it. So if it applies to beta, you're going to say doc beta. If it applies to release, you're going to say doc release. So I'm actually going to be pushing, hopefully, to be able to publish the website from the current release branch instead of the last tag branch so we can actually filter documentation changes only through not features or changes to code. But if there's a typo, there's no reason to leave that bad API doc with a typo that's already been fixed in Master and beta online for six weeks. That seems crazy. So if you prefix with doc release, then this will be updated the next time we deploy the website. And that's actually coming. It's not quite yet. Ready? So the next thing is bug fixes. So you're going through your code, you find a bug, you find a regression, something's not working properly. It's documented maybe somehow a guide or something says it should work one way and it doesn't. So the first thing you should do is add a test to show the regression if you possibly can. If you cannot add a test, then open an issue and just say, this is what it is. Here's a JS bin. The minimal JS bin that represents the problem set that you're describing with very clear instructions of how to replicate the problem. As we look at JS bin examples, and it's just crazy. So it's not possible for me to digest what is actually the problem or what is all this set up. If I have to scroll through your JS bin example to digest what's happening, it's likely not going to make an impact on me. So after you add a regression test or potentially open an issue, you're going to try to fix the issue. So it may not be obvious. If you can't fix the issue, submitting a pull request with a failing test is a very good thing. It demonstrates what's wrong and lets us jump in, pull that, commit in, and fix it in a separate PR or in a separate merge. So when you submit your bug fix, you're going to prefix your commit. So very similar to the Dockside. So one thing that's a caveat, if the bug is only in a feature, you're actually going to prefix it instead of bug fix, you're going to prefix it with feature. And we're going to get into feature flags in a little bit. But basically, the way, if the feature is not enabled by default, you'll do feature in brackets and the name of the feature and then your commit message. If it's related to actual live code like in beta or canary, not behind a feature flag, you're going to say bug fix beta. And the one thing to note, only very severe regressions and breakages will actually be pulled into the release branch. In theory, bug fix release is a thing. You could do it. But it's not likely that we're going to release a new one unless it's a very major problem, a new tagged release for a previously released version. Now all of this said, you should totally do this except for the security vulnerability. If you have something that seems like it might be a security issue, email the security team. We definitely have been making a habit of working with people and kind of getting this going. The key here is that we want to release these fixes at the same time as a tagged release so that the exposure time for consumer applications is as little as possible. So you can read the full policy on mbrjs.com slash security. And I think our security policy is great, and we should all know and learn it. Also everyone in this room should be subscribed to the security mailing list. That is where we're going to email you and let you know when a new release is done and talk about any errors or security exposures. Okay, so let's talk about features. So what are features? So what are new features? To me, it seems like mbr is a feature. mbr is not behind a feature flag. So what am I talking about? So first of all, anything that adds new API, anything that adds new public API that essentially wasn't in 1.0. So it's going to be behind a feature flag. So anything that's backwards compatible but is still changing the API is also going to be a feature. And all the features are hidden behind feature flags. So feature flags are really simple, sounds complicated, but it's really, really simple. And all it is is just an if block saying if this feature is enabled, run this code. If it's not, then either do something else or I don't need to run it. So the reason we use feature flags is basically to keep the releases stable so that we can iterate on API and changes and updates and new things that are going to be awesome to all of us when we want them, but still be able to have it out there, have it available for people to use and test and play with in canary builds. But we don't have to be locked in to Sembr supporting that API until we're ready and sure that it's good to go. So I think this is a really key point. We've had, there's a couple of features that have been removed before they were, instead of being approved. There's some features that have been completely rewritten, Queer Primes New, for example. I don't know how many iterations Alex is on at this point. But so it's very important and it's important to us to get the API right and this is how we do. So how does it work? It's actually kind of straightforward. I'm not going to say simple, but it's very straightforward. We use a package called the featureify to process the build output and it strips, depending on the flag value in the features JSON, it can strip the code out of the builds that shouldn't be in there. So if you're publishing a certain build and the feature is not enabled, it's going to strip that code out. So it's just not included at all. So how do you know what's enabled? This is something that comes up a lot in IRC or on Twitter. Oh, I thought such a feature was enabled. So the simplest way to tell if a given feature is enabled is just look at the features JSON file in the repo. So if you want to know if something is enabled in the beta, you go to the beta branch and you check out the features JSON. So there's three possible values in the features configuration file. Basically a value of true means that the feature flags are enabled in the build and the flags themselves, like the if blocks, the if itself is removed. So the code is there, but the if is not. So there's, in any else case, is removed as well. A false value means that that feature is completely disabled and is not even in the build. So you can't enable it at runtime. You can't change anything. It's just not there. And a value of null means that the feature is disabled but is left in the build so you could theoretically enable it at runtime. So this is the breakdown of when certain, how features are enabled or disabled in the build. So we have the canary branch where all features, the value is null. So all features are disabled but they're still in the builds. So you can throw a variable in your head and have that feature turned on when you load Ember. So in beta and release builds, this is not true. So the features are either enabled or disabled. So either true or false value and they're stripped. So only things that we have said, this has got a green light, this is go forward, public API are going to be in those things. And even still in the beta, we haven't actually had this to my knowledge yet. But in beta, we could theoretically find a problem with the given feature and have to take it out or move it back to non-enabled by default status for some more work if there's some bug. This hasn't happened but it certainly could. And that's the whole point of the beta process. So a lot of people ask this, can you enable feature flags in a beta or release build? So the short answer is yes, you can. The longer answer and the answer that I think everyone should give you is don't do it. So the main reason you're not going to want to do this is because the bug fixes there for that feature aren't going to be pulled into the beta branch or the release branch, right? So we're going to go through the process, we're collecting bugs, we're fixing things, things were broken, they're updated on master. If that feature is not enabled in beta at the time, we're not going to pull that fix in. So you could be using something that has known bugs and known issues. So basically you can do it but it's not a great idea. Can I enable features in Canary builds? So the answer is yes, please do. We need testers, we need people reporting these problems. But realize that this thing could be gone by the time it hits a public build. It could just be completely removed and nuked as a feature altogether. So how do I enable a feature? So this is it. This is enabling query.prem's new. You would have to put this above loading Ember itself. So I bet many of you actually think this is typo. It is not typo. So Ember-env, the global Ember-env is actually read prior to the end global. So this is so that you could have an end global that is for your app's environment and it doesn't stomp on things. So a lot of people don't know that both of those work and Ember-env is actually looked at first. So how do you contribute a feature? So there's essentially similar to bug fixes or documentation updates. You're going to add the entry to features, Jason. You'll have it with a null value. You'll add it to features and you're going to hide it behind the flags, add some tests and pre-fix commit. Sounds simple. So the first thing you have to do is pick your flag name. So this was something that we didn't really do initially. So there's some features that exist that don't have a flag name that follows this pattern. But basically you're going to pick the package name that you're modifying and then you're going to pick a short feature name. It's descriptive but not insanely long, hopefully. So you're going to add it to the features Jason file. You're going to want to add it last. Some people have been inserting them in the middle, which makes it really hard for me to keep track of the order things are at and keeping track of what's up for discussion at the court team meetings and agendas and stuff. So you're going to set the value to null. And just going to point out that you have to rebase this on every change to the features Jason file. It's actually kind of annoying. Hopefully your feature doesn't sit in a PR too long. So this isn't an issue. But you'll definitely, this is something to be aware of. So you need to add a nice clear description in the features Markdown file. So you can read about what this feature is in just pros, like just a quick couple of sentences, maybe a little example on what this feature is, what it does, so that it's clear so someone can come in and say, hey, what does this feature do? And it's very obvious. And then you're going to want to include the PR, the link to your pull request, adding the feature in the features Markdown file. Now this is kind of like a chicken or the egg problem. I would say you're probably better to submit the PR and then amend your commit to add the link. But you can try to guess the issue number if you want. Good luck. So and then you're going to hide the feature flags behind, you're going to hide the feature behind flags. So this applies to both your test code and your implementation code. So you actually, if you don't hide the test, they're going to be testing something that doesn't exist. And unless your test is really messed up, they're going to blow up. So it's very simple. You say if the feature is enabled, you pass the feature name you chose, and then you have your feature code. If there's code that has to be executed in case the feature is disabled or not enabled, maybe old code, maybe setting a variable in one way or the other, depending on the feature is enabled, you would put that in the else clause. So one thing to note here, you actually can't nest feature flags. So this is currently an issue with the feature file. It's not a big problem. We don't really have this occur often, but it's definitely something to be aware of. So if you're trying to add a feature inside of another feature flag, you're going to have to figure out a different way to do it. So whether it be set a variable and just use it internally inside the other flag or reopen the class or something like that, there's different techniques to do it. You can't have nested. It will blow up the feature file, and it will be an issue. So you've added the feature flags. Your tests are behind the flags. Your code is behind the flags. And all my tests pass. Yay. But you're not actually running the tests for your feature unless you check the checkbox that says enable optional features in the QUnit UI. It's near the top. So you can also run the tests in the command line runner. I don't have the exact syntax here because it's going to go away. Hopefully we can migrate off of the Ruby build process in the next few weeks. So it doesn't do any good for me to explain that. So then you're going to prefix your commit. So this is really simple. It's exactly the same pattern as we talked about before. You're going to have the feature, and then you have the package name or the feature name, sorry. And that's it. So you generally wouldn't have, you would just have that as your commit message. You wouldn't also put some other text, although that's not a huge problem. And the reason we do this, especially for features, it's important elsewhere too. But for features, having the feature and the feature name in the commit message means that we can basically go through the Git log and see all of the commits that were involved in a given feature. So this lets us either remove it if we have to revert or figure out all the different changes that might have had to do with it. So the next thing, sometimes the feature PRs, they may sit there. You might get feedback. You might not be merged immediately. So the review takes time. It has a lot of implications. The public API is very important to us. I think that's a good thing. So please be patient and be polite. If you don't see any activity, you know, feedback, sure you can ask a question, you know, any feedback or thoughts, don't be rude, don't be mean. We all have jobs that we have to do outside of this as well. So once your PR is merged, now what's going to happen? So the first thing we're going to be doing is a security audit. We've had an issue with a feature that was added that actually exposed user input and allowed it and didn't escape it properly. So we had to have a security patch release to resolve it. So we're now going to be doing security audits on the features before we enable them. So the features list of the new features that are not enabled by default are actually reviewed by the core team at the core team meetings weekly or, you know, every couple of weeks when we review them. And essentially it's going to get feedback. And does this make sense? Should we enable this? Is this good to go? Do we need to tell this person, hey, change something? We'd like this to be a little different syntax or whatever. So some of that will happen in the PR stage, the initial PR, but also you'll continue to get additional feedback throughout. So then finally it's going to come down to a go or no go decision. So your feature may be enabled. It may say, no, we don't think this belongs as part of core and it may be better as a plug-in. So the blog post for what's coming in 2014 that was released after the last face-to-face meeting talked a little bit about projects felt and that's making the file size smaller and sleek. So part of that is going to be not expanding the core for things that are easily done as a plug-in. So if you don't need to be part of core, it may be just say, hey, look, maybe this should be a Bauer package. We certainly didn't need to make that infrastructure better and easier to include, but that's likely a possible outcome to your feature. So that's pretty much it on the feature stuff. So we're going to talk a little bit about the release cycle. So Yehuda talked about it this morning, but earlier, we have three channels, the beta, so release, beta and canary. So the beta channel has six weeks, six weekly, sorry, once a week, every six weeks releases. And we're tagging these so that you can test this code and if there's no issues, they're flagged or reviewed, then this is what's going to end up being the final product for the next stable build. So in canary, new features go into canary, bug fixes, dock fixes, everything goes into canary. So this is kind of like the leading edge. It should be stable. I think we pride ourselves on making the canary builds basically work and be very stable, but it's possible that we've had a new change or new tweak that has a bug, so it does happen. So the beta branch is branched from the canary at the end of the cycle. So when we begin the next six week beta cycle, we're going to branch from canary and we will only be merging bug fixes and documentation updates into the beta branch. So new features, things that are not tagged as bug fix are not going to be pulled in, which leads me to reinforce that if your bug that you're fixing in a PR does affect the beta branch, make sure to prefix it with bug fix beta. It's really hard to review all the commits and determine each individual one whether it belongs in beta or not, so help us out and indicate that. So then we do weekly releases. I will say that there are occasions where I'm a tad delayed on doing that, so it's not always right on time, but we try to be very close. We've been pretty good, I think, to this point. So then the release branch is branch from beta at the end of the six cycle and will only be receiving documentation updates, major regression fixes, and security issues fixes. So a lot of commit prefixes. It doesn't seem too complicated, but let's recap it real quick. So there's basically one similar format. It's going to be the type of thing, doc, bug fix, feature, security, and the channel that you're applying to, and then like your message. So doc is used for documentation and targets your affected channel. Same thing with bug fix. It's only for bug fixes, not for new APIs or things like that. And again, only severe bugs will warrant new tags and releases for the release branch. So feature is adding a new feature and is used, and it's also used for bug fixes to give a feature. And security, this is one I didn't actually mention in the slides because it's generally used exclusively by the security team and is simultaneously published to the public repo and with a tag release and likely a patch to older releases that are affected. So basically, we need your contributions. Like I said earlier, I want to see those PRs. I want to see you guys give feedback, tell us how to make it better. It's very important, and that's the way that we're all going to launch forward into the future. So knowing is half the battle. And go with God, get some food, and have a good day. Thank you. Bye.
 Alright, so I'm going to talk about how do you contribute to Ember?  What do you need to know?  How can you help?  And how can we make this better?  So first of all, a little bit about me.  I am on the Ember Release Management Team, Frequent Contributor, and just basic open  source software addict.  I work at Dockyard.  We are hosting the WikiGood Ember conference, so hopefully a very, very good conference.  It will be up in Boston in the summer, right?  So you can also contact us.  We do full stack web development, Ember, Grails, whole stack stuff, so end design.  So first of all, why is Ember awesome?  So because we all know it's awesome, we're all here.  It's clearly the best.  So why is it awesome?  So it's really simple.  The answer is very clear.  You go to the website, it's obvious.  Tomster, right?  Oh wait, sorry.  So Ember is basically a collection of concepts and ideas, and as Tom and Yehuda said at Fluent,  basically it's possibly the only JavaScript framework, self-identified framework.  So this gives you assumptions.  It makes you faster.  It can make you develop quicker.  It can get things going better without having to do a bunch of boilerplate or rewrite all  your code and all this stuff.  Obviously we know this.  So that's great.  But what really makes Ember awesome is the community.  So it's you guys here.  It's everyone in IRC.  It's the Twitterverse.  It's all of you that are contributing back and making it better all the time.  So in light of that, we need your ideas.  We need your contributions.  We need your thoughts.  That's how we can all get better.  We can all move forward and launch ourselves into the next era, if you will.  So currently there's 334 contributors to the Ember repo.  There are 430-something people here.  So I expect 100 pull requests after my talk, the end of the day.  I got a big green button I can push now, so we're good to go.  Okay, so what can you do to help out?  So the first thing for anybody who's getting started as a beginner or relatively new to  Ember, your perspective is actually very, very needed.  The core team folks now, myself I guess, and all of the sort of advanced Ember developers  kind of know the ins and outs of things, know some of the conventions.  They're obvious to us.  But as a newcomer, these things that are obvious to us that we just assume and take  for granted, you don't know.  So you're reading the docs, you're reading the guides.  These things are your entry point into how to figure out what these conventions are.  And there's a typo.  There's something wrong.  Something doesn't make sense.  So that's the first and easiest place for you guys to get involved and make things better.  So I know a whole group of people have been working hard on the docs, on the API docs,  the guides, the cookbooks, the whole website.  It's a wonderful thing and it can only get better and it's going to get better because  of you guys in your proof reading.  There's no way that also on the release team or core team or anybody can read through all  of the docs anytime we do a release.  It's not possible.  So we need to crowdsource this and make it better.  So the next thing that you can do is as you're going through developing your application,  you can, you know, you find bugs.  You have issues.  You run across roadblocks, file issues, create pull requests for bug fixes.  You know, there may be something that other people haven't seen yet.  Maybe there's something that can be clarified in a better error message, better assertions.  Tom, actually, Yehuda said earlier that bad docs are a bug.  So same thing with bad error messages.  So the error messages really are basically just another form of documentation to guide  the developer through at design time how to make things better.  So the last thing that I'm going to talk about is submitting new features, new APIs, changing  existing APIs in backwards, compatible ways, and how to go forward and add these features  and what that process looks like.  Okay.  So let's first talk about documentation.  So helping with the docs is sometimes painful.  The process is not as simple as it could be.  The, you know, most of the time you're going to get nitpicked and kind of bike shed on  the actual verbiage and wording of what you put in there.  And it feels bad, right?  So I want to say, since it's often thankless, I want to say thank you, right?  So you guys, again, you're making it better and we need to continue.  We need to continue with this.  So basically, when you find something you've seen something's wrong as typo, something  is not explained very well, you're going to submit a pull request, right?  So if it's a typo or an issue in the guides, you're going to put it to the guides' website.  I'm sorry, the guides repo.  So that's ember.js slash website.  If it's something in the API docs, you're going to submit a pull request to the main  repo.  So the key here is how you prefix your commit.  So when you submit your pull request, the way that you're going to identify to us when  this thing is merged to be able to make sure that this gets backfed into all of the right  channels, the beta channel and the release channel and whatnot and get the website updated,  is by prefixing your commit.  So we're going to talk a little bit about this.  It's actually really simple.  So there's a whole bunch, there's actually a bunch of specific details on these prefixes,  but the pattern is all the same.  So in this case, if it's a documentation thing that only applies to Canary or Master, you're  going to just say doc.  You're going to put it in brackets, you're going to say doc.  That's it.  So if it applies to beta, you're going to say doc beta.  If it applies to release, you're going to say doc release.  So I'm actually going to be pushing, hopefully, to be able to publish the website from the  current release branch instead of the last tag branch so we can actually filter documentation  changes only through not features or changes to code.  But if there's a typo, there's no reason to leave that bad API doc with a typo that's  already been fixed in Master and beta online for six weeks.  That seems crazy.  So if you prefix with doc release, then this will be updated the next time we deploy the  website.  And that's actually coming.  It's not quite yet.  Ready?  So the next thing is bug fixes.  So you're going through your code, you find a bug, you find a regression, something's not  working properly.  It's documented maybe somehow a guide or something says it should work one way and it doesn't.  So the first thing you should do is add a test to show the regression if you possibly  can.  If you cannot add a test, then open an issue and just say, this is what it is.  Here's a JS bin.  The minimal JS bin that represents the problem set that you're describing with very clear  instructions of how to replicate the problem.  As we look at JS bin examples, and it's just crazy.  So it's not possible for me to digest what is actually the problem or what is all this  set up.  If I have to scroll through your JS bin example to digest what's happening, it's likely not  going to make an impact on me.  So after you add a regression test or potentially open an issue, you're going to try to fix  the issue.  So it may not be obvious.  If you can't fix the issue, submitting a pull request with a failing test is a very good  thing.  It demonstrates what's wrong and lets us jump in, pull that, commit in, and fix it in a  separate PR or in a separate merge.  So when you submit your bug fix, you're going to prefix your commit.  So very similar to the Dockside.  So one thing that's a caveat, if the bug is only in a feature, you're actually going to  prefix it instead of bug fix, you're going to prefix it with feature.  And we're going to get into feature flags in a little bit.  But basically, the way, if the feature is not enabled by default, you'll do feature  in brackets and the name of the feature and then your commit message.  If it's related to actual live code like in beta or canary, not behind a feature flag,  you're going to say bug fix beta.  And the one thing to note, only very severe regressions and breakages will actually be  pulled into the release branch.  In theory, bug fix release is a thing.  You could do it.  But it's not likely that we're going to release a new one unless it's a very major problem,  a new tagged release for a previously released version.  Now all of this said, you should totally do this except for the security vulnerability.  If you have something that seems like it might be a security issue, email the security team.  We definitely have been making a habit of working with people and kind of getting this  going.  The key here is that we want to release these fixes at the same time as a tagged release  so that the exposure time for consumer applications is as little as possible.  So you can read the full policy on mbrjs.com slash security.  And I think our security policy is great, and we should all know and learn it.  Also everyone in this room should be subscribed to the security mailing list.  That is where we're going to email you and let you know when a new release is done and  talk about any errors or security exposures.  Okay, so let's talk about features.  So what are features?  So what are new features?  To me, it seems like mbr is a feature.  mbr is not behind a feature flag.  So what am I talking about?  So first of all, anything that adds new API, anything that adds new public API that essentially  wasn't in 1.0.  So it's going to be behind a feature flag.  So anything that's backwards compatible but is still changing the API is also going to  be a feature.  And all the features are hidden behind feature flags.  So feature flags are really simple, sounds complicated, but it's really, really simple.  And all it is is just an if block saying if this feature is enabled, run this code.  If it's not, then either do something else or I don't need to run it.  So the reason we use feature flags is basically to keep the releases stable so that we can  iterate on API and changes and updates and new things that are going to be awesome to  all of us when we want them, but still be able to have it out there, have it available  for people to use and test and play with in canary builds.  But we don't have to be locked in to Sembr supporting that API until we're ready and sure  that it's good to go.  So I think this is a really key point.  We've had, there's a couple of features that have been removed before they were, instead  of being approved.  There's some features that have been completely rewritten, Queer Primes New, for example.  I don't know how many iterations Alex is on at this point.  But so it's very important and it's important to us to get the API right and this is how  we do.  So how does it work?  It's actually kind of straightforward.  I'm not going to say simple, but it's very straightforward.  We use a package called the featureify to process the build output and it strips, depending  on the flag value in the features JSON, it can strip the code out of the builds that  shouldn't be in there.  So if you're publishing a certain build and the feature is not enabled, it's going to  strip that code out.  So it's just not included at all.  So how do you know what's enabled?  This is something that comes up a lot in IRC or on Twitter.  Oh, I thought such a feature was enabled.  So the simplest way to tell if a given feature is enabled is just look at the features JSON  file in the repo.  So if you want to know if something is enabled in the beta, you go to the beta branch and  you check out the features JSON.  So there's three possible values in the features configuration file.  Basically a value of true means that the feature flags are enabled in the build and  the flags themselves, like the if blocks, the if itself is removed.  So the code is there, but the if is not.  So there's, in any else case, is removed as well.  A false value means that that feature is completely disabled and is not even in the  build.  So you can't enable it at runtime.  You can't change anything.  It's just not there.  And a value of null means that the feature is disabled but is left in the build so you  could theoretically enable it at runtime.  So this is the breakdown of when certain, how features are enabled or disabled in the  build.  So we have the canary branch where all features, the value is null.  So all features are disabled but they're still in the builds.  So you can throw a variable in your head and have that feature turned on when you load  Ember.  So in beta and release builds, this is not true.  So the features are either enabled or disabled.  So either true or false value and they're stripped.  So only things that we have said, this has got a green light, this is go forward, public  API are going to be in those things.  And even still in the beta, we haven't actually had this to my knowledge yet.  But in beta, we could theoretically find a problem with the given feature and have to  take it out or move it back to non-enabled by default status for some more work if there's  some bug.  This hasn't happened but it certainly could.  And that's the whole point of the beta process.  So a lot of people ask this, can you enable feature flags in a beta or release build?  So the short answer is yes, you can.  The longer answer and the answer that I think everyone should give you is don't do it.  So the main reason you're not going to want to do this is because the bug fixes there  for that feature aren't going to be pulled into the beta branch or the release branch,  right?  So we're going to go through the process, we're collecting bugs, we're fixing things,  things were broken, they're updated on master.  If that feature is not enabled in beta at the time, we're not going to pull that fix  in.  So you could be using something that has known bugs and known issues.  So basically you can do it but it's not a great idea.  Can I enable features in Canary builds?  So the answer is yes, please do.  We need testers, we need people reporting these problems.  But realize that this thing could be gone by the time it hits a public build.  It could just be completely removed and nuked as a feature altogether.  So how do I enable a feature?  So this is it.  This is enabling query.prem's new.  You would have to put this above loading Ember itself.  So I bet many of you actually think this is typo.  It is not typo.  So Ember-env, the global Ember-env is actually read prior to the end global.  So this is so that you could have an end global that is for your app's environment and it  doesn't stomp on things.  So a lot of people don't know that both of those work and Ember-env is actually looked  at first.  So how do you contribute a feature?  So there's essentially similar to bug fixes or documentation updates.  You're going to add the entry to features, Jason.  You'll have it with a null value.  You'll add it to features and you're going to hide it behind the flags, add some tests  and pre-fix commit.  Sounds simple.  So the first thing you have to do is pick your flag name.  So this was something that we didn't really do initially.  So there's some features that exist that don't have a flag name that follows this pattern.  But basically you're going to pick the package name that you're modifying and then you're  going to pick a short feature name.  It's descriptive but not insanely long, hopefully.  So you're going to add it to the features Jason file.  You're going to want to add it last.  Some people have been inserting them in the middle, which makes it really hard for me  to keep track of the order things are at and keeping track of what's up for discussion  at the court team meetings and agendas and stuff.  So you're going to set the value to null.  And just going to point out that you have to rebase this on every change to the features  Jason file.  It's actually kind of annoying.  Hopefully your feature doesn't sit in a PR too long.  So this isn't an issue.  But you'll definitely, this is something to be aware of.  So you need to add a nice clear description in the features Markdown file.  So you can read about what this feature is in just pros, like just a quick couple of  sentences, maybe a little example on what this feature is, what it does, so that it's  clear so someone can come in and say, hey, what does this feature do?  And it's very obvious.  And then you're going to want to include the PR, the link to your pull request, adding the  feature in the features Markdown file.  Now this is kind of like a chicken or the egg problem.  I would say you're probably better to submit the PR and then amend your commit to add the  link.  But you can try to guess the issue number if you want.  Good luck.  So and then you're going to hide the feature flags behind, you're going to hide the feature  behind flags.  So this applies to both your test code and your implementation code.  So you actually, if you don't hide the test, they're going to be testing something that  doesn't exist.  And unless your test is really messed up, they're going to blow up.  So it's very simple.  You say if the feature is enabled, you pass the feature name you chose, and then you have  your feature code.  If there's code that has to be executed in case the feature is disabled or not enabled,  maybe old code, maybe setting a variable in one way or the other, depending on the feature  is enabled, you would put that in the else clause.  So one thing to note here, you actually can't nest feature flags.  So this is currently an issue with the feature file.  It's not a big problem.  We don't really have this occur often, but it's definitely something to be aware of.  So if you're trying to add a feature inside of another feature flag, you're going to have  to figure out a different way to do it.  So whether it be set a variable and just use it internally inside the other flag or reopen  the class or something like that, there's different techniques to do it.  You can't have nested.  It will blow up the feature file, and it will be an issue.  So you've added the feature flags.  Your tests are behind the flags.  Your code is behind the flags.  And all my tests pass.  Yay.  But you're not actually running the tests for your feature unless you check the checkbox  that says enable optional features in the QUnit UI.  It's near the top.  So you can also run the tests in the command line runner.  I don't have the exact syntax here because it's going to go away.  Hopefully we can migrate off of the Ruby build process in the next few weeks.  So it doesn't do any good for me to explain that.  So then you're going to prefix your commit.  So this is really simple.  It's exactly the same pattern as we talked about before.  You're going to have the feature, and then you have the package name or the feature name,  sorry.  And that's it.  So you generally wouldn't have, you would just have that as your commit message.  You wouldn't also put some other text, although that's not a huge problem.  And the reason we do this, especially for features, it's important elsewhere too.  But for features, having the feature and the feature name in the commit message means that  we can basically go through the Git log and see all of the commits that were involved in  a given feature.  So this lets us either remove it if we have to revert or figure out all the different changes  that might have had to do with it.  So the next thing, sometimes the feature PRs, they may sit there.  You might get feedback.  You might not be merged immediately.  So the review takes time.  It has a lot of implications.  The public API is very important to us.  I think that's a good thing.  So please be patient and be polite.  If you don't see any activity, you know, feedback, sure you can ask a question, you know, any  feedback or thoughts, don't be rude, don't be mean.  We all have jobs that we have to do outside of this as well.  So once your PR is merged, now what's going to happen?  So the first thing we're going to be doing is a security audit.  We've had an issue with a feature that was added that actually exposed user input and  allowed it and didn't escape it properly.  So we had to have a security patch release to resolve it.  So we're now going to be doing security audits on the features before we enable them.  So the features list of the new features that are not enabled by default are actually reviewed  by the core team at the core team meetings weekly or, you know, every couple of weeks  when we review them.  And essentially it's going to get feedback.  And does this make sense?  Should we enable this?  Is this good to go?  Do we need to tell this person, hey, change something?  We'd like this to be a little different syntax or whatever.  So some of that will happen in the PR stage, the initial PR, but also you'll continue  to get additional feedback throughout.  So then finally it's going to come down to a go or no go decision.  So your feature may be enabled.  It may say, no, we don't think this belongs as part of core and it may be better as a  plug-in.  So the blog post for what's coming in 2014 that was released after the last face-to-face  meeting talked a little bit about projects felt and that's making the file size smaller  and sleek.  So part of that is going to be not expanding the core for things that are easily done as  a plug-in.  So if you don't need to be part of core, it may be just say, hey, look, maybe this should  be a Bauer package.  We certainly didn't need to make that infrastructure better and easier to include, but that's likely  a possible outcome to your feature.  So that's pretty much it on the feature stuff.  So we're going to talk a little bit about the release cycle.  So Yehuda talked about it this morning, but earlier, we have three channels, the beta,  so release, beta and canary.  So the beta channel has six weeks, six weekly, sorry, once a week, every six weeks releases.  And we're tagging these so that you can test this code and if there's no issues, they're  flagged or reviewed, then this is what's going to end up being the final product for the  next stable build.  So in canary, new features go into canary, bug fixes, dock fixes, everything goes into  canary.  So this is kind of like the leading edge.  It should be stable.  I think we pride ourselves on making the canary builds basically work and be very stable,  but it's possible that we've had a new change or new tweak that has a bug, so it does happen.  So the beta branch is branched from the canary at the end of the cycle.  So when we begin the next six week beta cycle, we're going to branch from canary and we will  only be merging bug fixes and documentation updates into the beta branch.  So new features, things that are not tagged as bug fix are not going to be pulled in,  which leads me to reinforce that if your bug that you're fixing in a PR does affect the  beta branch, make sure to prefix it with bug fix beta.  It's really hard to review all the commits and determine each individual one whether  it belongs in beta or not, so help us out and indicate that.  So then we do weekly releases.  I will say that there are occasions where I'm a tad delayed on doing that, so it's  not always right on time, but we try to be very close.  We've been pretty good, I think, to this point.  So then the release branch is branch from beta at the end of the six cycle and will  only be receiving documentation updates, major regression fixes, and security issues fixes.  So a lot of commit prefixes.  It doesn't seem too complicated, but let's recap it real quick.  So there's basically one similar format.  It's going to be the type of thing, doc, bug fix, feature, security, and the channel  that you're applying to, and then like your message.  So doc is used for documentation and targets your affected channel.  Same thing with bug fix.  It's only for bug fixes, not for new APIs or things like that.  And again, only severe bugs will warrant new tags and releases for the release branch.  So feature is adding a new feature and is used, and it's also used for bug fixes to  give a feature.  And security, this is one I didn't actually mention in the slides because it's generally  used exclusively by the security team and is simultaneously published to the public repo  and with a tag release and likely a patch to older releases that are affected.  So basically, we need your contributions.  Like I said earlier, I want to see those PRs.  I want to see you guys give feedback, tell us how to make it better.  It's very important, and that's the way that we're all going to launch forward into the  future.  So knowing is half the battle.  And go with God, get some food, and have a good day.  Thank you.  Bye.
Contributing_to_Ember_The_Inside_Scoop_0_263.png Contributing_to_Ember_The_Inside_Scoop_264_383.png Contributing_to_Ember_The_Inside_Scoop_384_635.png Contributing_to_Ember_The_Inside_Scoop_636_947.png Contributing_to_Ember_The_Inside_Scoop_948_1439.png Contributing_to_Ember_The_Inside_Scoop_1440_1919.png Contributing_to_Ember_The_Inside_Scoop_1920_3851.png Contributing_to_Ember_The_Inside_Scoop_3852_7187.png Contributing_to_Ember_The_Inside_Scoop_7188_7247.png Contributing_to_Ember_The_Inside_Scoop_7248_9179.png Contributing_to_Ember_The_Inside_Scoop_9180_10691.png Contributing_to_Ember_The_Inside_Scoop_10692_10775.png Contributing_to_Ember_The_Inside_Scoop_10776_15311.png Contributing_to_Ember_The_Inside_Scoop_15312_15455.png Contributing_to_Ember_The_Inside_Scoop_15456_16631.png Contributing_to_Ember_The_Inside_Scoop_16632_18695.png Contributing_to_Ember_The_Inside_Scoop_18696_19223.png Contributing_to_Ember_The_Inside_Scoop_19224_20327.png Contributing_to_Ember_The_Inside_Scoop_20328_21707.png Contributing_to_Ember_The_Inside_Scoop_21708_23315.png Contributing_to_Ember_The_Inside_Scoop_23316_24803.png Contributing_to_Ember_The_Inside_Scoop_24804_25343.png Contributing_to_Ember_The_Inside_Scoop_25344_26111.png Contributing_to_Ember_The_Inside_Scoop_26112_27035.png Contributing_to_Ember_The_Inside_Scoop_27036_28007.png Contributing_to_Ember_The_Inside_Scoop_28008_28823.png Contributing_to_Ember_The_Inside_Scoop_28824_29723.png Contributing_to_Ember_The_Inside_Scoop_29724_34259.png Contributing_to_Ember_The_Inside_Scoop_34260_34463.png Contributing_to_Ember_The_Inside_Scoop_34464_35219.png Contributing_to_Ember_The_Inside_Scoop_35220_37571.png Contributing_to_Ember_The_Inside_Scoop_37572_37727.png Contributing_to_Ember_The_Inside_Scoop_37728_37991.png Contributing_to_Ember_The_Inside_Scoop_37992_38363.png Contributing_to_Ember_The_Inside_Scoop_38364_38567.png Contributing_to_Ember_The_Inside_Scoop_38568_38915.png Contributing_to_Ember_The_Inside_Scoop_38916_39335.png Contributing_to_Ember_The_Inside_Scoop_39336_39647.png Contributing_to_Ember_The_Inside_Scoop_39648_40415.png Contributing_to_Ember_The_Inside_Scoop_40416_40426.png