You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+42-54Lines changed: 42 additions & 54 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,14 +11,12 @@ Please note we have a code of conduct, please follow it in all your interactions
11
11
-[Contributing](#contributing)
12
12
-[Table of Contents](#table-of-contents)
13
13
-[Setup](#setup)
14
-
-[MdBook](#mdbook)
14
+
-[Working with Markdown Files](#working-with-markdown-files)
15
15
-[Adding a new chapter](#adding-a-new-chapter)
16
16
-[Adding a new Cairo program](#adding-a-new-cairo-program)
17
17
-[Verification script](#verification-script)
18
18
-[Tests](#tests)
19
-
-[Use of anchor](#use-of-anchor)
20
-
-[Translations](#translations)
21
-
-[Initiate a new translation for your language](#initiate-a-new-translation-for-your-language)
19
+
-[Use of region](#use-of-region)
22
20
-[Code of Conduct](#code-of-conduct)
23
21
-[Our Pledge](#our-pledge)
24
22
-[Our Standards](#our-standards)
@@ -31,33 +29,41 @@ Please note we have a code of conduct, please follow it in all your interactions
31
29
32
30
1. Clone this repository.
33
31
34
-
2.Rust related packages:
32
+
2.Install the required dependencies using pnpm:
35
33
36
-
- Install toolchain providing `cargo` using [rustup](https://rustup.rs/).
37
-
- Install [mdBook](https://rust-lang.github.io/mdBook/guide/installation.html) and the required extension with `cargo install mdbook mdbook-i18n-helpers mdbook-last-changed `.
34
+
```
35
+
pnpm i
36
+
```
38
37
39
38
3. Install `scarb` using [asdf](https://asdf-vm.com/) with `asdf install`. Alternatively, you can install `scarb` manually by following the instructions [here](https://docs.swmansion.com/scarb/).
40
39
41
-
## MdBook
40
+
4. Start the development server:
42
41
43
-
All the Markdown files **MUST** be edited in english. To work locally in english:
42
+
```
43
+
pnpm dev
44
+
```
44
45
45
-
- Start a local server with `mdbook serve` and visit [localhost:3000](http://localhost:3000) to view the book.
46
-
You can use the `--open` flag to open the browser automatically: `mdbook serve --open`.
46
+
## Working with Markdown Files
47
47
48
-
- Make changes to the book and refresh the browser to see the changes.
48
+
All Markdown files (\*.md) MUST be edited in English. Follow these steps to work locally with Markdown files:
49
49
50
-
- Open a PR with your changes.
50
+
- Make changes to the desired .md files in your preferred text editor.
51
+
- Save the changes, and your browser window should automatically refresh to reflect the updates.
52
+
- Once you've finished making your changes, build the application to ensure everything works as expected:
53
+
```
54
+
pnpm build
55
+
```
56
+
- If everything looks good, commit your changes and open a pull request with your modifications.
51
57
52
58
## Adding a new chapter
53
59
54
-
To add a new chapter, create a new markdown file in the `src` directory. All the Markdown files **MUST** be edited in english. In order to add them to the book, you need to add a link to it in the `src/SUMMARY.md` file.
60
+
-To add a new chapter, create a new markdown file in the `pages` directory. All the Markdown files **MUST** be edited in english. In order to add them to the book, you need to add in the `vocs.config.ts` file.
55
61
56
-
Do not write directly Cairo program inside the markdown files. Instead, use code blocks that import the Cairo programs from the `listing` directory. These programs are bundled into scarb projects, which makes it easier to test and build all programs. See the next section for more details.
62
+
-Do not write directly Cairo program inside the markdown files. Instead, use code blocks that import the Cairo programs from the `listings` directory. These programs are bundled into scarb projects, which makes it easier to test and build all programs. See the next section for more details.
57
63
58
64
Be sure to check for typos with `typos`:
59
65
60
-
```shell
66
+
```bash [Terminal]
61
67
cargo install typos-cli
62
68
typos src/
63
69
```
@@ -159,7 +165,8 @@ Every listing needs to have atleast integration tests:
159
165
160
166
Add your contract in a specific file, you can name it `contract.cairo` or anything else. You can also add other files if needed.
161
167
162
-
You should add the tests in the same file as the contract, using the `#[cfg(test)]` flag and a `tests` module. With the usage of ANCHOR, the tests will not be displayed in the book but can be optionally be displayed by using the `{{#rustdoc_include ...}}` syntax.
168
+
You should add the tests in the same file as the contract, using the `#[cfg(test)]` flag and a `tests` module.
169
+
<!-- With the usage of ANCHOR, the tests will not be displayed in the book but can be optionally be displayed by using the `{{#rustdoc_include ...}}` syntax. -->
163
170
164
171
Here's a sample `lib.cairo` file:
165
172
@@ -171,9 +178,9 @@ mod contract;
171
178
And in the `contract.cairo` file:
172
179
173
180
```cairo
174
-
// ANCHOR: contract
181
+
// [!region contract]
175
182
// Write your contract here
176
-
// ANCHOR_END: contract
183
+
// [!endregion contract]
177
184
178
185
#[cfg(test)]
179
186
mod tests {
@@ -183,27 +190,26 @@ mod tests {
183
190
184
191
You can use Starknet Foundry to write and run your tests.
185
192
186
-
### Use of anchor
193
+
### Use of region
187
194
188
195
You can add delimiting comments to select part of the code in the book.
189
196
190
197
```cairo
191
198
file.cairo:
192
199
193
200
a
194
-
// ANCHOR: anchor_name
201
+
// [!region region_name]
195
202
b
196
-
// ANCHOR_END: anchor_name
203
+
// [!endregion region_name]
197
204
c
198
205
```
199
206
200
207
Then, in the markdown file, you can use the following syntax to include only the code between the delimiting comments:
To work with translations, those are the steps to update the translated content:
230
+
```cairo [tests]
231
+
// [!include ~/listings/src/contract.cairo:tests]
232
+
```
229
233
230
-
- Run a local server for the language you want to edit: `./translations.sh zh-cn` for instance. If no language is provided, the script will only extract translations from english.
231
-
232
-
- Open the translation file you are interested in `po/zh-cn.po` for instance. You can also use editors like [poedit](https://poedit.net/) to help you on this task.
233
-
234
-
- When you are done, you should only have changes into the `po/xx.po` file. Commit them and open a PR.
235
-
The PR must stars with `i18n` to let the maintainers know that the PR is only changing translation.
236
-
237
-
The translation work is inspired from [Comprehensive Rust repository](https://github.com/google/comprehensive-rust/blob/main/TRANSLATIONS.md).
238
-
239
-
You can test to build the book with all translations using the `build.sh` script and serve locally the `book` directory.
240
-
241
-
### Initiate a new translation for your language
242
-
243
-
If you wish to initiate a new translation for your language without running a local server, consider the following tips:
244
-
245
-
- Execute the command `./translations.sh new xx` (replace `xx` with your language code). This method can generate the `xx.po` file of your language for you.
246
-
- To update your `xx.po` file, execute the command `./translations.sh xx` (replace `xx` with your language code), as mentioned in the previous chapter.
247
-
- If the `xx.po` file already exists (which means you are not initiating a new translation), you should not run this command.
0 commit comments