Onboarding to System Parachains

Kian's document is the best resource I've seen for onboarding to Parity and can be found here. Read it and explore everything it links. Recurse through the links that those resources include.
There is a backup link to the source here in case he takes it off his website again.

Also Shawn gave a great talk at Sub0 in 2024 about being an effective dev in the ecosystem. It's worth a watch.

The Polkadot Fellowship Manifesto outlines the expectations and expected mindsets etc, also worth a read. If you want to build the pdf I recommend tectonic which pulls in way fewer dependencies than latexmk and downloads what is needed at the build step, rather than downloading every possible latex module pre-emptively.
A bit more in-depth: you can see what developers at different ranks have been working on in the evidence repo which can be useful to calibrate yourself and how you plan to take on complexity.
A successful onboarding in Parity should leave you operating around the level of what the manifesto describes at rank 2.

General Ramp-Up Expectations

I've stolen this next part verbatim from Joe's document to onboard me as I think it puts it really well:

Of course many people join with different backgrounds/levels of experience, but these are some general guidelines on how the first six months should go:

Within 2 weeks: Make your first PR to Substrate, Polkadot, or Cumulus. It can be really small (e.g. docs, minor refactor, new test). Polkadot SDK has something like 110 CI checks now; the main point of this PR is to get familiar with our contribution process and workflow.

Within 1 month: Be comfortable with the team/working style, demonstrate good communication, have a sense of the appropriate channels for questions, issues, asking for reviews, etc.

Within 3 months: By this time you should have committed to some project and begun working in earnest on it. You will probably still need some context and guidance, but you should have a general sense of what you're working on and familiarity with the existing codebase that's related to it.

Within 6 months: By this time you should be well on your way to being a true "owner" of some subsystem. That is, not just implementing features that others have asked for or fixing bugs, but having a vision for where this product is going and how to make it successful. This might be more of a 9-12 month level to get to, but you should be heading in this direction.

Since he wrote this CI has padded out to about 300 checks, some of which are dormant but it's a lot of moving parts.

We try to do as much work in the open as possible. You should follow along and be active in:

GitHub issues and pull requests on polkadot-sdk
Substrate Stack Exchange
Polkadot Forum
Parity Forum
Polkassembly or SubSquare for Governance proposals (my preference is subsquare, but both have their strong/weak points).
Polkadot Daily Digest

Understanding the expectations at your level

Check out CultureAmp and read the descriptions of the competencies at your level, and maybe read the other levels to have something to aim towards. Note that there are many important soft skills to master for your job as well as programming.

Github

I would recommend trimming back your notifications and only be notified about what you're mentioned in or what you've been asked to review, then using bookmarked github filters you can still be active without having your notifications spammed. Maybe that's just my personal preference. Notification zero ensures that when somebody does mention you directly you get a notification, whereas having millions of notifications usually buries these and they get lost.

Some good bookmarks to have (and poll) are:
PRs you've been mentioned on - for some reason @me doesn't work for this one as for the rest, so you'll need to replace my username with your own
PRs that you've been asked to review directly
PRs that your group has been asked to review
PRs that you haven't yet reviewed but seem suitable
And then just keeping an eye on newly opened issues is a good idea.

I usually take a flick through once or twice a day between my own work to see if I can help with any drive-by reviews on top of the larger reviews that I do when I can set aside more time.

Rust

For those new to rust, or for anybody just looking for some resources to polish and improve.
https://rust-book.cs.brown.edu/ - an "improved" version of The Rust Book, with more visualisations and with added questions/quizzes to make it more interactive
https://rust-for-rustaceans.com/ - a great book which starts where the rust book leaves off and covers a wide variety of topics very well, written by Jon Gjengset, who also has a great rust-focused YouTube channel
https://rust-unofficial.github.io/too-many-lists/ - a nice pathway through rust with the focus of making increasingly effective/performant linked lists

More resources getting more specific to Polkadot:

Choosing your first few issues

As you're starting off you should be aiming to pick up issues on the tracker and tackling ones with increasing complexity. Some good searches might be:
mentor issues
good first issue
D0-easy
refactors. These are especially good when they are mass-refactors where you can claim a pallet and change something, with PRs to other pallets as reference, for example this one.

Or you can bundle the tags and see what exists with combinations of the previous ones.

Contributing

Check out the contributing guidelines and re-read it each time you're about to post a PR for your first few PRs.

More info about labelling your PRs here.

Stick to good git hygiene.
E.g. Commits: keep your commits atomic and commit messages should be in the active voice in the present tense, less than 50 characters with any more info after two newlines.

For parity employees, you'll be added to the GitHub organisation, and you can then push branches to the polkadot-sdk repository (and any other parity repos).
The workflow is usually to branch from master, make your changes and then make PRs to master. The CI must pass and you will be required to get specific reviews if you edit certain files. In general you'll need at least two approvals to be able to merge your changes, but if somebody else has reviewed and requested changes you should address them before merging, even if you have two reviews already.

Kian's doc has some good points to stick to for contributions, which I won't repeat here.

In some projects you might end up making PRs to a dev branch to parallelise and accumulate changes before merging it all to master. Dev branches don't have the same branch protection rules, so the review requirements are different and code can be merged while CI is broken - just keep an eye on CI and make sure you're not unintentionally breaking whatever dev branch you're working on.

Reviewing PRs

Try to review other people's PRs as much as you can without negatively affecting productivity too much, although it's understandable at the start that it will be difficult to give meaningful reviews on bigger PRs. Since it takes at least two approvals for each of your PRs to be merged, and we have hundreds of PRs per week, you can guess how much of a bottleneck this can be. There's no point in making any hard and fast "spend a day per week reviewing"-esque suggestions here, come up with something that works for you.
It's important to not just click approve, really think about what they're trying to achieve and try to understand the intent and think critically about how they're going about it. If you don't understand what's going on or have any context, it can be a good excuse to dig down and understand something more. If you start reviewing and learning and the PR gets merged in the meantime, you haven't reviewed but you've probably learnt a lot along the way. I think I'm still in a state where I've lurked more PRs than I've actually finished the review on, although the ratio is increasing as my scope broadens and I learn something from nearly every single one.

Development environment

Developing with polkadot-sdk leads to crashing editors, local lag, rust-analyzer errors and general pain and suffering. Oh dear. There are solutions.

Basically everybody uses vscode or neovim these days, so we've got config guides for both of them here. If you use something different it's likely you're still using rust-analyzer and everything can be adapted for that.
I've found that Zed does not (as of July 2024) work well yet for substrate/polkadot-sdk, but it's improving rapidly and if you can get rust-analyzer configured properly and cargo remote working for check-on-save let me know!

Update April 2025: cursor is a good upgrade from vscode and a few of us have found that it can really help improve throughput.

Cargo remote

If you've got access to a powerful server cargo-remote is indispensible. It offloads the check-on-save and any other cargo commands that you want from your local machine. It rsyncs your changes and with some tweaks you can even avoid the overhead of ssh auth. I've found that with even just average network speeds this is much better than checking/compiling locally. You can scp any build artifacts, but since I work on a macbook only the wasm is any good locally. I'll either connect over ssh and run it on the server or compile some binaries locally at each release and have them in my path (polkadot/polkadot-parachain/subkey etc).

Refining ssh connections

There is considerable overhead with ssh auth, to get around it you can configure your ssh connections to tunnel over an existing connection, skipping auth. Put this in your .ssh/config:

Host cargo-remote
    HostName x.x.x.x
    IdentityFile ~/.ssh/id_rsa
    IdentitiesOnly yes
    User donal
    port n
    ControlMaster auto
    ControlPath ~/.ssh/control:%C
    ControlPersist 600

The last three entries are where the magic happens.
ControlMaster auto checks if a master connection is already open, if so it looks for the socket (next config) if not it opens one
ControlPath ~/.ssh/control:%C specifies the socket location
ControlPersist 600 keeps the connection open for 10mins after the master connection closes - this is optional but just means you don't need to remember to open the master link every time.

Full details: man ssh_config

Runtimes repo setup

I use multiple remotes for repos that I don't have write access to (like polkadot-fellows/runtimes, which we work in a lot).
I have origin set to my own fork and then another remote called upstream, then I delete the main/master branch on my fork and checkout upstream.

git remote remove origin
git remote add origin git@github.com:your-fork/runtimes.git
git remote add upstream git@github.com:polkadot-fellows/runtimes.git
git branch -D main
git fetch --all
git checkout upstream/main

then you have all branches from both repos in one directory structure.

My full setup

If you want my specific setup I wrote it all down a while ago here, but depending on when you read this definitely override that where needed with this.

Now re-read Kian's document 😉

Become a consumer of the things we build

Loose suggestions (vague to encourage Googling around the topics):

Use a wallet (Talisman and Nova are my personal favourites) and create a new account
Onramp some DOT/KSM to play with (not financial advice etc etc)
Stake some DOT
Explore some blocks on subscan
Vote in governance, no matter how little DOT
Set yourself an on-chain identity on Polkadot
Maybe also add a Kusama identity
Swap some tokens on Hydration and get them back to asset hub
Fork the chain with chopsticks and wreak havoc locally with millions of injected DOT
Write a parachain
Register it on ~~Rococo (if you get in before it scales down)~~ Paseo
Buy some on-demand coretime and make blocks

Check in with the production runtimes

They're owned by the fellowship and live in the runtimes repo. This is a consumer of the polkadot-sdk repo.

Start with the pallets inside construct_runtime! for Polkadot, choose your favourite pallet name and start reading some source code. Develop a good idea of where things are in the monorepo/fellowship runtimes repo.

Check out the PBA content

PBA docs are great and have videos – the best way to cover the fundamentals and develop a wide base of knowledge, but a long ride
The PBA book is searchable and is a great reference, if a bit terse at times since it is taken directly from the slides.
The module videos cover the content in lecture form (the playlists follow the order of the book, but can also be watched out of order)

The PBA-X has just dropped and aims to be a living resource and online course:

🚀 Parity employees now have exclusive, free access to PBA-X - a great resource brought to you by the Polkadot Blockchain Academy, to deepen your expertise, accelerate your onboarding, and increase your knowledge about blockchain technology.

💻️ The online program has been designed for both developers and non-developers, making blockchain fundamentals accessible and practical for everyone. It is a flexible, 4 week course created to help you to navigate your Web3 career and is taught by the brains behind Polkadot. The weekly time commitment is 6 hours, mostly self-studying. This includes 2-3 hours of live lectures each week, which you are encouraged to join virtually, however replays will be available if you aren’t able to make a session. Find out more

🗓️ The PBA-X course kicks off on January 6th, 2025, so don’t miss your chance to be part of this valuable experience! To claim your free spot, please fill out this form. Once registered, we will provide you with a code to access the course, for a 100% discount. 👀

The deadline for registering your interest is Friday 3rd January!

Depending on when you join that might not line up well.

https://pbax.polkadot.academy/

Work on your testing abilities!

Writing or improving unit tests for existing pallets is a great task while onboarding to get your head into a pallet. In the future if you ever wonder whether a pallet can do a certain thing, write a test! if it doesn't exist already then contribute it back.

Building on unit tests, we have multiple tools that together give us a certainty that our code is running well. The layers are (roughly speaking):

Unit tests
E2e tests
E2e tests from forked network state
Manual tests to cover one-off tests or things that are too long to make sense in CI
Testnet deployments (westend and paseo) - sniff out network/validator problems etc and real user systems. Westend is the system testnet to ensure things are working, Paseo allows parachains to test with the new system and at that point you should be relatively sure that the changes are working
Kusama deployment - test crypto-economic assumptions
Probably more tests from Polkadot forked state
THEN Polkadot deployment

Within integration/e2e testing we have multiple options:
Runtime-level tests
XCM-emulator
Zombienet (and zombie-bite)
Chopsticks (and ecosystem tests)

Each of these mocks some part of the system, but maximally effective testing is achieved by covering the mocked parts of one tool with tests in another.

unit tests - rely on mocks and test small parts of the code. Most changes in a pallet should break a unit test. If it doesn't, write one that would break with the thing you've just changed and include it in your PR.