gistfile1.txt

onboarding

* **thank you** for doing this
  * going to cover three things:
    * local setup
    * issues, labels, and reviewing code
    * merging code


* setup:
  * CI lives here: https://jenkins-iojs.nodesource.com/job/iojs+any-pr+multi/
    * make sure to log in – I've sent your emails to rvagg, who will set up an account for you
    * go to "Build with parameters"
    * fill in user, repo, and branch. pr number is unused.
  * other repos:
    * https://github.com/nodejs/NG
    * https://github.com/nodejs/roadmap
    * https://github.com/nodejs/website
    * https://github.com/nodejs/readable-stream
  * notifications setup
    * use https://github.com/notifications or set up email
    * watching the main repo will flood your inbox, so be prepared
  * make sure you have whitespace=fix: `git config --global --add core.whitespace fix`
  * working dirs (clone the repo twice)
    * fork the repo to your user account on github
    * git clone git://github.com/nodejs/io.js.git work-iojs
    * git clone work-iojs MERGE-iojs
    * cd work-iojs; git remote add chris git@github.com:chrisdickinson/io.js.git; git fetch;
    * cd ../MERGE-iojs; git remote remove origin; git remote add origin git@github.com:iojs/io.js.git; git fetch
  * #io.js on freenode is the best place to be to interact with the TC / other collaborators
    * if you don't have IRC or a bouncer, contact me via email after the meeting and
    we'll get you set up.

* issues + labels
  * you have free reign – don't hesitate to close an issue if you are confident that it should be closed
    * this will come more naturally over time
  * subsystems:
    * doc, tools, test, src (special)
    * lib/*.js
  * cc'ing humans (by subsystem):
    * lib/child_process: bnoordhuis, piscisaereus, cjihrig
    * lib/cluster: bnoordhuis
    * lib/net: indutny, bnoordhuis, piscisaereus, chrisdickinson, iojs/streams
    * lib/http: isaacs, bnoordhuis
    * lib/vm: isaac (or domenic!)
    * lib/buffer: trevnorris
    * src/async-wrap.*: trevnorris
    * lib/crypto,tls,https: indutny
    * src/node_crypto.*: indutny
    * upgrading v8: domenic, bnoordhuis
    * IN GENERAL: iojs/tc, or `git shortlog -n -s <file>`
  * labels:
    * tsc-agenda if a topic seems controversial
    * semver-major, semver-minor:
      * be conservative – that is, if a change has the remote *chance* of breaking something, go for major
      * when adding the label, add a comment explaining why you're adding it
        * it's cached locally in your brain at that moment!
      * minor vs. patch: roughly: "does it add a new method / does it add a new section to the docs"
      * major vs. everything else: run last versions tests against this version, if they pass, minor or patch
      * adding affected subsystem, os, + iojs version labels is good as well!
      * https://gist.github.com/chrisdickinson/ba532fa0e4e243fb7b44 – test commits

        git checkout $(git show -s --pretty='%T' $(git show-ref -d $(git describe --abbrev=0) | tail -n1 | awk '{print $1}')) -- test; make test

  * reviewing:
    * primary goal is for the codebase to improve
    * secondary (but not far off) is for the person submitting code to succeed
      * helps grow the community
      * and draws new people into the project
    * it is tempting to micro-optimize / make everything about relative perf,
      don't succumb to that temptation. we change v8 a lot more often now, contortions
      that are zippy today may be unnecessary in the future
    * be aware: your opinion carries a lot of weight!
    * nits are fine, but try to avoid stalling the PR
      * note that they are nits when you comment
      * if they really are nits, feel free to fix them yourself on merge (especially for new contributors)
      * improvement doesn't have to come all at once
    * set time limits and expectations:
      * before merging code: give folks at least one working day to respond: "If no one objects, tomorrow at <time> I'll merge this in."
        * set reminders
      * check in on the code every once in a while (set reminders!)
      * if a PR is abandoned, check if they'd mind if you took it over (especially if its just nits left)
    * what belongs in iojs:
      * opinions vary, but I find the following helpful:
      * if io.js itself needs it, then it belongs in io.js 
        * that is to say, url is there because of http, freelist is there because of http, et al


* process for getting code in:
  * the collaborator guide is a great resource: https://github.com/nodejs/io.js/blob/master/COLLABORATOR_GUIDE.md#technical-howto
  * no one (not even TC) pushes directly to master without review
    * best practice: work in WORK-iojs, commit often, open a PR
    * make sure to spend time on the description: every moment you spend writing
      a good description halves the amount of time it takes to understand your code.
    * only squash at the *end* of your work
    * one "LGTM" is sufficient
    * you have the power to LGTM another collaborator or TC members' work
    * make sure to run the PR through CI *first*!
  * once code is ready to go in:
    * cd MERGE-iojs
    * git status; git pull origin master
    * curl -sL 'url-of-pr.patch' | less
    * if it all looks good, `curl -sL 'url-of-pr.patch' | git am`
    * git rebase -i origin/master
    * squash into logical commits
    * `make clean; ./configure; make -j8; make test` (`-j8` builds iojs in parallel with 8 cores. adjust to the number of cores your processor has for best results.)
    * commits should follow `subsystem[,subsystem]: small description\n\nbig description\n\n<metadata>`
    * first line 50, all others 72
    * add metadata:
      * Fixes: <url>
      * Reviewed-By: human <email>
      * PR-URL: <original-pr-url>
    * make clean; make test-ci; git push origin master
    * close the original PR with "merged in `<commit hash>`".
  * what if something goes wrong?
    * ping a TC member
    * if `git am` fails – use `git am --abort`
      * this usually means the PR needs updated
      * prefer to make the originating user update the code, since they have it fresh in mind
      * if you must, `git fetch origin pull/N/head:pr-N; git checkout pr-N; git rebase master`

* exercise: make PRs adding yourselves to the README.
* final note:
  * don't worry about making mistakes: everybody makes them, there's a lot to internalize and that takes time (& we recognize that!)
  * very few (no?) mistakes are unrecoverable
  * the existing io.js committers trust you and are grateful for your help!

https://docs.google.com/forms/d/1wtwhnabArplRSEkerkx9JPA1y3F-aWzGWtFFlL3Fwdg/viewform?usp=send_form