Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update developing #1769

Merged
merged 2 commits into from
Mar 14, 2024
Merged

docs: update developing #1769

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
876e463
docs: update developing
wischli Mar 12, 2024
e409037
Merge branch 'main' into docs/developing
wischli Mar 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 21 additions & 49 deletions docs/DEVELOPING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Initialize your Wasm Build environment:

Build Wasm and native code:

- Prerequisites : cmake, libclang-dev
- Prerequisites : `cmake`, `libclang-dev`

```bash
cargo build --release
Expand All @@ -28,7 +28,7 @@ and another one to verify how it works in a more real environment as a parachain
The following command will run the unit and integration tests:

```bash
cargo +nightly test --workspace --release --features runtime-benchmarks,try-runtime
cargo test --workspace --release --features runtime-benchmarks,try-runtime
```

### Environment tests
Expand Down Expand Up @@ -58,7 +58,7 @@ It runs a [collator](https://wiki.polkadot.network/docs/learn-collator) node:
*Note: the command above will show logs and block until the parachain is stopped.
If you had a previous state, you can reset the node using `purge` after the command.*

Similar to the relay chain, you can explore the parachain using the [polkadot.js (on localhost:11946)](https://polkadot.js.org/apps/?rpc=ws%3A%2F%2Flocalhost%3A11946#/explorer) client.
Similar to the relay chain, you can explore the parachain using the [polkadot.js (on localhost:11936)](https://polkadot.js.org/apps/?rpc=ws%3A%2F%2Flocalhost%3A11936#/explorer) client.
You will see the block production frozen until you connect it to the relay chain.

By default, the initialized parachain will have the id `2000`.
Expand All @@ -84,33 +84,28 @@ You can play with it from the parachain client, make transfers, inspect events,
## Linting

### Source code
Lint the source code with `cargo +nightly fmt`. This excludes certain paths (defined in `rustfmt.toml`) that we want to stay as close as possible to `paritytech/substrate` to simplify upgrading to new releases.
Lint the source code with `cargo fmt --all`. This excludes certain paths (defined in `rustfmt.toml`) that we want to stay as close as possible to `paritytech/substrate` to simplify upgrading to new releases.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't this be the same command that we use in our CI - cargo fmt -- --check?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, I actually believe we should instead change the CI to check with --all 😅. IMO fmt --all here has no downsides as it is a superset of fmt. I also have to admit that I am not sure whether there is a difference between cargo fmt and cargo fmt --all for our workspace.


### Cargo.toml files
1. Install [taplo](https://github.com/tamasfe/taplo) with `cargo install taplo-cli`.
2. Lint the `Cargo.toml` files with `taplo fmt`.

## Verifying Runtime
1. Check out the commit at which the runtime was built.
2. Run `TARGET=build-runtime RUST_TOOLCHAIN=nightly ./ci/script.sh`
3. A similar output is generated
2. Build the WASM via `cargo build --release`
3. Ensure the output from [subwasm](https://github.com/chevdor/subwasm) matches the release one. Run `subwasm info ./target/release/wbuild/centrifuge-runtime/centrifuge_runtime.compact.compressed.wasm`, which creates an output like the following one:
```
✨ Your Substrate WASM Runtime is ready! ✨
Summary:
Generator : srtool v0.9.5
GIT commit : 27326e69481f08313d6048da1500befe209bdf71
GIT tag : v0.0.3
GIT branch : master
Time : 2020-03-20T11:00:24Z
Rustc : rustc 1.43.0-nightly (5e7af4669 2020-02-16)
Size : 928 KB (950464 bytes)
Content : 0x0061736d0100000001c2022f60037f7f...3436363920323032302d30322d313629
Package : centrifuge-runtime
Proposal : 0x5c3d2cd41d70c514566c9b512743ad229fa96518061fe21c8178ba43cfcf16dc
SHA256 : 3f0d2e98e2351144027826f26277bda90e5fabc13f0945fc8fec13d116602e2a
Wasm : ./target/srtool/release/wbuild/centrifuge-runtime/centrifuge_runtime.compact.wasm
🏋️ Runtime size: 1.819 MB (1,906,886 bytes)
🗜 Compressed: Yes, 78.50%
✨ Reserved meta: OK - [6D, 65, 74, 61]
🎁 Metadata version: V14
🔥 Core version: centrifuge-1025 (centrifuge-1.tx2.au1)
🗳️ system.setCode hash: 0x210cdf71ee5c5fbea3dc5090c596a992b148030474121b481a856433eb5720f3
🗳️ authorizeUpgrade hash: 0x319e30838e1acc9dd071261673060af687704430c45b14cdb5fc97ec561e2a12
🗳️ Blake2-256 hash: 0xb7f74401c52ee8634ad28fe91e8a6b1debb802d4d2058fdda184a6f2746477f6
📦 IPFS: https://www.ipfs.io/ipfs/QmS3GDmbGKvcmSd7ca1AN9B34BW3DuDEDQ1iSLXgkjktpG
```
4. `Proposal` hash should match the runtime upgrade proposal
4. The `Blake2-256` hash should match the hex of the `authorizeUpgrade` call.
See more [here](docs/runtime-upgrade.md).

## Generate new Spec and Parachain files
Expand Down Expand Up @@ -143,13 +138,13 @@ the collator node the parachain will be running on.
# Updating to a newer version of Polkadot

When a new version of Polkadot is released, companion releases happen for the other
parity projects such as Substrate and Cumulus, as well as for other third-party projects
such as the `orml` pallets, `xcm-simulator`, etc.
parity projects such as the Polkadot SDK, as well as for other third-party projects
such as the `ORML` pallets, `xcm-simulator`, etc.

Therefore, updating this repository to a new version of Polkadot means updating all of these dependencies
(internal and external to Centrifuge ) and have them all aligned on the same version of Polkadot.

_Note: When we say "new version of Polkadot", we implicitly mean "Polkadot, Substrate, Cumulus"._
_Note: When we say "new version of Polkadot", we implicitly mean "Polkadot SDK, Frontier, ORML"._

The high level flow to upgrade to a newer version of Polkadot is:

Expand All @@ -172,9 +167,7 @@ The high level flow to upgrade to a newer version of Polkadot is:
```shell
export POLKADOT_NEW_VERSION="<version>"; # for example, 0.9.32

diener update --polkadot --branch release-v$POLKADOT_NEW_VERSION;
diener update --substrate --branch polkadot-v$POLKADOT_NEW_VERSION;
diener update --cumulus --branch polkadot-v$POLKADOT_NEW_VERSION;
diener update --polkadot-sdk --branch release-v$POLKADOT_NEW_VERSION;
Copy link
Contributor

@lemunozm lemunozm Mar 14, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just notify this behavior has not been merged yet: paritytech/diener#45. I hope we have it when we need it. Although since we use workspace dependencies, this is no longer an "issue" for us.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you fine with keeping as proposed and iterating over this as part of the Polkadot SDK updates after v1.1.0?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah! Sure, I was only notifying

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Click the button 🚀

```

**Note**: This step only updates the versions of those dependencies across the repository. Any breaking changes introduced
Expand Down Expand Up @@ -216,26 +209,5 @@ by the new versions will have to be dealt with manually afterwards.
If you face compilation errors like "type X doesn't implement trait Y", and the compiler
doesn't suggest you import any particular trait, experience is that there are different versions
of Polkadot|Substrate|Cumulus being pulled; The `cargo patch` rules in `Cargo.toml` should be handling that so if this
still happens it's likely because some new crate of Polkadot|Substrate|Cumulus is being pulled directly or indirectly
still happens it's likely because some new crate of Polkadot SDK or Frontier is being pulled directly or indirectly
and we need to include that crate in the appropriate `cargo patch` rule.
Running `nix --extra-experimental-features "nix-command flakes" build` should fail if multiple versions of a crate is
being pulled and, therefore, not yet being handled by any `cargo patch` rules, making it very easy to spot the crate
causing the trouble.

## NIX

The CI runs a `nix-build` job that executes `nix build` on the entire repository. This job fails if the output
`cargoSha256` for the revision being built does not match the expected value defined in `flake.nix`.

Whenever a dependency is added, removed, or updated, said `cargoSha256` value defined in `flake.nix` needs to be updated.
To do that, you need:

1. [Install Nix](https://nixos.org/download.html)

2. On your feature branch, run:
```shell
nix --extra-experimental-features "nix-command flakes" build
```

3. Use the new `cargoSha256` output provided on step 2. and update it in `flake.nix`
4. Commit and push
Loading