Saving Sprockets - Speaker Deck

Tweet

Tweet

Slide 1

Slide 1 text

Type to enter text Saving Sprockets

Slide 2

Slide 2 text

2016 @schneems Saving Sprockets

Slide 3

Slide 3 text

No content

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

Why does sprockets need saving?

Slide 6

Slide 6 text

May 2011

Slide 7

Slide 7 text

Major Feature of Rails 3.1

Slide 8

Slide 8 text

Sprockets is the asset pipeline

Slide 9

Slide 9 text

Sprockets came first

Slide 10

Slide 10 text

BTW

Slide 11

Slide 11 text

They Call me @Schneems

Slide 12

Slide 12 text

Sounds like “schnapps”

Slide 13

Slide 13 text

Ruby “Hero”

Slide 14

Slide 14 text

Ruby “Hero”

Slide 15

Slide 15 text

No content

Slide 16

Slide 16 text

All likeness to Disney owned properties totally coincidental

Slide 17

Slide 17 text

And/or parody

Slide 18

Slide 18 text

(Please don’t sue me)

Slide 19

Slide 19 text

Lawyers

Slide 20

Slide 20 text

Call me by my real name

Slide 21

Slide 21 text

DHH

Slide 22

Slide 22 text

No need to look like Indy to maintain OSS

Slide 23

Slide 23 text

He’s my Sprockets Spirit Animal

Slide 24

Slide 24 text

From 2011 to 2016

Slide 25

Slide 25 text

51 million downloads

Slide 26

Slide 26 text

Rails has 65 million

Slide 27

Slide 27 text

One developer responsible for 2,027 commits

Slide 28

Slide 28 text

68% Sprockets

Slide 29

Slide 29 text

♥♥♥

Slide 30

Slide 30 text

68% Sprockets 0.9% Rails

Slide 31

Slide 31 text

51 million downloads 1 developer

Slide 32

Slide 32 text

One day, Josh left

Slide 33

Slide 33 text

What should we do?

Slide 34

Slide 34 text

Abandon Sprockets?

Slide 35

Slide 35 text

What are the problems?

Slide 36

Slide 36 text

You can’t fix what you can’t define

Slide 37

Slide 37 text

A re-write assumes we know better

Slide 38

Slide 38 text

we don’t

Slide 39

Slide 39 text

Assets are easy, edge cases are hard

Slide 40

Slide 40 text

Established API

Slide 41

Slide 41 text

How many of you maintain code?

Slide 42

Slide 42 text

How many of you want to maintain it forever?

Slide 43

Slide 43 text

No content

Slide 44

Slide 44 text

Losing maintainers is inevitable

Slide 45

Slide 45 text

It’s not always expected

Slide 46

Slide 46 text

No content

Slide 47

Slide 47 text

No content

Slide 48

Slide 48 text

2014

Slide 49

Slide 49 text

When we lose a maintainer it hurts

Slide 50

Slide 50 text

How do we cope with losing a maintainer?

Slide 51

Slide 51 text

Denial

Slide 52

Slide 52 text

“They’ll come back”

Slide 53

Slide 53 text

Anger

Slide 54

Slide 54 text

“Leaving is so selfish”

Slide 55

Slide 55 text

“That was a pretty jerk thing to do”

Slide 56

Slide 56 text

Bargaining

Slide 57

Slide 57 text

“Maybe if we hire them to work on it full time…”

Slide 58

Slide 58 text

Acceptance

Slide 59

Slide 59 text

“They’re not coming back”

Slide 60

Slide 60 text

“Who will take this over?”

Slide 61

Slide 61 text

Rule 1)

Slide 62

Slide 62 text

A maintainer does not OWE you anything

Slide 63

Slide 63 text

“I deserve an explanation

Slide 64

Slide 64 text

Not even an explanation

Slide 65

Slide 65 text

Leaving a project is a personal decision

Slide 66

Slide 66 text

Josh didn’t want to talk about it

Slide 67

Slide 67 text

We should respect what they’ve done

Slide 68

Slide 68 text

Rule 2)

Slide 69

Slide 69 text

You OWE a maintainer respect

Slide 70

Slide 70 text

“But I HATE software

Slide 71

Slide 71 text

Critique software without demonizing the creators

Slide 72

Slide 72 text

I’m going to critique the crap out of Sprockets

Slide 73

Slide 73 text

Critique don’t Criticize

Slide 74

Slide 74 text

No content

Slide 75

Slide 75 text

You are not your software

Slide 76

Slide 76 text

You are not your khakis

Slide 77

Slide 77 text

Josh gave years of his life

Slide 78

Slide 78 text

HUNDREDS of closed issues

Slide 79

Slide 79 text

To @josh Thanks for making Sprockets

Slide 80

Slide 80 text

Rule 3)

Slide 81

Slide 81 text

Words without actions are empty

Slide 82

Slide 82 text

Be actionable

Slide 83

Slide 83 text

Not Helping

Slide 84

Slide 84 text

No content

Slide 85

Slide 85 text

“ES6 support is great…

Slide 86

Slide 86 text

“looks like they don’t have async/await support yet

Slide 87

Slide 87 text

“I need those because of

Slide 88

Slide 88 text

Ask

Slide 89

Slide 89 text

Is this comment adding anything?

Slide 90

Slide 90 text

Hyperbole breeds burnout

Slide 91

Slide 91 text

Be honest

Slide 92

Slide 92 text

Be productive

Slide 93

Slide 93 text

No content

Slide 94

Slide 94 text

No content

Slide 95

Slide 95 text

Complaining accomplishes nothing

Slide 96

Slide 96 text

How do we keep a maintainer longer?

Slide 97

Slide 97 text

How to stay as a maintainer longer?

Slide 98

Slide 98 text

Back up

Slide 99

Slide 99 text

Do we want mantainers to stay?

Slide 100

Slide 100 text

Mic Drop

Slide 101

Slide 101 text

Graceful handoff

Slide 102

Slide 102 text

Almost every day I say “this is insane”

Slide 103

Slide 103 text

6 hours of my life later, I say “this is genius”

Slide 104

Slide 104 text

Maintainers are historians

Slide 105

Slide 105 text

Maintainers bring context

Slide 106

Slide 106 text

Good commit messages

Slide 107

Slide 107 text

Good PR messages

Slide 108

Slide 108 text

Well written CHANGELOG entries

Slide 109

Slide 109 text

Don’t compare to having someone who was there

Slide 110

Slide 110 text

A story is worth 1000 commit messages

Slide 111

Slide 111 text

You can’t ask a commit message a question

Slide 112

Slide 112 text

Did you also consider…

Slide 113

Slide 113 text

LOL I’m a commit message

Slide 114

Slide 114 text

Keep maintainers longer by giving them what they want

Slide 115

Slide 115 text

Respect

Slide 116

Slide 116 text

Help

Slide 117

Slide 117 text

“I don’t have time to help

Slide 118

Slide 118 text

“Gahhhhhh fix all the things for me!!!!!!!!!

Slide 119

Slide 119 text

5 minutes to check snap- faceta- foursquare- tagram?

Slide 120

Slide 120 text

5 minutes to help

Slide 121

Slide 121 text

Contribute to docs

Slide 122

Slide 122 text

Read the guides

Slide 123

Slide 123 text

Fix typos

Slide 124

Slide 124 text

Did you find surprising behavior?

Slide 125

Slide 125 text

Was your behavior documented?

Slide 126

Slide 126 text

Add it to the guide

Slide 127

Slide 127 text

5 minutes to help

Slide 128

Slide 128 text

Submit bug reports

Slide 129

Slide 129 text

SRSLY We don’t know if it’s broken

Slide 130

Slide 130 text

5 minutes to help

Slide 131

Slide 131 text

No content

Slide 132

Slide 132 text

Ask common questions

Slide 133

Slide 133 text

“Was this working previously?

Slide 134

Slide 134 text

Would you rather a maintainer spent time fixing bugs?

Slide 135

Slide 135 text

or

Slide 136

Slide 136 text

Asking for minutiae in issue comments?

Slide 137

Slide 137 text

Give a minute, save a minute

Slide 138

Slide 138 text

If you don’t who will?

Slide 139

Slide 139 text

Exposes you to different parts of the project

Slide 140

Slide 140 text

Helps you grow as a developer

Slide 141

Slide 141 text

10 minutes to help

Slide 142

Slide 142 text

Include a example app that reproduces the problem

Slide 143

Slide 143 text

OMG example apps are amazing

Slide 144

Slide 144 text

“First run $ rails new”

Slide 145

Slide 145 text

No content

Slide 146

Slide 146 text

Could not reproduce

Slide 147

Slide 147 text

“Oh, yeah try…”

Slide 148

Slide 148 text

No content

Slide 149

Slide 149 text

Could not reproduce

Slide 150

Slide 150 text

No content

Slide 151

Slide 151 text

“Can you try…”

Slide 152

Slide 152 text

No content

Slide 153

Slide 153 text

Instead

Slide 154

Slide 154 text

“Here’s an app that reproduces the problem”

Slide 155

Slide 155 text

github.com/ / ExampleApp

Slide 156

Slide 156 text

Give a minute, save a minute

Slide 157

Slide 157 text

Challenge make 1 example app this year

Slide 158

Slide 158 text

30 minutes to help?

Slide 159

Slide 159 text

Try fixing a/ your bug

Slide 160

Slide 160 text

Timebox it

Slide 161

Slide 161 text

Guaranteed to learn something

Slide 162

Slide 162 text

Read other people’s code

Slide 163

Slide 163 text

Navigating and debugging are skills

Slide 164

Slide 164 text

Navigating and debugging are marketable skills

Slide 165

Slide 165 text

No content

Slide 166

Slide 166 text

Go the extra mile

Slide 167

Slide 167 text

How do we make transition easier?

Slide 168

Slide 168 text

What is a maintainer?

Slide 169

Slide 169 text

Someone who knows the stories

Slide 170

Slide 170 text

Someone who takes 5 minutes

Slide 171

Slide 171 text

Someone who takes 10 minutes

Slide 172

Slide 172 text

Someone who takes 30 minutes

Slide 173

Slide 173 text

To help

Slide 174

Slide 174 text

Helping preserves history

Slide 175

Slide 175 text

Helping is the answer to keeping maintainers

Slide 176

Slide 176 text

Helping is the answer to creating maintainers

Slide 177

Slide 177 text

How do we foster a a culture for helping?

Slide 178

Slide 178 text

Previously

Slide 179

Slide 179 text

What do maintainers want?

Slide 180

Slide 180 text

Now

Slide 181

Slide 181 text

What do helpers want?

Slide 182

Slide 182 text

DOCS

Slide 183

Slide 183 text

Sane Code

Slide 184

Slide 184 text

They want what regular users want

Slide 185

Slide 185 text

A good developer UX

Slide 186

Slide 186 text

Non-magical code

Slide 187

Slide 187 text

Backwards compatibility

Slide 188

Slide 188 text

Good deprecations

Slide 189

Slide 189 text

Reliable Tests

Slide 190

Slide 190 text

DOCS

Slide 191

Slide 191 text

$ yard doc lib/ [warn]: In file `README.md':248: Cannot resolve link to ExecJS from text: [warn]: {ExecJS}... [warn]: In file `README.md':439: Cannot resolve link to Tilt from text: [warn]: {Tilt}... [warn]: In file `README.md':248: Cannot resolve link to ExecJS from text: [warn]: {ExecJS}... [warn]: In file `README.md':439: Cannot resolve link to Tilt from text: [warn]: {Tilt}... [warn]: In file `lib/sprockets/unloaded_asset.rb':62: Cannot resolve link to type: from text: [warn]: ...{type: ”application/javascript“}... Files: 70 Modules: 30 ( 10 undocumented) Classes: 48 ( 25 undocumented) Constants: 50 ( 32 undocumented) Methods: 405 ( 72 undocumented) 73.92% documented

Slide 192

Slide 192 text

Sprockets methods are documented

Slide 193

Slide 193 text

Method docs are like unit tests

Slide 194

Slide 194 text

Don’t tell the whole story

Slide 195

Slide 195 text

Easy to get out of sync with reality

Slide 196

Slide 196 text

No content

Slide 197

Slide 197 text

A README tells a story

Slide 198

Slide 198 text

Like an integration test

Slide 199

Slide 199 text

$ wc -w README.md 2619 README.md

Slide 200

Slide 200 text

Sprockets tells a LONG story

Slide 201

Slide 201 text

Helpers love docs

Slide 202

Slide 202 text

Sprockets has docs

Slide 203

Slide 203 text

Y U NO HELPERS SPROCKETS?

Slide 204

Slide 204 text

Design Research

Slide 205

Slide 205 text

User Stories

Slide 206

Slide 206 text

Consider the people using your “product”

Slide 207

Slide 207 text

Introducing

Slide 208

Slide 208 text

Pedro

Slide 209

Slide 209 text

Likes long walks on the beach

Slide 210

Slide 210 text

Favorite food is bagel bites

Slide 211

Slide 211 text

Building the next UBER for goldfish

Slide 212

Slide 212 text

Rails user

Slide 213

Slide 213 text

Cares only about the user level interface

Slide 214

Slide 214 text

//= require “foo.js”

Slide 215

Slide 215 text

Pat

Slide 216

Slide 216 text

Addicted to ES6

Slide 217

Slide 217 text

Loves to fly fish

Slide 218

Slide 218 text

Plugin developer

Slide 219

Slide 219 text

Did you know sprockets has plugins?

Slide 220

Slide 220 text

Called Processors

Slide 221

Slide 221 text

Cares about the processor interface

Slide 222

Slide 222 text

def self.call(input) data = input[:data] # … end

Slide 223

Slide 223 text

Diana

Slide 224

Slide 224 text

Has a dog named Exception

Slide 225

Slide 225 text

Hates mustard

Slide 226

Slide 226 text

Rails Developer

Slide 227

Slide 227 text

I.e. people building an asset pipeline

Slide 228

Slide 228 text

Cares about Low level interface

Slide 229

Slide 229 text

env = Sprockets::Environment.new(".") env.gzip = false

Slide 230

Slide 230 text

Different people need different docs

Slide 231

Slide 231 text

Don’t make me hunt down docs

Slide 232

Slide 232 text

sprockets/ guides

Slide 233

Slide 233 text

Building an Asset Processing Framework

Slide 234

Slide 234 text

End User Asset Generation

Slide 235

Slide 235 text

Extending Sprockets

Slide 236

Slide 236 text

Makes it easier for devs to find what they need

Slide 237

Slide 237 text

Lives in the source, not a wiki

Slide 238

Slide 238 text

Docs are only valid for a point in time

Slide 239

Slide 239 text

Helpers love contributing to docs

Slide 240

Slide 240 text

so

Slide 241

Slide 241 text

Make more docs

Slide 242

Slide 242 text

Make better docs

Slide 243

Slide 243 text

Docs are the gateway to code contributions

Slide 244

Slide 244 text

Sane Code

Slide 245

Slide 245 text

realtalk

Slide 246

Slide 246 text

Sprockets designed to solve problems

Slide 247

Slide 247 text

Sometimes it feels like

Slide 248

Slide 248 text

No content

Slide 249

Slide 249 text

They don’t know why it fails

Slide 250

Slide 250 text

Sprockets isn’t talking to devs

Slide 251

Slide 251 text

How does code talk?

Slide 252

Slide 252 text

Errors

Slide 253

Slide 253 text

Not

Slide 254

Slide 254 text

“something broke”

Slide 255

Slide 255 text

No route matches {:action=>"show", :controller=>"users"}

Slide 256

Slide 256 text

“This broke”

Slide 257

Slide 257 text

No route matches {:action=>"show", :controller=>"users"}, :id key is missing

Slide 258

Slide 258 text

Look here

Slide 259

Slide 259 text

No route matches {:action=>"show", :controller=>"users"}, :id key is missing

Slide 260

Slide 260 text

Good errors are instructive

Slide 261

Slide 261 text

Sprockets will have better errors

Slide 262

Slide 262 text

I care about this

Slide 263

Slide 263 text

No content

Slide 264

Slide 264 text

Deprecations

Slide 265

Slide 265 text

Deprecating in comments is not enough

Slide 266

Slide 266 text

No content

Slide 267

Slide 267 text

A) No one casually reads your method docs

Slide 268

Slide 268 text

B) Who has the time?

Slide 269

Slide 269 text

You cannot break your API without warning*

Slide 270

Slide 270 text

*when you’ve got 51 million downloads

Slide 271

Slide 271 text

Your code knows

Slide 272

Slide 272 text

YELL AT THEM FOR IT

Slide 273

Slide 273 text

Sprockets 3.X will have deprecations before 4.x

Slide 274

Slide 274 text

No content

Slide 275

Slide 275 text

Deprecations nudge

Slide 276

Slide 276 text

Deprecations Help people upgrade

Slide 277

Slide 277 text

Deprecations help with API design

Slide 278

Slide 278 text

If you can’t write a good deprecation

Slide 279

Slide 279 text

The interface wasn’t very good

Slide 280

Slide 280 text

What if you change a hash key?

Slide 281

Slide 281 text

Sprockets did this

Slide 282

Slide 282 text

filename = input[:source_path] || input[:filename]

Slide 283

Slide 283 text

(more) Sane Code

Slide 284

Slide 284 text

Sprockets suffers from the god object problem

Slide 285

Slide 285 text

1 main class, lot’s of concerns.

Slide 286

Slide 286 text

1 object, 105 methods

Slide 287

Slide 287 text

Where did that method come from?

Slide 288

Slide 288 text

Sprockets::Base

Slide 289

Slide 289 text

Sprockets:: Environment

Slide 290

Slide 290 text

Sprockets:: Dependencies

Slide 291

Slide 291 text

Sprockets:: DigestUtils

Slide 292

Slide 292 text

Sprockets:: HTTPUtils

Slide 293

Slide 293 text

Sprockets:: Mime

Slide 294

Slide 294 text

Sprockets:: Server

Slide 295

Slide 295 text

Sprockets:: Resolve

Slide 296

Slide 296 text

Sprockets:: Loader

Slide 297

Slide 297 text

Sprockets:: Bower

Slide 298

Slide 298 text

Sprockets:: PathUtils

Slide 299

Slide 299 text

Sprockets:: PathDependencyUtils

Slide 300

Slide 300 text

Sprockets:: PathDigestUtils

Slide 301

Slide 301 text

Sprockets:: DigestUtils

Slide 302

Slide 302 text

Sprockets:: SourceMapUtils

Slide 303

Slide 303 text

Sprockets:: UriUtils

Slide 304

Slide 304 text

My favorite

Slide 305

Slide 305 text

Sprockets:: Utils

Slide 306

Slide 306 text

mixed into

Slide 307

Slide 307 text

Sprockets:: Compressing

Slide 308

Slide 308 text

mixed into

Slide 309

Slide 309 text

Sprockets:: Configuration

Slide 310

Slide 310 text

Included in

Slide 311

Slide 311 text

Sprockets:: Base

Slide 312

Slide 312 text

Inherited by

Slide 313

Slide 313 text

Sprockets:: Environment

Slide 314

Slide 314 text

Wrapped and cached by

Slide 315

Slide 315 text

Sprockets:: CachedEnvironment

Slide 316

Slide 316 text

No content

Slide 317

Slide 317 text

Impossible to know at a glance how they interact

Slide 318

Slide 318 text

For more info go to Rafael Franca’s talk

Slide 319

Slide 319 text

Which was yesterday

Slide 320

Slide 320 text

Solution to god objects?

Slide 321

Slide 321 text

Move logic over to helper classes

Slide 322

Slide 322 text

No content

Slide 323

Slide 323 text

Minimize God object API

Slide 324

Slide 324 text

Small easy to understand files

Slide 325

Slide 325 text

Readable code

Slide 326

Slide 326 text

Attracts helpers who read code

Slide 327

Slide 327 text

Ruby is Object Oriented

Slide 328

Slide 328 text

Get comfortable with objects

Slide 329

Slide 329 text

Sandi Metz POODR

Slide 330

Slide 330 text

Katrina Owen Refactoring & Exercism.io

Slide 331

Slide 331 text

Helping takes commitment

Slide 332

Slide 332 text

respect that

Slide 333

Slide 333 text

How?

Slide 334

Slide 334 text

Be nice

Slide 335

Slide 335 text

“thanks for submitting this PR

Slide 336

Slide 336 text

They cared enough to try to help

Slide 337

Slide 337 text

Help them help you

Slide 338

Slide 338 text

What else do people want?

Slide 339

Slide 339 text

Maybe they want recognition?

Slide 340

Slide 340 text

No content

Slide 341

Slide 341 text

Maybe helpers want pizza?

Slide 342

Slide 342 text

Windows Tests

Slide 343

Slide 343 text

)

Slide 344

Slide 344 text

Thanks @daniel-rikowski

Slide 345

Slide 345 text

These are our ideals

Slide 346

Slide 346 text

So you inherited a project with 51 million downloads

Slide 347

Slide 347 text

The original maintainer mic-dropped

Slide 348

Slide 348 text

What do you do?

Slide 349

Slide 349 text

Find something that needs fixing

Slide 350

Slide 350 text

Bug driven development

Slide 351

Slide 351 text

Get an example app

Slide 352

Slide 352 text

OMG example apps are amazing

Slide 353

Slide 353 text

Reproduce the problem

Slide 354

Slide 354 text

Repeat

Slide 355

Slide 355 text

Every bug you fix, you’ll learn more about the project

Slide 356

Slide 356 text

Eventually you’ll begin to see non- bug problems

Slide 357

Slide 357 text

So you’ve got a bug report what do you do now?

Slide 358

Slide 358 text

Source Maps in Sprockets 4

Slide 359

Slide 359 text

Half finished

Slide 360

Slide 360 text

I had no idea what source maps were

Slide 361

Slide 361 text

Fixing bugs made tests break

Slide 362

Slide 362 text

Are those test reliable?

Slide 363

Slide 363 text

¯\_(ツ)_/¯

Slide 364

Slide 364 text

Where do we start?

Slide 365

Slide 365 text

Become an archeologist

Slide 366

Slide 366 text

Research

Slide 367

Slide 367 text

Mozilla RFC

Slide 368

Slide 368 text

Notes

Slide 369

Slide 369 text

Create guides

Slide 370

Slide 370 text

What is a source map?

Slide 371

Slide 371 text

Read my guide!

Slide 372

Slide 372 text

Good OSS maintainers steal borrow

Slide 373

Slide 373 text

Used other projects to verify Sprockets

Slide 374

Slide 374 text

Encoding $ npm install uglify-js

Slide 375

Slide 375 text

Encoding $ uglifyjs foo.js --source-map foo.js.map var foo="foo";var bar="bar"; //# sourceMappingURL=foo.js.map

Slide 376

Slide 376 text

Decoding $ npm install source-map

Slide 377

Slide 377 text

Is it finished?

Slide 378

Slide 378 text

No, need more actionable bug reports

Slide 379

Slide 379 text

Where do we go now?

Slide 380

Slide 380 text

Maintainers Won’t be around forever

Slide 381

Slide 381 text

I Won’t be around forever

Slide 382

Slide 382 text

I need help

Slide 383

Slide 383 text

Help maintain the history of Sprockets

Slide 384

Slide 384 text

Preserve the stories

Slide 385

Slide 385 text

Get involved

Slide 386

Slide 386 text

If you won’t, who will?

Slide 387

Slide 387 text

We all need to step up

Slide 388

Slide 388 text

Take 5 minutes

Slide 389

Slide 389 text

Read guides

Slide 390

Slide 390 text

Write docs

Slide 391

Slide 391 text

Open issues

Slide 392

Slide 392 text

Create example apps

Slide 393

Slide 393 text

Just

Slide 394

Slide 394 text

5

Slide 395

Slide 395 text

minutes

Slide 396

Slide 396 text

Join me

Slide 397

Slide 397 text

Become

Slide 398

Slide 398 text

A helper

Slide 399

Slide 399 text

A maintainer

Slide 400

Slide 400 text

Together

Slide 401

Slide 401 text

Save Sprockets

Slide 402

Slide 402 text

Questions?