# Onboarding to System Parachains

Kian's document is the best resource I've seen for onboarding to Parity and can be found [here](https://blog.kianenigma.com/posts/runtime-function-onboarding-2024/). Read it and explore everything it links. Recurse through the links that those resources include.
There is a backup link to the source [here](https://github.com/kianenigma/kianenigma.github.io/blob/main/src/site/notes/Posts/Runtime%20Function%20Onboarding%202024.md) in case he takes it off his website again.

Also Shawn gave a [great talk](https://www.youtube.com/watch?v=Dxx96ZAXL2c) at Sub0 in 2024 about being an effective dev in the ecosystem. It's worth a watch.

The [Polkadot Fellowship Manifesto](https://github.com/polkadot-fellows/manifesto) outlines the expectations and expected mindsets etc, also worth a read. If you want to build the pdf I recommend [`tectonic`](https://github.com/tectonic-typesetting/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](https://github.com/polkadot-fellows/Evidences) 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](https://substrate.stackexchange.com)
- [Polkadot Forum](https://forum.polkadot.network/)
- [Parity Forum](https://forum.parity.io/)
- [Polkassembly](https://polkadot.polkassembly.io/opengov) or [SubSquare](https://polkadot.subsquare.io) for Governance proposals (my preference is subsquare, but both have their strong/weak points).
[Polkadot Daily Digest](https://matrix.to/#/#dailydigest:web3.foundation)

## Understanding the expectations at your level
Check out Joe's [Meta Expectations doc](https://docs.google.com/document/d/1N6QCdJ5TW-uW0QSahSjgZ0YYcLZLLpfD_BAIu6K8VtE/edit?tab=t.0) to give a good overview of the expectations at your level. Notice that programming and technical skills are not at all the whole picture.

## 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](https://github.com/paritytech/polkadot-sdk/pulls?q=is%3Aopen+is%3Apr+mentioned%3A%40seadanda) - 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](https://github.com/paritytech/polkadot-sdk/pulls?q=is%3Aopen+is%3Apr+user-review-requested%3A%40me)
[PRs that your group has been asked to review](https://github.com/paritytech/polkadot-sdk/pulls/review-requested/@me)
[PRs that you haven't yet reviewed but seem suitable](https://github.com/paritytech/polkadot-sdk/pulls?q=is%3Apr+is%3Aopen+-reviewed-by%3A%40me+-is%3Adraft+-author%3A%40me)
And then just keeping an eye on [newly opened issues](https://github.com/paritytech/polkadot-sdk/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://www.youtube.com/@jonhoo)
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:
- https://github.com/JoshOrndorff/blockchain-from-scratch
- https://github.com/shawntabrizi/rust-state-machine/tree/master
- https://github.com/shawntabrizi/substrate-collectables-workshop/tree/master
- https://github.com/shawntabrizi/awesome-polkadot/tree/master

## 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](https://github.com/paritytech/polkadot-sdk/labels/C1-mentor)
[good first issue](https://github.com/paritytech/polkadot-sdk/labels/C2-good-first-issue)
[D0-easy](https://github.com/paritytech/polkadot-sdk/labels/D0-easy)
[refactors](https://github.com/paritytech/polkadot-sdk/labels/I4-refactor). 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](https://github.com/paritytech/polkadot-sdk/issues/226).

Or you can bundle the tags and see what exists with [combinations](https://github.com/paritytech/polkadot-sdk/issues?q=is%3Aopen+label%3AI4-refactor+label%3AC1-mentor+label%3AC2-good-first-issue) of the previous ones.

## Contributing
Check out the [contributing guidelines](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CONTRIBUTING.md) 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](https://www.notion.so/paritytechnologies/GitHub-Labels-368aabced86d43538fa40c8c04bab8e7).

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](https://github.com/paritytech/polkadot-sdk/blob/master/docs/sdk/src/reference_docs/development_environment_advice.rs). 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](https://zed.dev/) 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 [e-mail]:your-fork/runtimes.git
git remote add upstream [e-mail]: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](https://hackmd.io/ihlLzppYTCK8fIymWQPijw), but depending on when you read this definitely override that where needed with [this](https://github.com/paritytech/polkadot-sdk/blob/master/docs/sdk/src/reference_docs/development_environment_advice.rs).

Now re-read [Kian's document](https://blog.kianenigma.com/posts/runtime-function-onboarding-2024/) 😉

### AI coding agents

Use claude-code.

There is a right way and a wrong way to use AI agents for programming. In general AI should not be used where you don't have easy truth matching.

A good way to apply this to programming is:
- disallow git commits by claude
- review everything that claude writes and commit changes yourself intentionally - think of it more like pair programming + a bit of an adversarial mindset. You are responsible for the code that you commit, so make sure that you understand the intention behind the code, what it is actually doing and what it is testing
- (if you're onboarding) while claude is churning, you can use the time to better understand substrate and the pallets that make up the runtimes

#### Concrete recommendations

/model opus # or /model opusplan
/sandbox
/init

Then enter plan mode, explain the problem and make use of MCP, knowledge bases, share docs etc in a way that claude can ingest

Use keywords like "ultrathink" and "use multiple parallel subagents to ... " in the planning phase.

This is the point to carefully read his output, as a few minutes here could save you an hour going in the wrong direction. This is the point where you should expect a good quality, clear design doc which you can review and approve.

Then switch to automatically accept edits and let him cook. I have a system prompt to be concise in his text output.

If things start to go south, be firm and explain exactly what you want, and where he's going wrong.

When the conversation compacts, know that claude has just lost some braincells and adapt your prompting accordingly with things like "familiarise yourself with the project" "remember that the aim is to do x and y by implementing it in way z" "what do we have left to do towards our aim here?"

If claude starts to degrade and go into a spin of bad interpretations, I have found swearing at him actually causes a noticeable improvement in his output.

## 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](https://www.subscan.io/)
* 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](https://github.com/AcalaNetwork/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](https://github.com/polkadot-fellows/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](https://hackmd.io/@seadanda/ByVL3-Zc0) is searchable and is a great reference, if a bit terse at times since it is taken directly from the slides.
[The module videos](https://www.youtube.com/@polkadotblockchainacademy/playlists) 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/

Parity have got a special relationship with PBA, detailed here: https://forum.parity.io/t/exclusive-access-parity-w3f-only-pba-x-course-is-now-live/2500

## 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.