onboarding.md

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: nodejs/tsc, 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 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
    • git rebase -i origin/master
    • 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; ./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.)
      • require('os').cpus() to find out how many cpus you have
      • push once it works!
  • 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!