How to Hand Over a Project to a New Developer: A Practical Checklist
A practical handover checklist covering the repository, server, database, external services, environments, and safe access.
In brief
- • A handover means a reproducible startup and clear ownership.
- • Share secrets through an access manager, not in chat or a document.
- • Revoke old access and test backup recovery after the handover.
ContentsShow sections
A new developer needs more than a set of links. They need a safe way to understand, run, and change the project. If you transfer only the repository, work may stop at the first question about the database, environment variables, or release process.
Minimum handover package
| Area | What to document |
|---|---|
| Repository | Address, branch, change rules, and recent releases |
| Startup | Commands, runtime version, dependencies, and test data |
| Production | Where the app runs, how to release, and how to roll back |
| Data | Database schema, migrations, backups, and owner |
| Integrations | Payments, email, analytics, bots, and external APIs |
How to share access safely
- List every system and assign an owner.
- Create a personal account with the minimum required permissions.
- Share secrets through a password manager or secret store.
- Do not put tokens in chat, tickets, or a public README.
- Remove temporary keys and former contractor access after the handover.
Do not grant administrator rights “just in case.” Access should match the task: log reading, test work, and release permissions are different.
Verify the handover
Ask the new developer to complete a short scenario independently: obtain the code, run the project, open a test page, change safe text, and explain how it would reach production. Also verify that a backup exists and can be restored.
What documentation to leave
- a short description of the product and its main user flow;
- a map of services and integrations;
- known limitations and bugs;
- important technical decisions;
- owners of the domain, payments, and infrastructure;
- acceptance rules and the next task list.
If documentation is missing, do not try to write an encyclopedia. Start with startup, critical access, and failure procedures. Continue improving it with project support.
What the freelancer should do during handover
Handover is a deliverable, not free minutes at the end of a contract. Include time for the guide, temporary-access cleanup, a short video or call, and questions from the next developer.
If the project is handed over after the contract, agree on the format: a document, a meeting, a limited chat window, or a short support period. Do not promise unlimited consulting without a separate agreement.
Access matrix
| System | Owner | New access | Revoke |
|---|---|---|---|
| Repository | Client or team | Personal account | Shared and temporary tokens |
| Hosting | Product owner | Minimum role | Contractor access after handover |
| Services | Integration owner | Separate key | Keys from the old environment |
Do not share a personal password when the service supports user invitations. Document the secret name and purpose, but not the value in ordinary documentation. The client should be able to rotate or revoke access independently after handover.
How to estimate handover work
Split the work into preparation, meeting, and short post-handover support. Preparation covers startup and documentation checks; the meeting explains decisions; post-support answers questions from the first independent run.
Charge it hourly or include it as a separate project stage. Do not hide handover inside “small fixes.” The client gains independence, and the freelancer demonstrates a professional finish.
Verify after a week
A good handover ends with a short check: the new developer runs the project, changes a safe element, tests the basic flow, and describes the release process. Without this, a document may look complete but fail in a real incident.
Keep the final access list, the date old keys were revoked, and known limitations. These three notes often save more time than a long technical history.
A completed handover
The handover is complete when the new developer can answer four questions: how to run the project, where to test changes, how to release, and what to do during a failure. If the answer still depends on the former developer, the process is not finished.
End the document with a date, project version, and owners. Months later, this helps separate current instructions from old notes.