Developer onboarding: an outside engineer shipping in 5 days
Developer onboarding: an outside engineer shipping in 5 days
Microsoft surveyed 267 new hires who onboarded remotely during the pandemic [C4]. They "often take a few weeks to create their first pull request" [C5]. One spent "close to 2 weeks" just setting up their environment [C7]. Almost none of that is the engineer's fault. It's the developer onboarding week nobody prepared.
With an outside engineer, that lost week shows up on an invoice. The fix is on your side of the table, and most of it takes an afternoon.
Developer onboarding is the work between signed paperwork and an engineer's first shipped work. For an outside engineer it skips hardware and HR induction: just paperwork, access, context, one well-scoped task and a review.
Key takeaways
- A 5-day first delivery tests your setup more than the engineer.
- Give an outside engineer the Write role, not Admin, behind branch protection with no admin bypass [C18] [C19].
- Socialization is the most evidenced barrier for open-source newcomers, in 15 of 20 studies [C9]. Pair docs with a questions meeting.
- Day 5 brings a first delivery for you to approve. At Google, median first feedback on a small change is under an hour [C11].
- One shipped task proves the pipeline. DX also tracks time to the 10th merged pull request as a ramp-up metric [C1].
Why does time to first PR take weeks?
Setup and waiting eat the weeks. The code doesn't. Microsoft's remote new hires lost time to environment setup and to tools they couldn't easily get at from home [C7].
The changes are small. In Google's study of 9 million reviewed changes [C11], the median change modifies 24 lines, and over 10% modify a single line [C12]. First feedback takes "a median time of under an hour for small changes and about 5 hours for very large changes" [C11].
DORA's line on batch size is blunt: "Any batch of code that takes longer than a week to complete and check is too big." [C15] When a first pull request takes weeks, the time went somewhere else.
The 5-day developer onboarding sequence
This is how we run the first week on Dev On Demand. Onboard once. First ship in 5 days.
| Day | What happens | What you prepare |
|---|---|---|
| Day 1 | 30-min kickoff within 24 hours: you grant repo access, we sign NDAs and IP assignment. Then our engineer reads your docs, builds an AI-assisted repo brief and brings directed questions. | Paperwork, access, roadmap view, docs, first task |
| Days 2–4 | One task, 3-day turnaround per task, daily async updates. | Same-day answers to async questions |
| Day 5 | First delivery in 5 business days, reviewed and tested before you approve. | Reviewer time on the calendar |
Day 1 plus a 3-day task is four days. The spare day disappears if any of the seven items below isn't ready.
1. Sign the NDA and IP assignment before anything else
NDA before access. We sign IP assignment up front.
Under US Copyright Office Circular 30 (revised August 2024), a commissioned work is "work made for hire" only if it falls into one of nine listed categories and the parties "expressly agree in a written instrument signed by them" [C26]. Software isn't named among the nine [C26], so work-for-hire wording alone may not cover a contractor's code. That's our reading, not legal advice: ask your lawyer whether you need a written IP assignment, and have their standard paper ready before the kickoff.
2. Share the repo on Day 1, with least privilege
Access usually slips to day three over a security review nobody scheduled. NIST defines least privilege as restricting access "to the minimum necessary to accomplish assigned tasks" [C25]. For onboarding contractors to GitHub:
- Outside collaborator, not member. They "cannot be added to a team", need 2FA if your org requires it, and on paid GitHub plans take a licensed seat on a private repo [C17].
- Write role. GitHub recommends Write "for contributors who actively push to your project"; Admin includes "sensitive and destructive actions" [C18].
- Branch protection with no admin bypass. Require reviews, code-owner approval and status checks; dismiss stale approvals. Admins aren't bound unless you set "Do not allow bypassing the above settings" [C19].
- CODEOWNERS. Owners are "automatically requested for review" when a pull request touches their code [C20]. Google requires owner approval, citing a Microsoft finding that "minor contributors should be received with more scrutiny" [C13].
- Expiring tokens. GitHub "highly recommend[s] adding an expiration" [C21]. Outside collaborators can only use classic tokens on your org's repos, so keep scopes minimal [C21].
- Secrets: assume Write can read them. GitHub warns that "any user with write access to your repository has read access to all secrets configured in your repository" [C37]. Put deploy credentials in environment secrets, not repository secrets, and limit that environment to your protected main branch; on GitHub Enterprise Cloud, also add required reviewers [C37] [C38]. Use OIDC instead of long-lived secrets [C22].
- A dev container. A
devcontainer.jsongives everyone who opens the repo in Codespaces the same environment [C23]. That targets the kind of setup that took one Microsoft hire "close to 2 weeks" [C7].
It's how we work anyway: engineers operate inside your environment under your access controls.
3. Show them the roadmap
Share where the product is going. No study backs this one; it's what we've seen. An engineer who knows the billing page gets rebuilt next quarter won't spend Day 3 polishing it. A read-only backlog view or a one-page roadmap is plenty.
4. Documentation they can read alone
DORA's 2022 data found "a clear link between documentation quality and organizational performance" [C16]. Trunk-based development's lift to organizational performance was 36% with below-average documentation and 1525% with above-average [C16]. For continuous integration, 34% against 750% [C16]. A README on how to run the thing, an architecture note and a CONTRIBUTING file (GitHub links it on every new pull request) cover most of Day 1 [C24].
Docs alone won't do it. Steinmacher's review of 20 studies of open-source newcomers found "the most evidenced barriers are related to socialization", in 15 of them [C9]. Microsoft found "building a strong social connection with their team" hard to do remotely [C8]. A newcomer support portal (FLOSScoach, tested with 65 students) helped orientation but didn't lower technical barriers [C10].
5. An AI-assisted repo brief, then a directed-questions meeting
Where your NDA and AI policy allow it, our engineer puts an AI coding assistant to work on the repo, on a business tier or privacy setting that doesn't train on your code. Anthropic "does not train generative models using code or prompts sent to Claude Code under commercial terms", unless the customer opts in to share data [C30]. GitHub "does not use Copilot Business or Copilot Enterprise customer data to train AI models" [C31]. With Cursor's Privacy Mode on, "Customer Data will not be used for training by Cursor" [C32].
The questions are the ones a new hire would ask a colleague. Claude Code's docs start from the same spot: "Suppose you've just joined a new project and need to understand its structure quickly," with prompts like "give me an overview of this codebase" and "trace the login process from front-end to database" [C33]. The answers become a one-page brief: architecture, how to run it, key flows, risky areas and open questions.
Then the engineer checks the brief against your docs and the code. The VS Code docs say it plainly: "Review their answers and edits against the source." [C34] In a CHI '24 study of answers to programming questions, "52% of ChatGPT answers contain incorrect information", and participants missed it 39% of the time [C35].
The brief's open questions set the meeting agenda: why this service owns that table, which test suite is flaky, who decides the API shape. Your engineer corrects whatever the brief still gets wrong. In one small industry study of five developers onboarding at Beko, learners on expert-guided tours scored 83% on a quiz against 57% for AI-only tours [C36]. The brief shortens the meeting; it doesn't replace it. Name the reviewer before you hang up.
6. Pick a first task with acceptance criteria already written
Microsoft suggests a first task "such as fixing a spelling error" [C6]. Asana says "all new engineers must ship something on their first day", even "a fix to a bug or a typo" [C28].
A typo proves almost nothing. Nawaz Dhandala at OneUptime warns: "The threat of evaluation also encourages trivial first changes and under-reporting of obstacles." [C29] Pick something small but real that touches build, tests and deploy. Google's "100 lines is usually a reasonable size" for a change makes a sensible ceiling [C14].
Write the acceptance criteria before Day 1; if no ticket is clear enough, triage the backlog first. More on what a good trial task looks like.
7. Agree it as a 3-day task
Three days is our cadence, not an industry standard. It fits DORA's advice to work in "small increments of time, meaning hours to a couple days" [C15].
If the first task won't fit, split it. That's our rule for all bigger work: a migration is split into 3-day tasks, each approved before the next. More in our guide to running async dev teams.
Your review is the last mile
Day 5 brings a delivery, and the approval is yours. Whether it merges on Day 5 or Day 9 depends on your reviewer.
At Google the whole review has a median latency under 4 hours [C11], usually with one approver [C12]. A named reviewer, a Day 5 slot and CODEOWNERS routing the pull request to them get you close [C20].
The gate stays after week one. You sign off each task before the next starts, so a slow first review becomes a slow review on every task.
What a 5-day first ship doesn't prove
A fast first delivery proves the setup works. Ramp-up is a separate question. DX, which sells developer-productivity tooling, also tracks "Time to 10th PR": "Days from start date to 10th merged pull request" [C1]. As Dhandala says of time to first deployment: "It should measure the onboarding system-not rank individual engineers." [C29] More on engineering metrics that predict delivery.
Onboarding also sets up offboarding. Contractor access "should be tied to a sponsor, a contract end date, and a defined set of systems", per NHI Mgmt Group [C27]. Require token expiry on Day 1 [C21] and the last day is a checklist. Wrong fit? New engineer within 5 business days, into a setup that's already built.
The Day 1 developer onboarding checklist
Copy this into the kickoff ticket:
Frequently asked questions
What is developer onboarding?
Developer onboarding is the work between signed paperwork and an engineer's first shipped work: access, a working environment, context, a first task and a review.
How long should time to first PR take?
There's no neutral standard. Microsoft's remote new hires "often take a few weeks" [C5]. With access, docs and a scoped task ready on Day 1, a first delivery for your approval in 5 business days is realistic. Google's median review latency is under 4 hours [C11].
How do you onboard contractors to GitHub?
Add them as outside collaborators with the Write role, not Admin [C17] [C18]. Protect the main branch with "Do not allow bypassing the above settings" turned on [C19]. Require an expiry on any token they use; removing their access deactivates their tokens [C21].
What should a developer onboarding checklist include?
Paperwork, least-privilege access with branch protection and CODEOWNERS, a reproducible environment, README and CONTRIBUTING, a roadmap view, a scoped first task, a booked reviewer, and an access end date with a sponsor [C19] [C20] [C23] [C24] [C27].
Does a fast first PR mean the engineer is ramped up?
No. It proves your access, build and review path work. DX also tracks time to the 10th merged pull request as a ramp-up metric [C1].
Start with one task
Run the checklist against one ticket that's been waiting. Then hand it to Dev On Demand: $3,495/mo for one task at a time or $6,795/mo for two in parallel, with a 3-day turnaround per task and daily async updates. Cancel any time. If we're a fit, your trial task is free.
Book the reviewer's Day 5 slot before the kickoff. If something on your side stops that slot being used, you've found your onboarding problem.
Sources
- [C1] DX onboarding metrics: "Time to first PR" and "Time to 10th PR" definitions — https://docs.getdx.com/
onboarding/ - [C4] Rodeghero, Zimmermann, Houck, Ford (Microsoft): survey of 267 remotely onboarded new hires — https://ar5iv.labs.arxiv.org/
html/ 2011.08130 - [C5] Microsoft: new hires "often take a few weeks to create their first pull request" — https://ar5iv.labs.arxiv.org/
html/ 2011.08130 - [C6] Microsoft: recommend a simple first task, "such as fixing a spelling error" — https://ar5iv.labs.arxiv.org/
html/ 2011.08130 - [C7] Microsoft: environment setup "close to 2 weeks"; hardware and software hard to access from home — https://ar5iv.labs.arxiv.org/
html/ 2011.08130 - [C8] Microsoft: social connection as a top remote-onboarding challenge; onboarding buddy recommended — https://ar5iv.labs.arxiv.org/
html/ 2011.08130 - [C9] Steinmacher et al. (2015): systematic review of open-source newcomer barriers, socialization most evidenced (15 of 20 studies) — https://experts.nau.edu/
en/ publications/ a-systematic-literature-review-on-the-barriers-faced-by-newcomers/ - [C10] Steinmacher et al. (ICSE 2016): FLOSScoach newcomer portal (65 students) helped orientation, did not lower technical barriers — https://experts.nau.edu/
en/ publications/ overcoming-open-source-project-entry-barriers-with-a-portal-for-n/ - [C11] Sadowski et al. (Google, 2018): 9 million reviewed changes; review latency medians — https://research.google/
pubs/ modern-code-review-a-case-study-at-google/ - [C12] Google: median change 24 lines, over 10% single-line; usually one reviewer — https://storage.googleapis.com/
gweb-research2023-media/ pubtools/ 4476.pdf - [C13] Google: owner approval; "minor contributors should be received with more scrutiny" — https://storage.googleapis.com/
gweb-research2023-media/ pubtools/ 4476.pdf - [C14] Google eng-practices: "100 lines is usually a reasonable size for a CL" — https://google.github.io/
eng-practices/ review/ developer/ small-cls.html - [C15] DORA: working in small batches — https://dora.dev/
capabilities/ working-in-small-batches/ - [C16] DORA: documentation quality and organizational performance — https://dora.dev/
capabilities/ documentation-quality/ - [C17] GitHub: adding outside collaborators — https://docs.github.com/
en/ organizations/ managing-user-access-to-your-organizations-repositories/ managing-outside-collaborators/ adding-outside-collaborators-to-repositories-in-your-organization - [C18] GitHub: repository roles for an organization — https://docs.github.com/
en/ organizations/ managing-user-access-to-your-organizations-repositories/ managing-repository-roles/ repository-roles-for-an-organization - [C19] GitHub: about protected branches — https://docs.github.com/
en/ repositories/ configuring-branches-and-merges-in-your-repository/ managing-protected-branches/ about-protected-branches - [C20] GitHub: about code owners — https://docs.github.com/
en/ repositories/ managing-your-repositorys-settings-and-features/ customizing-your-repository/ about-code-owners - [C21] GitHub: managing personal access tokens — https://docs.github.com/
en/ authentication/ keeping-your-account-and-data-secure/ managing-your-personal-access-tokens - [C22] GitHub: using secrets in GitHub Actions — https://docs.github.com/
en/ actions/ security-for-github-actions/ security-guides/ using-secrets-in-github-actions - [C37] GitHub: secure use reference for Actions (write access can read repository secrets) — https://docs.github.com/
en/ actions/ reference/ security/ secure-use - [C38] GitHub: managing environments for deployment (required reviewers plan availability) — https://docs.github.com/
en/ actions/ how-tos/ deploy/ configure-and-manage-deployments/ manage-environments - [C23] GitHub: introduction to dev containers — https://docs.github.com/
en/ codespaces/ setting-up-your-project-for-codespaces/ adding-a-dev-container-configuration/ introduction-to-dev-containers - [C24] GitHub: setting guidelines for repository contributors (CONTRIBUTING) — https://docs.github.com/
en/ communities/ setting-up-your-project-for-healthy-contributions/ setting-guidelines-for-repository-contributors - [C25] NIST glossary: least privilege — https://csrc.nist.gov/
glossary/ term/ least_privilege - [C26] US Copyright Office Circular 30: works made for hire (revised 08/2024) — https://www.copyright.gov/
circs/ circ30.pdf - [C27] NHI Mgmt Group: contractor and partner offboarding risk — https://nhimg.org/
faq/ why-do-contractors-and-partners-create-more-offboarding-risk-than-many-employee/ - [C28] Asana: onboarding new engineers, "ship something on their first day" — https://asana.com/
es/ inside-asana/ onboarding-new-engineers.md - [C29] OneUptime (Nawaz Dhandala, 2026-07-30): time to first deployment — https://oneuptime.com/
blog/ post/ 2026-07-30-time-to-first-deployment/ view - [C30] Anthropic: Claude Code data usage (commercial terms, no training) — https://code.claude.com/
docs/ en/ data-usage - [C31] GitHub: Copilot model hosting (Business/Enterprise data not used for training) — https://docs.github.com/
en/ copilot/ reference/ ai-models/ model-hosting - [C32] Cursor: data use and Privacy Mode — https://cursor.com/
data-use - [C33] Anthropic: Claude Code common workflows, "Understand new codebases" — https://code.claude.com/
docs/ en/ common-workflows - [C34] VS Code: Copilot workspace context — https://code.visualstudio.com/
docs/ copilot/ reference/ workspace-context - [C35] Kabir et al., CHI '24: ChatGPT answers to Stack Overflow questions — https://arxiv.org/
abs/ 2308.02312 - [C36] Kara et al., FSE '26 Companion (LACY): expert-guided vs AI-only code tours — https://arxiv.org/
abs/ 2603.25391
