Permalink
Browse files

Initial Commit - Import all my drafts

  • Loading branch information...
0 parents commit 57987ba19b99c89880f48331e2a03f502f8e16d9 @kneath committed Jan 26, 2010
@@ -0,0 +1,110 @@
+<!-- -*-Markdown-*- -->
+
+We spend a lot of time optimizing the front end experience at GitHub. With that said, our asset (css, javascript, images) packaging and serving has evolved to be the best setup I've seen out of any web application I've worked on in my life.
+
+Originally, I was going to package what we have up into a plugin, but realized that much of our asset packaging is specific our particular app architecture and [choice of deployment strategy](http://github.com/blog/470-deployment-script-spring-cleaning). If you haven't read up on our deployment recipe ***read it now***. I cannot stress enough how awesome it is to have 14 second no downtime deploys. In any case, you can find the relevant asset bundling code in [this gist](http://gist.github.com/238291)
+
+### Benefits of our asset bundling
+
+* Users never have to wait while the server generates bundle caches, ever. With default Rails bundling, each time you deploy, each request until your server generates the bundle has to wait for the bundle to finish. This makes your site pause for about 30s after each deploy.
+* We can use slower asset minifiers (such as YUI or Google Closure) without consequence to our users.
+* Adding new stylesheets or javascripts is as easy as creating the file. No need to worry about including a new file in every layout file.
+* Because we base our ASSET_ID off our git modified date, we can deploy code updates without forcing users to lose their css/js cache.
+* We take full advantage of image caching with SSL while eliminating the unauthenticated mixed content warnings some browsers throw.
+
+Our asset bundling is comprised of several different pieces:
+
+1. A particular css & js file structure
+2. Rails helpers to include css & js bundles in production and the corresponding files in development.
+3. A rake task to bundle and minify css & javascript as well as the accompanying changes to deploy.rb to make it happen on deploy
+4. Tweaks to our Rails environment to use smart ASSET_ID and asset servers
+
+### CSS & JS file layout
+
+Our file layout for CSS & JS is detailed in the [README](http://gist.github.com/238291#file__readme.md) for Javascript, but roughly resembles something like this:
+
+ public/javascripts
+ |-- README.md
+ |-- admin
+ | |-- date.js
+ | `-- datePicker.js
+ |-- common
+ | |-- application.js
+ | |-- jquery.facebox.js
+ | `-- jquery.relatize_date.js
+ |-- dev
+ | |-- jquery-1.3.2.js
+ | `-- jquery-ui-1.5.3.js
+ |-- gist
+ | `-- application.js
+ |-- github
+ | |-- _plugins
+ | | |-- jquery.autocomplete.js
+ | | `-- jquery.truncate.js
+ | |-- application.js
+ | |-- blob.js
+ | |-- commit.js
+ `-- rogue
+ |-- farbtastic.js
+ |-- iui.js
+ `-- s3_upload.js
+
+I like this layout because:
+
+* It allows me to namespace specific files to specific layouts (gist, github.com, iPhone, admin-only layouts, etc) **and** share files between apps (common).
+* I can lay out files however I want within each of these namespaces, and reorganize them at will.
+
+Some might say that relying on including everything is bad practice -- but remember that web-based javascript is almost exclusively onDOMReady or later. That means that there is no dependency order problems. If you run into dependency order issues, you're writing javascript wrong.
+
+### Rails Helpers
+
+To help with this new bundle strategy, I've created some Rails helpers to replace your standard `stylesheet_link_tag` and `javascript_include_tag`. Because of the way we bundle files, it was necessary to use custom helpers. As an added benefit, these helpers are much more robust than the standard Rails helpers.
+
+Here's the code:
+
+<script src="http://gist.github.com/238291.js?file=bundle_helper.rb"></script>
+
+Our `application.html.erb` now looks something like this:
+
+ <%= javascript_dev ['jquery-1.3.2', "#{http_protocol}://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"] %>
+ <%= javascript_bundle 'common', 'github' %>
+
+This includes jQuery and all javascript files under `public/javascripts/common` and `public/javascripts/github` (recursively). Super simple and we probably won't need to change this for a very long time. We just add files to the relevant directories and they get included magically.
+
+For pages that have heavy javascript load, you can still use the regular `javascript_include_tag` to include these files (we keep them under the `public/javascripts/rogue` directory).
+
+### Bundle rake & deploy tasks
+
+The `javascript_bundle` and `stylesheet_bundle` helpers both assume that in production mode, there'll be a corresponding bundle file. Since we are proactively generating these files, you need to create these manually on each deploy.
+
+<script src="http://gist.github.com/238291.js?file=bundle.rake"></script>
+
+Throw this into `lib/tasks/bundle.rake` ***and the corresponding YUI & Closure jars*** and then run `rake bundle:all` to generate your javascript. You can customize this to use the minifying package of your choice.
+
+To make sure this gets run on deploy, you can add this to your deploy.rb:
+
+<script src="http://gist.github.com/238291.js?file=deploy.rb"></script>
+
+### Tweaks to production.rb
+
+The last step in optimizing your asset bundling for deploys is to tweak your production.rb config file to make asset serving a bit smarter. The relevant bits in our file are:
+
+<script src="http://gist.github.com/238291.js?file=production.rb"></script>
+
+There's three important things going on here.
+
+**First—** If you hit a page using SSL, we serve all assets through SSL. If you're on Safari, we send all CSS & images non-ssl since Safari doesn't have a mixed content warning.
+
+It is of note that many people [suggest serving CSS & images non-ssl to Firefox](http://37signals.com/svn/posts/1431-mixed-content-warning-how-i-loathe-thee). This was good practice when Firefox 2.0 was standard, but now that Firefox 3.0 is standard (and obeys cache-control:public as it should) there is no need for this hack. Firefox does have a mixed content warning (albeit not as prominent as IE), so I choose to use SSL.
+
+**Second—** We're serving assets out of 4 different servers. This fakes browsers into downloading things faster and is generally good practice.
+
+**Third—** We're hitting the git repo on the server (note our deployment setup) and getting a sha of the last changes to the `public/stylesheets` and `public/javascripts` directory. We use that sha as the ASSET_ID (the bit that gets tacked on after css/js files as ?sha-here).
+
+This means that if we deploy a change that only affects `app/application.rb` we don't interrupt our user's cache of the javascripts and stylesheets.
+
+### Conclusion
+
+What all of this adds up to is that our deploys have almost no frontend consequence unless they intend to (changing css/js). This is **huge** for a site that does dozens of deploys a day. All browser caches remain the same and there isn't any downtime while we bundle up assets. It also means we're not afraid to deploy changes that may only affect one line of code and some minor feature.
+
+All of this is not to say there isn't room for improvement in our stack. I'm still tracking down some SSL bugs, and always trying to cut down on the total CSS, javascript and image load we deliver on every page.
@@ -0,0 +1,35 @@
+<!-- -*-Markdown-*- -->
+
+# Notification Improvements
+
+Separates out pull requests, issues, & issue comments into "notifications" These show up as a badge next to your username in the userbox, and have their own section in the inbox
+
+Today we rolled out updates to the messaging & notification systems for GitHub. There's a few new features, and some tweaks to existing features.
+
+### Notification Center
+
+If you check the account settings page, you'll notice a new tab called Notification Center that holds preferences for all the emails you get from GitHub.
+
+![Notification Center](http://share.kyleneath.com/captures/skitched-20100117-193031.gif)
+
+### Commit Comment Notifications
+
+We've enabled two new email notifications by default: comments on your commits (where you are listed as an author or committer) and comments on commits in your repositories. You can also turn off notifications for noisy commits.
+
+![Commit Comments](http://share.kyleneath.com/captures/skitched-20100117-193552.gif)
+
+### Improved email subjects
+
+All of our email notifications were previously "[GitHub] user sent you a message" — they should be considerably more descriptive now, saying exactly what kind of email they are.
+
+![Email Subjects](http://share.kyleneath.com/captures/default.data-20100117-194222.gif)
+
+### Notifications vs Messages
+
+We also separated out pull requests and issue notifications into a new category under your inbox. Your inbox should now be filled solely with actual messages. Notifications will show up next to your username (in grey), while the inbox count will reference messages.
+
+![Sample Userbox](http://share.kyleneath.com/captures/Commit_cbd162f5526b2bf0e32340964e612acc9f4d29ca_to_kneath_s_watchtower_-_GitHub-20100117-194430.gif)
+
+Another small update is that we've added a *mark all as read* button to the inbox and notification sections.
+
+We know there's always room for improvement with our messaging and notifications — but this should be a step in the right direction.
@@ -0,0 +1,29 @@
+<!-- -*-Markdown-*- -->
+
+On my first day at GitHub, I asked the crew what they wanted to me to do around here. Their response was something along the lines of "make GitHub sexy" Now that we've been rolling out steady UI updates for about a month, I thought I'd take some time and go over what all I've been working on.
+
+I previously covered the [updated dashboard repository lists](http://github.com/blog/513-new-repository-lists-on-your-dashboard) and [gist improvements](http://github.com/blog/523-gist-improvements), but I haven't had a chance to go over the new userbox, [profile pages](http://github.com/kneath), [account pages](http://github.com/account), and [dashboard headers](http://github.com/dashboard).
+
+![New userbox](http://share.kyleneath.com/captures/skitched-57-20091108-173421.jpg)
+
+The new userbox was rolled out to solve a problem we had -- people with long usernames were breaking the UI, forcing links into the next line. I also took the time to reorganize the navigation and spruce up the look & feel.
+
+![New profile pages](http://share.kyleneath.com/captures/skitched-58-20091108-173443.jpg)
+
+The new profile pages were one of the first purely cosmetic updates to the site. You'll notice a new style of page header being rolled out. This header does have some functional benefits -- but they're subtle. On pages that are yours, you'll notice a slight yellow highlight. This isn't terribly useful right now, but as we roll out new features you'll see why I'm going this route.
+
+I was also testing out the waters with this page. GitHub has an extremely particular and vocal audience that doesn't represent the typical web user. I wanted to make sure that the general reaction was positive. Judging from the twitter updates and in-person feedback I've gotten, people seem to like the changes -- so you'll see more of this style around the site in the future.
+
+![New Account Settings Pages](http://share.kyleneath.com/captures/skitched-59-20091108-173500.jpg)
+
+Along with the new profile pages, we also rolled out updated account settings pages. Previously, you had to edit your profile information in-place on the profile page, but now it's grouped with the rest of your settings.
+
+![New billing page](http://share.kyleneath.com/captures/skitched-60-20091108-173516.jpg)
+
+Previously all of the billing information was crammed into a little grey box in the upper right of the account settings page. With the updated account settings page I decided to create a dedicated billing page. This page shows your plan usage in an easier to access manner and (hopefully) makes it easier to upgrade to paid accounts! :)
+
+![New dashboard headers](http://share.kyleneath.com/captures/skitched-61-20091108-173545.jpg)
+
+The last update we've rolled out are new-style dashboard headers. The reason for these aren't entirely obvious right now -- but in time they will become a lot more useful. I realize these new headers do push down the repository lists by about 60px, but it was a compromise that I decided to make to give us room for the future.
+
+Hopefully you guys are enjoying the evolution of the GitHub interface, I've been having a blast watch the feedback pour in after each push.
@@ -0,0 +1,9 @@
+# New Repository Headers!
+
+We just pushed out an updated header design for all repository pages, you can see it in action on any of our [project pages](http://github.com/rails/rails)
+
+![Repository Header Comparison](http://share.kyleneath.com/captures/skitched-20091227-193611.jpg)
+
+The new headers fixed some long outstanding bugs (downloading the wrong branch for example) and added a few new little features (exposing HTTP clone urls, noting which branch you're currently on)
+
+Hope you like 'em!
@@ -0,0 +1,45 @@
+# The birth of a new feature
+
+I've been pretty quiet around here lately, but that's because I've been spending so much time enjoying [my new job](http://warpspire.com/tipsresources/personal/joining-github/). One of the best things about the new gig is how little bureaucracy there is. There's few secrets in the land of GitHub -- ask us what we're working on and we'll let you know. So I thought it might be interesting to write about how we're building a new feature.
+
+## What feature?
+
+The feature is pretty broad: **code review**. In fact it's hard to call it a feature because it's not really something we can add to a checklist. Code review is a process that takes many tools to complete.
+
+The thing is, GitHub offers many code review tools as is. Pull requests notify developers when they have branches ready to merge, issues give you a tool to discuss & track bugs & merge status, and commit/line comments allow you to discuss the code.
+
+But none of this really worked with the flow I was used to.
+
+## GitHub makes git better
+
+Ever since I joined GitHub, [Ryan Tomayko](http://rtomayko) and myself have been talking about how we wish there was a view showing the combination of `git cherry` and `git diff master...` in GitHub. These two commands have been insanely useful in the past for code reviews. For example, if you're in a branch called `new-feature` and you run `git cherry -v master` it will show you all *unique* commits in this branch compared to master. Basically what you'd be merging in:
+
+ main_site(new-feature) % git cherry -v master
+ + 733e176ea97cfdaf77eb01724ce3abce7adeacb8 Add in context switching widget
+ + e859dc59c3bb5147a633a93d8fdc5accb2518ca6 Fake a contexted click-thru page
+ + 501123dbc0e3cc942938df513b27fb2fa076897d Add in some descriptive text
+ + 7d5acf63df5cd8decb3e63f0eebc9cad19cf8fe8 Improve copy for contexted pages
+
+This is awesomely useful. It doesn't matter how many times you merge `master` back into `new-feature` -- `git cherry` shows you the unique work to the branch. Next up is `git diff master...` which shows you a diff of the unique changes to the `new-feature` branch.
+
+So these two commands give you *why* the branch was created (commit messages) and *how* the branch affects the existing code. These are the two principle things I want to see when I review someone's branch/changes. But GitHub is about making git *better* - and the output for these commands is fairly ugly.
+
+## Specs are dead, just ship it
+
+We'd been talking about this in campfire for a while, but we were distracted by other issues. One night I whipped up a quick & dirty comp in Photoshop:
+
+<div class="figure"><img src="/images/posts/code-review/initial_comp.gif" alt="Initial Comp" /></div>
+
+A day or so later, Scott slammed together some code that got the feature off the ground by listing the output of cherry. Ryan hopped in and cleaned things up to get them to a usable state. Pretty much at that point we launched the feature to admins only. At a certain point, I realized that I was using it every day, so we cranked out some simple caching and [let the public in](http://github.com/sinatra/sinatra/compare/0.9.x...master) (assuming you know how to construct the URLs, this works everywhere)
+
+<div class="figure"><img src="/images/posts/code-review/compare_view_now.gif" alt="Compare View right now" /></div>
+
+If you're ever planning out a big feature, I suggest you just start shipping bits of it. This compare view is not what I had in mind for code review, and it's not complete, but it's a dart thrown in the right direction -- and most importantly it's the minimum viable product (launch early, launch often, even after you're launched).
+
+## Brainstorm, dump & sketch it out
+
+<div class="figure right"><img src="/images/posts/code-review/ramblings.gif" alt="Ramblings" /></div>
+
+I'm a big fan of talking your problems out. So the past week I've been bugging everyone in campfire with endless messages about where to go with everything. We even discussed in person quite a bit to figure out where we wanted to go. After this I just started dumping out all my ideas to our wiki (see screenshot right).
+
+It's really important to dump out your ideas after a brainstorming session. Doesn't matter if your medium is text, photoshop, omnigraffle or a sketchbook -- just get the ideas out of your brain and onto a shareable medium.
Oops, something went wrong.

0 comments on commit 57987ba

Please sign in to comment.