From f13b31f27eb60b7cd64187a90256c6e6f219eb5d Mon Sep 17 00:00:00 2001 From: nhussein11 Date: Tue, 2 Sep 2025 14:19:42 -0300 Subject: [PATCH 1/7] Add CONTRIBUTING.md to outline contribution guidelines for Polkadot Cookbooks --- CONTRIBUTING.MD | 108 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 CONTRIBUTING.MD diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD new file mode 100644 index 0000000..f5b9562 --- /dev/null +++ b/CONTRIBUTING.MD @@ -0,0 +1,108 @@ +## Contributing + +Thank you for helping validate and improve the Polkadot Cookbooks tutorials. This repository contains two types of cookbooks: + +- **Polkadot Smart Contract Cookbooks**: Tutorials focused on smart contract development +- **Polkadot SDK Cookbooks**: Tutorials for Polkadot SDK development and runtime building + +## Contribution Workflow + +1. Propose a new tutorial by opening an issue with the idea +2. Wait for approval +3. Once approved, create a branch for the new tutorial +4. Create a draft PR with the markdown content of the tutorial, once approved, go ahead and push the changes to the PR and mark it as ready for review +5. Once the PR is merged, you can choose to create a new PR in the polkadot-docs repo to include the tutorial in the official documentation, or wait for the team to do that for you. + +- If you are proposing a new tutorial for the Polkadot Smart Contract Cookbooks, please follow the instructions in the [Polkadot Smart Contract Cookbooks](#polkadot-smart-contract-cookbooks) section. + +- If you are proposing a new tutorial for the Polkadot SDK Cookbooks, please follow the instructions in the [Polkadot SDK Cookbooks](#polkadot-sdk-cookbooks) section. + +## Polkadot Smart Contract Cookbooks + +To contribute to the Polkadot Smart Contract Cookbooks, please follow these instructions: + +1. Create an issue with the idea. The issue should include: + - Clear learning objectives + - Target audience (beginner/intermediate/advanced) + - Prerequisites needed + - List of tools, versions, and technologies used (eg. Polkadot-API, ParaSpell, etc.) + +2. Wait for approval +3. Once approved, create a new branch for the new tutorial: + +```bash +git checkout -b feat/tutorial- +``` + +4. Create the tutorial structure + +```bash +tutorials// + tutorial.yml # manifest: build/runtime, chain spec, network, tests + justfile # tutorial-local Just recipes + -code/ # project directory with the smart contract code. For example, nft-code, erc20-code, etc. + tests/ + .test.ts # polkadot.js based e2e tests (recommended) + scripts/ # optional; prefer using repo-level Just recipes +``` + +5. Push the changes to the branch and create a PR: + +```bash +git push origin feat/tutorial- +``` + +6. After the PR is approved and merged, you will have to decide the following: + +- Do you want to include the tutorial in the official documentation? + - If no, you can still use the tutorial as a standalone tutorial in the cookbook + - If yes, do you want to do it by yourself or do you want the team to do it for you? + - If you want to do it by yourself, you will have to create a new PR in the polkadot-docs repo to include the tutorial in the official documentation + - If you want the team to do it for you, you will have to wait for the team to do it for you + + +## Polkadot SDK Cookbooks + +To contribute to the Polkadot SDK Cookbooks, please follow these instructions: + +1. Create an issue with the idea. The issue should include: + - Clear learning objectives + - Target audience (beginner/intermediate/advanced) + - Prerequisites needed + - List of tools, versions, and technologies used (eg. Polkadot-API@1.110.0, ParaSpell@0.4.0, etc.) + +2. Wait for approval +3. Once approved, create a new branch for the new tutorial: + +```bash +git checkout -b feat/tutorial- +``` + +4. Create the tutorial structure + +```bash +tutorials// + tutorial.yml # manifest: build/runtime, chain spec, network, tests + justfile # tutorial-local Just recipes + -code/ # project directory with the smart contract code. For example, nft-code, erc20-code, etc. + zombienet/ + zombienet-omni-node.toml + zombienet.toml # optional alternative using template node + tests/ + .test.ts # polkadot.js based e2e tests (recommended) + scripts/ # optional; prefer using repo-level Just recipes +``` + +5. Push the changes to the branch and create a PR: + +```bash +git push origin feat/tutorial- +``` + +6. After the PR is approved and merged, you will have to decide the following: + +- Do you want to include the tutorial in the official documentation? + - If no, you can still use the tutorial as a standalone tutorial in the cookbook + - If yes, do you want to do it by yourself or do you want the team to do it for you? + - If you want to do it by yourself, you will have to create a new PR in the polkadot-docs repo to include the tutorial in the official documentation + - If you want the team to do it for you, you will have to wait for the team to do it for you \ No newline at end of file From c12a72c80e6bef0cde7b21b76d22dbca8e2335fb Mon Sep 17 00:00:00 2001 From: nhussein11 Date: Tue, 2 Sep 2025 14:21:48 -0300 Subject: [PATCH 2/7] Clarify project directory descriptions in CONTRIBUTING.md for better understanding of smart contract project structure. --- CONTRIBUTING.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index f5b9562..f45b042 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -40,7 +40,7 @@ git checkout -b feat/tutorial- tutorials// tutorial.yml # manifest: build/runtime, chain spec, network, tests justfile # tutorial-local Just recipes - -code/ # project directory with the smart contract code. For example, nft-code, erc20-code, etc. + -code/ # project directory with the smart contract project code. For example, nft-code, erc20-code, etc. tests/ .test.ts # polkadot.js based e2e tests (recommended) scripts/ # optional; prefer using repo-level Just recipes @@ -84,7 +84,7 @@ git checkout -b feat/tutorial- tutorials// tutorial.yml # manifest: build/runtime, chain spec, network, tests justfile # tutorial-local Just recipes - -code/ # project directory with the smart contract code. For example, nft-code, erc20-code, etc. + -code/ # project directory with the project code. For example, add-nft-pallet, customize-your-pallet, etc. zombienet/ zombienet-omni-node.toml zombienet.toml # optional alternative using template node From 21ac0f01b7f0ada9812193e1fb2920700c3b1f7b Mon Sep 17 00:00:00 2001 From: nhussein11 Date: Tue, 2 Sep 2025 14:23:01 -0300 Subject: [PATCH 3/7] Add guidance on utilizing the `parachain-kitchensink` project and clarify the optional use of the `zombienet` folder in CONTRIBUTING.md --- CONTRIBUTING.MD | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index f45b042..0f9a9cc 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -93,6 +93,10 @@ tutorials// scripts/ # optional; prefer using repo-level Just recipes ``` +When possible, this tutorials should take advantage of the existing `parachain-kitchensink` project. + +- Note: The `zombienet` folder is optional, you can use it if you want to test the tutorial locally using zombienet. + 5. Push the changes to the branch and create a PR: ```bash From 9346e2c05da557d2568a8007b7caaca9ca4f14e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Hussein?= <80422357+nhussein11@users.noreply.github.com> Date: Tue, 2 Sep 2025 14:53:02 -0300 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Bruno Galvao --- CONTRIBUTING.MD | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index 0f9a9cc..874c6bf 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -2,24 +2,24 @@ Thank you for helping validate and improve the Polkadot Cookbooks tutorials. This repository contains two types of cookbooks: -- **Polkadot Smart Contract Cookbooks**: Tutorials focused on smart contract development -- **Polkadot SDK Cookbooks**: Tutorials for Polkadot SDK development and runtime building +- **Polkadot Smart Contract Cookbook**: Tutorials focused on smart contract development +- **Polkadot SDK Cookbook**: Tutorials for Polkadot SDK development and runtime building ## Contribution Workflow -1. Propose a new tutorial by opening an issue with the idea +1. Propose a new tutorial by opening a GitHub Issue with the idea 2. Wait for approval 3. Once approved, create a branch for the new tutorial 4. Create a draft PR with the markdown content of the tutorial, once approved, go ahead and push the changes to the PR and mark it as ready for review 5. Once the PR is merged, you can choose to create a new PR in the polkadot-docs repo to include the tutorial in the official documentation, or wait for the team to do that for you. -- If you are proposing a new tutorial for the Polkadot Smart Contract Cookbooks, please follow the instructions in the [Polkadot Smart Contract Cookbooks](#polkadot-smart-contract-cookbooks) section. +- If you are proposing a new tutorial for the Polkadot Smart Contract Cookbook, please follow the instructions in the [Polkadot Smart Contract Cookbook](#polkadot-smart-contract-cookbook) section. -- If you are proposing a new tutorial for the Polkadot SDK Cookbooks, please follow the instructions in the [Polkadot SDK Cookbooks](#polkadot-sdk-cookbooks) section. +- If you are proposing a new tutorial for the Polkadot SDK Cookbook, please follow the instructions in the [Polkadot SDK Cookbook](#polkadot-sdk-cookbook) section. -## Polkadot Smart Contract Cookbooks +## Polkadot Smart Contract Cookbook -To contribute to the Polkadot Smart Contract Cookbooks, please follow these instructions: +To contribute to the Polkadot Smart Contract Cookbook, please follow these instructions: 1. Create an issue with the idea. The issue should include: - Clear learning objectives @@ -28,7 +28,7 @@ To contribute to the Polkadot Smart Contract Cookbooks, please follow these inst - List of tools, versions, and technologies used (eg. Polkadot-API, ParaSpell, etc.) 2. Wait for approval -3. Once approved, create a new branch for the new tutorial: +3. Once approved, fork the polkadot-cookbook and create a new branch for your new tutorial: ```bash git checkout -b feat/tutorial- @@ -61,9 +61,9 @@ git push origin feat/tutorial- - If you want the team to do it for you, you will have to wait for the team to do it for you -## Polkadot SDK Cookbooks +## Polkadot SDK Cookbook -To contribute to the Polkadot SDK Cookbooks, please follow these instructions: +To contribute to the Polkadot SDK Cookbook, please follow these instructions: 1. Create an issue with the idea. The issue should include: - Clear learning objectives From 5b4b4b1890d5d3560086f9d768dd8cab8a82ec97 Mon Sep 17 00:00:00 2001 From: nhussein11 Date: Tue, 2 Sep 2025 14:55:46 -0300 Subject: [PATCH 5/7] Revise CONTRIBUTING.md to clarify the steps for contributing to the Polkadot Cookbook and enhance section descriptions. --- CONTRIBUTING.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index 874c6bf..d63c185 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -1,6 +1,6 @@ ## Contributing -Thank you for helping validate and improve the Polkadot Cookbooks tutorials. This repository contains two types of cookbooks: +Steps for contributing to the Polkadot Cookbook. The Polkadot Cookbook contains two main sections: - **Polkadot Smart Contract Cookbook**: Tutorials focused on smart contract development - **Polkadot SDK Cookbook**: Tutorials for Polkadot SDK development and runtime building From 002e1657657f3dffd9483ab46a1d7ef4ebd1009d Mon Sep 17 00:00:00 2001 From: nhussein11 Date: Tue, 2 Sep 2025 14:57:21 -0300 Subject: [PATCH 6/7] Enhance CONTRIBUTING.md by simplifying the final steps for tutorial submission and clarifying the optional process for including tutorials in the official Polkadot Docs. --- CONTRIBUTING.MD | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index d63c185..f367b73 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -11,7 +11,9 @@ Steps for contributing to the Polkadot Cookbook. The Polkadot Cookbook contains 2. Wait for approval 3. Once approved, create a branch for the new tutorial 4. Create a draft PR with the markdown content of the tutorial, once approved, go ahead and push the changes to the PR and mark it as ready for review -5. Once the PR is merged, you can choose to create a new PR in the polkadot-docs repo to include the tutorial in the official documentation, or wait for the team to do that for you. +5. After your PR is merged, you’re done 🎉. + + - (Optional) If you would also like your tutorial to be considered for the official Polkadot Docs, create a PR in the polkadot-docs repo that links to your merged PR in this repo. Otherwise, the team may handle this step for you. - If you are proposing a new tutorial for the Polkadot Smart Contract Cookbook, please follow the instructions in the [Polkadot Smart Contract Cookbook](#polkadot-smart-contract-cookbook) section. From 4853bfb0fbda1bedfcdb1f7a44ef910888bd7013 Mon Sep 17 00:00:00 2001 From: nhussein11 Date: Tue, 2 Sep 2025 14:58:13 -0300 Subject: [PATCH 7/7] Clarify the tutorial submission process in CONTRIBUTING.md by specifying to fork the polkadot-cookbook before creating a new branch. --- CONTRIBUTING.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index f367b73..92d5689 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -74,7 +74,7 @@ To contribute to the Polkadot SDK Cookbook, please follow these instructions: - List of tools, versions, and technologies used (eg. Polkadot-API@1.110.0, ParaSpell@0.4.0, etc.) 2. Wait for approval -3. Once approved, create a new branch for the new tutorial: +3. Once approved, fork the polkadot-cookbook and create a new branch for your new tutorial: ```bash git checkout -b feat/tutorial-