From ba50a01c0b1fa24b6e72c9bccd53edb1a039ac68 Mon Sep 17 00:00:00 2001 From: Eric Nordelo Date: Tue, 8 Nov 2022 17:15:12 +0100 Subject: [PATCH 1/6] feat: add design patterns entry to README --- CONTRIBUTING.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 89728da3..fe4a539b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,6 +58,27 @@ As a contributor, you are expected to fork this repository, work on your own for *IMPORTANT* Please pay attention to the maintainer's feedback, since it's a necessary step to keep up with the standards OpenZeppelin Nile attains to. + +## Design Patterns + +We always try to follow best practices and design patterns to make the code readable and maintainable. While most of them are left to be decided by the PR developer and the reviewer, we require following some patterns we enforce ourselves in the package source code: + +### Hex/Int pattern + +The pattern is defined as follows: + +#### Definitions +- Internal API is the set of functions that are not meant to be called directly in scripting, tests, or any other context from users of Nile, but only internally, from other nile code (including plugins). +- Public API is the complement. + +#### Rules +- Accept and use only integers for Internal APIs (for hashes, keys, or addresses). +- Accept both hex and int from external input (from config files, starknet cli output, etc..) or Public API functions, and convert the input to int before using it internally (nile.utils.normalize_number). +- Always return int from Internal or Public API, excpet when the method explicitly declare the intention to return an hex (like hex_class_hash helper in utils). +- Convert to hex before writing to files (like in address for accounts, or class_hash for declares) to keep consistency. +- Convert to hex when is required for integrations (like starknet cli subprocess calls), right before where is needed. + + ## All set If you have any questions, feel free to post them to github.com/OpenZeppelin/nile/issues. From 107e785041c25c899ee22d551a4908ba13c8c3c2 Mon Sep 17 00:00:00 2001 From: Eric Nordelo Date: Tue, 8 Nov 2022 17:17:47 +0100 Subject: [PATCH 2/6] featL update CONTRIBUTING --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe4a539b..7a03b063 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,10 +73,10 @@ The pattern is defined as follows: #### Rules - Accept and use only integers for Internal APIs (for hashes, keys, or addresses). -- Accept both hex and int from external input (from config files, starknet cli output, etc..) or Public API functions, and convert the input to int before using it internally (nile.utils.normalize_number). -- Always return int from Internal or Public API, excpet when the method explicitly declare the intention to return an hex (like hex_class_hash helper in utils). -- Convert to hex before writing to files (like in address for accounts, or class_hash for declares) to keep consistency. -- Convert to hex when is required for integrations (like starknet cli subprocess calls), right before where is needed. +- Accept both hex and int from external input (config files, starknet cli output, etc..) or Public API functions, and convert the input to int before using it internally (nile.utils.normalize_number). +- Always return int from Internal or Public API, except when the method explicitly declares the intention to return a hex (like hex_class_hash helper in utils). +- Convert to hex before writing to files (like in address for accounts or class_hash for declares) to keep consistency. +- Convert to hex when required for integrations (like starknet cli subprocess calls), right before where it is needed. ## All set From 2a230e1985f32f4d6aab886e536018175b78ce10 Mon Sep 17 00:00:00 2001 From: Eric Nordelo Date: Tue, 8 Nov 2022 17:25:13 +0100 Subject: [PATCH 3/6] Update CONTRIBUTING.md --- CONTRIBUTING.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7a03b063..e3701847 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,22 +61,22 @@ As a contributor, you are expected to fork this repository, work on your own for ## Design Patterns -We always try to follow best practices and design patterns to make the code readable and maintainable. While most of them are left to be decided by the PR developer and the reviewer, we require following some patterns we enforce ourselves in the package source code: +We always try to follow best practices and design patterns to make the code readable and maintainable. While most of them are left to be decided by the PR developer and the reviewer, we require following some patterns we enforce ourselves, presented below: ### Hex/Int pattern The pattern is defined as follows: #### Definitions -- Internal API is the set of functions that are not meant to be called directly in scripting, tests, or any other context from users of Nile, but only internally, from other nile code (including plugins). -- Public API is the complement. +- **Internal API** is the set of functions that are not meant to be called directly in scripting, tests, or any other context from users of Nile, but only internally, from other Nile code (including plugins). +- **Public API** is the complement. #### Rules -- Accept and use only integers for Internal APIs (for hashes, keys, or addresses). -- Accept both hex and int from external input (config files, starknet cli output, etc..) or Public API functions, and convert the input to int before using it internally (nile.utils.normalize_number). -- Always return int from Internal or Public API, except when the method explicitly declares the intention to return a hex (like hex_class_hash helper in utils). -- Convert to hex before writing to files (like in address for accounts or class_hash for declares) to keep consistency. -- Convert to hex when required for integrations (like starknet cli subprocess calls), right before where it is needed. +- Accept and use **only int for Internal API** (for hashes, keys, or addresses). +- Accept **both hex and int from external input** (config files, starknet cli output, etc..) **or Public API functions**, and convert the input to int before using it internally (use `nile.utils.normalize_number`). +- Always **return int from Internal or Public API, except when the method explicitly declares the intention to return a hex** (like `nile.utils.hex_class_hash` helper). +- Convert to **hex before writing to files** (like in address for accounts or class_hash for declares) to keep consistency. +- Convert to **hex when required for integrations** (like starknet cli subprocess calls), **right before where it is needed**. ## All set From 83b9bca7895a20e09beed25552af155c2789f357 Mon Sep 17 00:00:00 2001 From: Eric Nordelo Date: Tue, 8 Nov 2022 20:31:25 +0100 Subject: [PATCH 4/6] Update CONTRIBUTING.md Co-authored-by: Andrew Fleming --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3701847..ac0e99fc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,7 +73,7 @@ The pattern is defined as follows: #### Rules - Accept and use **only int for Internal API** (for hashes, keys, or addresses). -- Accept **both hex and int from external input** (config files, starknet cli output, etc..) **or Public API functions**, and convert the input to int before using it internally (use `nile.utils.normalize_number`). +- Accept **both hex and int from external input** (config files, starknet cli output, etc.) **or Public API functions**, and convert the input to int before using it internally (use `nile.utils.normalize_number`). - Always **return int from Internal or Public API, except when the method explicitly declares the intention to return a hex** (like `nile.utils.hex_class_hash` helper). - Convert to **hex before writing to files** (like in address for accounts or class_hash for declares) to keep consistency. - Convert to **hex when required for integrations** (like starknet cli subprocess calls), **right before where it is needed**. From 51d21a48a7a8b7f136059ed868025eeddd374cd4 Mon Sep 17 00:00:00 2001 From: Eric Nordelo Date: Tue, 8 Nov 2022 20:31:47 +0100 Subject: [PATCH 5/6] Update CONTRIBUTING.md Co-authored-by: Andrew Fleming --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac0e99fc..4834f2b2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,7 +61,7 @@ As a contributor, you are expected to fork this repository, work on your own for ## Design Patterns -We always try to follow best practices and design patterns to make the code readable and maintainable. While most of them are left to be decided by the PR developer and the reviewer, we require following some patterns we enforce ourselves, presented below: +We always try to follow best practices and design patterns to make the code readable and maintainable. While most of them are left to be decided by the PR developer and the reviewer, we require following some patterns that we enforce ourselves which are presented below: ### Hex/Int pattern From 745c632dff9991dfb224871820145efff97dbf2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mart=C3=ADn=20Triay?= Date: Thu, 10 Nov 2022 23:15:34 +0100 Subject: [PATCH 6/6] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4834f2b2..e36bfcbd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,7 +68,7 @@ We always try to follow best practices and design patterns to make the code read The pattern is defined as follows: #### Definitions -- **Internal API** is the set of functions that are not meant to be called directly in scripting, tests, or any other context from users of Nile, but only internally, from other Nile code (including plugins). +- **Internal API** is the set of functions that are not meant to be called directly in scripting, tests, or any other context from users of Nile, but only internally from other Nile code (including plugins). - **Public API** is the complement. #### Rules