From 950421f32a81ff2d1c04793ee77d35868bcd1d7b Mon Sep 17 00:00:00 2001 From: David Hawig Date: Thu, 13 Jul 2023 10:58:24 +0200 Subject: [PATCH 1/7] Update README.md Initial clean up --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 8d76c5198..ccca845a2 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,8 @@ # Polkadot Protocol Specification -Polkadot is a replicated sharded state machine designed to resolve the scalability and interoperability among blockchains. This repository contains the official specification for the Polkadot Protocol. - -The latest releases of the *Polkadot Protocol Specification* can be found on [spec.polkadot.network](https://spec.polkadot.network) or on our [GitHub Releases page](https://github.com/w3f/polkadot-spec/releases). +## Intorduction -This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. +This repository contains the official specification for the [Polkadot Protocol](https://polkadot.network/). The latest releases of the *Polkadot Protocol Specification* can be found on [spec.polkadot.network](https://spec.polkadot.network) or our [GitHub Releases page](https://github.com/w3f/polkadot-spec/releases). ## Local Development From 271f13099628ab78c301bfb5e5a71f6480896080 Mon Sep 17 00:00:00 2001 From: David Hawig Date: Thu, 13 Jul 2023 14:17:47 +0200 Subject: [PATCH 2/7] Update README.md Draft Spec Committee --- README.md | 49 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 40 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index ccca845a2..4abb3fce2 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,40 @@ # Polkadot Protocol Specification +- [Introduction](#intorduction) +- [Process](#process) +- [Local Development](#local-development) +- [Formatting](#formatting) + - [LaTeX](#latex) + - [Numeration System](#numeration-system) + - [Chapters](#chapters) + - [Sections](#sections) + - [Definitions](#definitions) + - [Algorithms](#algorithms) + - [Tables and Images](#tables-and-images) + - [References](#references) + - [Bibliography](#bibliography) + - [Broken Links](#broken-links) +- [License](#license) + ## Intorduction This repository contains the official specification for the [Polkadot Protocol](https://polkadot.network/). The latest releases of the *Polkadot Protocol Specification* can be found on [spec.polkadot.network](https://spec.polkadot.network) or our [GitHub Releases page](https://github.com/w3f/polkadot-spec/releases). +## Process + +Everyone, but specifically implementers and members of the [Technical Fellowship](https://wiki.polkadot.network/docs/learn-polkadot-opengov#the-technical-fellowship), are welcome to open PRs to this repo and contribute to the specification. A PR is merged as soon as two members of the Spec Committee accept the PR. + +### Spec Committee + +The Spec Committee consists of Researchers, Researcher Engineers, and Implementers of the Polkadot Protocol that actively contribute (= opening/contributing to PRs or issues regarding the spec) to the specification. For now and compared to the [Technical Fellowship](https://github.com/polkadot-fellows/manifesto) itself, the responsibility of the Spec Committee is clearly defined as maintaining the specification of the protocol. In case of inactivity for three months, members will be removed again. + +- [Bhargav Bhatt](https://github.com/bhargavbh) +- [Seyed Lavasani](https://github.com/drskalman) +- [Pierre Krieger](https://github.com/tomaka) +- [Heverson B. Ribeiro](https://github.com/heversonbr) + +## Spec Committee + ## Local Development To clone, build and serve the website locally, run the following commands: @@ -18,24 +49,24 @@ npm run build # or build_with_kaitai to also rebuild kaitai SVG files npm run serve ``` -If you already have the repo cloned, remember to update it and the submodule before doing any changes: +If you already have the repo cloned, remember to update it and the submodule before making any changes: ```bash git pull git submodule update --remote ``` -Because of the "complex" build, unfortunately you can't see the changes in real time, if you directly edit the `docs` folder. There are two workarounds: -- use a Markdown plugin or editor (e.g. the extension [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) for VSCode) to see the changes in real time. You won't be able to see the placeholders rendered and other elements, but you'll be able to render the markdown and latex; +Because of the "complex" build, you can't see the changes in real time if you directly edit the `docs` folder. There are two workarounds: +- use a Markdown plugin or editor (e.g., the extension [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) for VSCode) to see the changes in real time. You won't be able to see the placeholders rendered and other elements, but you'll be able to render the markdown and latex; -- build the website a first time, then run `npm run start` instead of `npm run serve`, and edit the files inside the `website/docs` folder. This will allow you to see the changes in real time, but you have to remember to bring the changes inside the `docs` folder before committing. Also, in this way, you can't put the placeholders and other elements inside the markdown files of `website/docs` as they wouldn't be rendered. - -## Contributing +- build the website the first time, then run `npm run start` instead of `npm run serve,` and edit the files inside the `website/docs` folder. This will allow you to see the changes in real time, but you have to remember to bring the changes inside the `docs` folder before committing. Also, in this way, you can't put the placeholders and other elements inside the markdown files of `website/docs` as they wouldn't be rendered. You can find the markdown files inside the [`docs`](docs) folder. When building, the scripts inside [`preBuild`](https://github.com/w3f/polkadot-spec-website/tree/main/preBuild) will generate a `docs` folder, from which Docusaurus will render the website. Then, the rendered content will be modified by the [`plugins`](https://github.com/w3f/polkadot-spec-website/tree/main/plugins) in the browser. +## Formatting + ### LaTeX You can use LaTeX inside the markdown files using the following syntax: @@ -176,7 +207,7 @@ or ```md ###### Image -img-num- Name {#img-name} ``` -For these two entities you won't need to use any component or admonition. +For these two entities, you won't need to use any component or admonition. #### References @@ -198,8 +229,8 @@ Automatically, the bibliography will be generated at the end of the page. ### Broken Links -During the `preBuild`, the external links in the markdown files will be checked.
-After the `build`, the internal links will be checked.
+During the `preBuild,` the external links in the markdown files will be checked.
+After the `build,` the internal links will be checked.
If any link is broken, the console will show a warning.
Refer to [`checkBrokenInternalLinks/index.ts`](https://github.com/w3f/polkadot-spec-website/tree/main/plugins/checkBrokenInternalLinks/index.ts) and [`checkBrokenExternalLinks/index.ts`](https://github.com/w3f/polkadot-spec-website/tree/main/preBuild/checkBrokenExternalLinks/index.ts). From 24d61332ddb413db97a17ee4de858683370513f4 Mon Sep 17 00:00:00 2001 From: David Hawig Date: Thu, 13 Jul 2023 16:55:35 +0200 Subject: [PATCH 3/7] Update README.md Co-authored-by: caso --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 4abb3fce2..1d52917bf 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,6 @@ The Spec Committee consists of Researchers, Researcher Engineers, and Implemente - [Pierre Krieger](https://github.com/tomaka) - [Heverson B. Ribeiro](https://github.com/heversonbr) -## Spec Committee ## Local Development From 87884476f1b9ec8894c7621fe90dea0672d74655 Mon Sep 17 00:00:00 2001 From: David Hawig Date: Mon, 24 Jul 2023 09:40:04 +0200 Subject: [PATCH 4/7] Update README.md Update Committee --- README.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1d52917bf..1ffa85a8a 100644 --- a/README.md +++ b/README.md @@ -26,13 +26,18 @@ Everyone, but specifically implementers and members of the [Technical Fellowship ### Spec Committee -The Spec Committee consists of Researchers, Researcher Engineers, and Implementers of the Polkadot Protocol that actively contribute (= opening/contributing to PRs or issues regarding the spec) to the specification. For now and compared to the [Technical Fellowship](https://github.com/polkadot-fellows/manifesto) itself, the responsibility of the Spec Committee is clearly defined as maintaining the specification of the protocol. In case of inactivity for three months, members will be removed again. +The Spec Committee consists of Researchers, Researcher Engineers, and Implementers of the Polkadot Protocol that actively contribute (= opening/contributing to PRs or issues regarding the spec) to the specification. For now and compared to the [Technical Fellowship](https://github.com/polkadot-fellows/manifesto), the Spec Committee's responsibility is clearly defined as maintaining the specification of the protocol. In case of inactivity for three months, members will be removed again. +Web3 Foundation - [Bhargav Bhatt](https://github.com/bhargavbh) - [Seyed Lavasani](https://github.com/drskalman) -- [Pierre Krieger](https://github.com/tomaka) - [Heverson B. Ribeiro](https://github.com/heversonbr) +Smoldot +- [Pierre Krieger](https://github.com/tomaka) + +Parity +- [Fateme Shirazi](https://github.com/FatemeShirazi) ## Local Development From 4a52bc0f75923add230ecffe998c8fd22bb8d785 Mon Sep 17 00:00:00 2001 From: David Hawig Date: Tue, 25 Jul 2023 07:29:07 +0200 Subject: [PATCH 5/7] Update README.md Add Kamil --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 1ffa85a8a..f29dac530 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,9 @@ Web3 Foundation - [Seyed Lavasani](https://github.com/drskalman) - [Heverson B. Ribeiro](https://github.com/heversonbr) +Soramitsu +- [Kamil Salakhiev](https://github.com/kamilsa) + Smoldot - [Pierre Krieger](https://github.com/tomaka) From 6e2b099a25beb1691a898eb4d1c92318f45beb7a Mon Sep 17 00:00:00 2001 From: David Hawig Date: Tue, 25 Jul 2023 10:36:14 +0200 Subject: [PATCH 6/7] Update README.md Quadrivium instead of Soramitsu --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f29dac530..5e713b423 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Web3 Foundation - [Seyed Lavasani](https://github.com/drskalman) - [Heverson B. Ribeiro](https://github.com/heversonbr) -Soramitsu +Quadrivium - [Kamil Salakhiev](https://github.com/kamilsa) Smoldot From 51b9be68405a6d67e670fec05972bb63ca4b056c Mon Sep 17 00:00:00 2001 From: David Hawig Date: Wed, 6 Sep 2023 16:53:59 +0200 Subject: [PATCH 7/7] Update README.md Add myself, as requested --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 5e713b423..510582107 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,7 @@ The Spec Committee consists of Researchers, Researcher Engineers, and Implemente Web3 Foundation - [Bhargav Bhatt](https://github.com/bhargavbh) +- [David Hawig](https://github.com/Noc2) - [Seyed Lavasani](https://github.com/drskalman) - [Heverson B. Ribeiro](https://github.com/heversonbr)