From 0df24bea42ad072f5aee761394aaabd843db9c6e Mon Sep 17 00:00:00 2001 From: Shivani-gslab Date: Fri, 15 Nov 2024 12:02:29 +0530 Subject: [PATCH 01/16] Doc: Adding contribution guide for eos_cli_config_gen --- .../authoring_eos_cli_config_gen.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md new file mode 100644 index 00000000000..075ce848ed0 --- /dev/null +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -0,0 +1,75 @@ + + +# Contribution Guide for `eos_cli_config_gen` role + +This document outlines the steps and checklist for contributing to the `eos_cli_config_gen` role under Arista AVD. + +## Steps to add a new feature to eos_cli_config_gen role + +### Schema creation + +Add the schema for new feature as per EOS CLI to the appropriate schema fragments file in the `pyavd/_eos_cli_config_gen/schema/schema_fragments` directory or create a new schema file if adding a top-level feature. + +#### Schema Guidelines + +1. **Primary Key Placement:** For list-type data-models, place primary keys at the top, for readability. +2. **Key Naming:** +- Follow EOS CLI for key names, when creating new schema keys. +- Use plural for keys that represent multiple elements (e.g., sample_policies). +3. **Descriptions:** +- Only add descriptions to the keys when they provide additional context beyond the key name. +- Refer Arista docs for description content. +- Ensure all descriptions end with punctuation. +- Highlight the key names in description, like - ``. +4. **Type Conversion:** Add `convert_types: [str]` for `type: int` keys. +5. **Defaults:** Avoid using `defaults` in eos_cli_config_gen. + +### Creating Jinja2 Templates + +Edit the appropriate Jinja2 templates in `pyavd/_eos_cli_config_gen/j2templates/eos` and `pyavd/_eos_cli_config_gen/j2templates/documentation` to generate the desired configuration and documentation. + +Add new template if adding a top-level feature, also modify the `pyavd/_eos_cli_config_gen/j2templates/eos-device-documentation.j2` and `pyavd/_eos_cli_config_gen/j2templateseos-intended-config.j2` to add these new templates, trying to respect the order in the EOS CLI. + +#### Jinja2 Templates Guidelines + +1. **Code Indentation:** Keep less indented code to improve readability. +2. **Variable Naming:** Use meaningful variable names. +3. **Natural Sorting:** Use `arista.avd.natural_sort` for sorting the `for loops` after checking on EOS CLI. +4. **Defined Checks:** +- Avoid `arista.avd.defined` check for parent keys when directly checking for child keys. +- No need to add `arista.avd.defined` check When using `arista.avd.default()` filter. +5. **Password Security:** Do not display passwords or password types in documentation template; use +`arista.avd.hide_passwords` filter. +6. **Config Order:** Ensure the order of configuration matches EOS CLI. +7. **Exclamation Marks:** Place exclamation marks `!` correctly as per the EOS running-config. +8. Along with EOS config template, update the documentation template as well (if required). +9. Implement only those commands whoes output is seen on EOS device running-config. + +### Build Schemas and Documentation + +Run `pre-commit run schemas --all` to re-generate the eos_cli_config_gen schema with any modifications. This command should be executed every time the schema is changed, even if only a description is updated. +It also updates the documentation with new options. + +### Add Molecule Tests + +Add some molecule tests in the `ansible_collections/arista/avd/molecule/eos_cli_config_gen` scenario exercising the new knob configuration. + +When marking any key as "deprecated," move the related tests to the `eos_cli_config_gen_deprecated_vars` molecule scenario and add any missing tests if necessary. + +### Run Molecule Tests + +Run `molecule converge -s eos_cli_config_gen` from the path `ansible_collections/arista/avd/` to execute the molecule tests locally and generate the new expected configuration and documentation for newly added test-cases. + +### Run Pre-commit Checks + +Run all pre-commit checks `pre-commit run --all` to ensure that all files added or modified are correctly following the coding standards and formatting rules. +Running these checks also ensures that the changes pass CI checks. + +### Self Review The Changes + +Before pushing the changes to GitHub, carefully review all modifications. +Confirm that all new features work as intended and that existing features are unaffected. Once satisfied, proceed to push the changes to the repository. From 112a30c9bac91d5913dcc560b11c4eef2034b891 Mon Sep 17 00:00:00 2001 From: Shivani-gslab Date: Fri, 15 Nov 2024 16:31:40 +0530 Subject: [PATCH 02/16] Added review checklist --- .../authoring_eos_cli_config_gen.md | 29 +++++++++++++++---- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md index 075ce848ed0..a3bf6120eeb 100644 --- a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -32,7 +32,7 @@ Add the schema for new feature as per EOS CLI to the appropriate schema fragment Edit the appropriate Jinja2 templates in `pyavd/_eos_cli_config_gen/j2templates/eos` and `pyavd/_eos_cli_config_gen/j2templates/documentation` to generate the desired configuration and documentation. -Add new template if adding a top-level feature, also modify the `pyavd/_eos_cli_config_gen/j2templates/eos-device-documentation.j2` and `pyavd/_eos_cli_config_gen/j2templateseos-intended-config.j2` to add these new templates, trying to respect the order in the EOS CLI. +Add new template if adding a top-level feature, also modify the `pyavd/_eos_cli_config_gen/j2templates/eos-device-documentation.j2` and `pyavd/_eos_cli_config_gen/j2templates/eos-intended-config.j2` to add these new templates, trying to respect the order in the EOS CLI. #### Jinja2 Templates Guidelines @@ -42,12 +42,11 @@ Add new template if adding a top-level feature, also modify the `pyavd/_eos_cli_ 4. **Defined Checks:** - Avoid `arista.avd.defined` check for parent keys when directly checking for child keys. - No need to add `arista.avd.defined` check When using `arista.avd.default()` filter. -5. **Password Security:** Do not display passwords or password types in documentation template; use -`arista.avd.hide_passwords` filter. -6. **Config Order:** Ensure the order of configuration matches EOS CLI. +5. **Password Security:** Avoid displaying passwords in the documentation template and use the `arista.avd.hide_passwords` filter to hide it. +6. **Config Order:** Ensure the order and indentation of configuration matches EOS CLI. 7. **Exclamation Marks:** Place exclamation marks `!` correctly as per the EOS running-config. 8. Along with EOS config template, update the documentation template as well (if required). -9. Implement only those commands whoes output is seen on EOS device running-config. +9. Implement only commands visible in running-config of the EOS device. ### Build Schemas and Documentation @@ -64,6 +63,11 @@ When marking any key as "deprecated," move the related tests to the `eos_cli_con Run `molecule converge -s eos_cli_config_gen` from the path `ansible_collections/arista/avd/` to execute the molecule tests locally and generate the new expected configuration and documentation for newly added test-cases. +### Update Documentation + +If the proposed feature requires any changes to the documentation, make sure to update it accordingly. +If there are any breaking changes introduced, document them in the porting guide. + ### Run Pre-commit Checks Run all pre-commit checks `pre-commit run --all` to ensure that all files added or modified are correctly following the coding standards and formatting rules. @@ -73,3 +77,18 @@ Running these checks also ensures that the changes pass CI checks. Before pushing the changes to GitHub, carefully review all modifications. Confirm that all new features work as intended and that existing features are unaffected. Once satisfied, proceed to push the changes to the repository. + +## Checklist to review an eos_cli_config_gen PR + +1. Check that all the CI checks are passing. +2. If the PR addresses an issue raised in the repository, confirm that the issue is fully resolved by the PR. +3. Refer to the Arista documentation for a deeper understanding of the proposed feature. +4. Verify that the schema adheres to EOS CLI standards and all relevant guidelines mentioned above. +5. Ensure that Jinja2 templates follow all the guidelines mentioned above. +6. Check that the template generates valid configuration and documentation, maintaining the same configuration order and indentation as EOS CLI. +7. Check out the PR in a local IDE and run all tests to ensure functionality. +8. Test the generated configuration through EAPI or CVP in the ATD lab. +9. If providing code suggestions, test them locally to ensure that your proposals work as intended. +10. Check that the molecule tests are added for the new feature. +11. If any keys are marked as deprecated, ensure that the associated tests are moved to the `eos_cli_config_gen_deprecated_vars` scenario. +12. If the proposed feature requires any changes to the documentation, ensure that it is updated accordingly. From a43aa6db20b7d24fdb8533bcd1519a5bf6d11de2 Mon Sep 17 00:00:00 2001 From: Shivani-gslab Date: Fri, 15 Nov 2024 17:19:33 +0530 Subject: [PATCH 03/16] Few modifications --- .../authoring_eos_cli_config_gen.md | 21 +++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md index a3bf6120eeb..7d5443f1e1e 100644 --- a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -14,6 +14,8 @@ This document outlines the steps and checklist for contributing to the `eos_cli_ Add the schema for new feature as per EOS CLI to the appropriate schema fragments file in the `pyavd/_eos_cli_config_gen/schema/schema_fragments` directory or create a new schema file if adding a top-level feature. +Please refer to the schema documentation for details on the various keys in the schema: [Schema Documentation](https://avd.arista.com/5.0/docs/contribution/input-variable-validation.html#schema-details). + #### Schema Guidelines 1. **Primary Key Placement:** For list-type data-models, place primary keys at the top, for readability. @@ -22,7 +24,7 @@ Add the schema for new feature as per EOS CLI to the appropriate schema fragment - Use plural for keys that represent multiple elements (e.g., sample_policies). 3. **Descriptions:** - Only add descriptions to the keys when they provide additional context beyond the key name. -- Refer Arista docs for description content. +- Refer Arista documentation for description content. - Ensure all descriptions end with punctuation. - Highlight the key names in description, like - ``. 4. **Type Conversion:** Add `convert_types: [str]` for `type: int` keys. @@ -30,23 +32,26 @@ Add the schema for new feature as per EOS CLI to the appropriate schema fragment ### Creating Jinja2 Templates -Edit the appropriate Jinja2 templates in `pyavd/_eos_cli_config_gen/j2templates/eos` and `pyavd/_eos_cli_config_gen/j2templates/documentation` to generate the desired configuration and documentation. +Edit the appropriate jinja2 templates in `pyavd/_eos_cli_config_gen/j2templates/eos` and `pyavd/_eos_cli_config_gen/j2templates/documentation` to generate the desired configuration and documentation. -Add new template if adding a top-level feature, also modify the `pyavd/_eos_cli_config_gen/j2templates/eos-device-documentation.j2` and `pyavd/_eos_cli_config_gen/j2templates/eos-intended-config.j2` to add these new templates, trying to respect the order in the EOS CLI. +Add new jinja2 template if adding a top-level feature, also modify the `pyavd/_eos_cli_config_gen/j2templates/eos-intended-config.j2` and `pyavd/_eos_cli_config_gen/j2templates/eos-device-documentation.j2` to add these new templates, trying to respect the order in the EOS CLI. #### Jinja2 Templates Guidelines 1. **Code Indentation:** Keep less indented code to improve readability. 2. **Variable Naming:** Use meaningful variable names. +3. **Use AVD filters:** Use AVD filters for code optimization - [AVD Filters](https://avd.arista.com/5.0/docs/plugins/Filter_plugins/add_md_toc.html). 3. **Natural Sorting:** Use `arista.avd.natural_sort` for sorting the `for loops` after checking on EOS CLI. 4. **Defined Checks:** - Avoid `arista.avd.defined` check for parent keys when directly checking for child keys. -- No need to add `arista.avd.defined` check When using `arista.avd.default()` filter. +- Avoid `arista.avd.defined` check for primary and required keys. +- Avoid`arista.avd.defined` check when using `arista.avd.default()` and `arista.avd.natural_sort` filters. 5. **Password Security:** Avoid displaying passwords in the documentation template and use the `arista.avd.hide_passwords` filter to hide it. 6. **Config Order:** Ensure the order and indentation of configuration matches EOS CLI. 7. **Exclamation Marks:** Place exclamation marks `!` correctly as per the EOS running-config. 8. Along with EOS config template, update the documentation template as well (if required). 9. Implement only commands visible in running-config of the EOS device. +10. Validate the template using j2lint tool, run `pre-commit run j2lint --all`. ### Build Schemas and Documentation @@ -63,6 +68,8 @@ When marking any key as "deprecated," move the related tests to the `eos_cli_con Run `molecule converge -s eos_cli_config_gen` from the path `ansible_collections/arista/avd/` to execute the molecule tests locally and generate the new expected configuration and documentation for newly added test-cases. +Check the PyAVD test coverage report by running `tox -e coverage,report` and work on improving the coverage where possible. + ### Update Documentation If the proposed feature requires any changes to the documentation, make sure to update it accordingly. @@ -75,7 +82,7 @@ Running these checks also ensures that the changes pass CI checks. ### Self Review The Changes -Before pushing the changes to GitHub, carefully review all modifications. +Before pushing the changes to GitHub, carefully review all the modifications. Confirm that all new features work as intended and that existing features are unaffected. Once satisfied, proceed to push the changes to the repository. ## Checklist to review an eos_cli_config_gen PR @@ -83,7 +90,8 @@ Confirm that all new features work as intended and that existing features are un 1. Check that all the CI checks are passing. 2. If the PR addresses an issue raised in the repository, confirm that the issue is fully resolved by the PR. 3. Refer to the Arista documentation for a deeper understanding of the proposed feature. -4. Verify that the schema adheres to EOS CLI standards and all relevant guidelines mentioned above. +4. Verify that the schema adheres to EOS CLI and all relevant guidelines mentioned above. +5. Ensure that the min/max values are specified in the schema if they are defined in the EOS CLI. 5. Ensure that Jinja2 templates follow all the guidelines mentioned above. 6. Check that the template generates valid configuration and documentation, maintaining the same configuration order and indentation as EOS CLI. 7. Check out the PR in a local IDE and run all tests to ensure functionality. @@ -92,3 +100,4 @@ Confirm that all new features work as intended and that existing features are un 10. Check that the molecule tests are added for the new feature. 11. If any keys are marked as deprecated, ensure that the associated tests are moved to the `eos_cli_config_gen_deprecated_vars` scenario. 12. If the proposed feature requires any changes to the documentation, ensure that it is updated accordingly. +13. Approve the PR if everything looks good. From 728d0e56933a9f320b4a6738ab9011fed60e9298 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 15 Nov 2024 11:54:24 +0000 Subject: [PATCH 04/16] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- .../contribution/authoring_eos_cli_config_gen.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md index 7d5443f1e1e..3aa2a6cb221 100644 --- a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -19,14 +19,18 @@ Please refer to the schema documentation for details on the various keys in the #### Schema Guidelines 1. **Primary Key Placement:** For list-type data-models, place primary keys at the top, for readability. -2. **Key Naming:** +2. **Key Naming:** + - Follow EOS CLI for key names, when creating new schema keys. - Use plural for keys that represent multiple elements (e.g., sample_policies). -3. **Descriptions:** + +3. **Descriptions:** + - Only add descriptions to the keys when they provide additional context beyond the key name. - Refer Arista documentation for description content. - Ensure all descriptions end with punctuation. - Highlight the key names in description, like - ``. + 4. **Type Conversion:** Add `convert_types: [str]` for `type: int` keys. 5. **Defaults:** Avoid using `defaults` in eos_cli_config_gen. @@ -42,10 +46,12 @@ Add new jinja2 template if adding a top-level feature, also modify the `pyavd/_e 2. **Variable Naming:** Use meaningful variable names. 3. **Use AVD filters:** Use AVD filters for code optimization - [AVD Filters](https://avd.arista.com/5.0/docs/plugins/Filter_plugins/add_md_toc.html). 3. **Natural Sorting:** Use `arista.avd.natural_sort` for sorting the `for loops` after checking on EOS CLI. -4. **Defined Checks:** +4. **Defined Checks:** + - Avoid `arista.avd.defined` check for parent keys when directly checking for child keys. - Avoid `arista.avd.defined` check for primary and required keys. - Avoid`arista.avd.defined` check when using `arista.avd.default()` and `arista.avd.natural_sort` filters. + 5. **Password Security:** Avoid displaying passwords in the documentation template and use the `arista.avd.hide_passwords` filter to hide it. 6. **Config Order:** Ensure the order and indentation of configuration matches EOS CLI. 7. **Exclamation Marks:** Place exclamation marks `!` correctly as per the EOS running-config. @@ -55,7 +61,7 @@ Add new jinja2 template if adding a top-level feature, also modify the `pyavd/_e ### Build Schemas and Documentation -Run `pre-commit run schemas --all` to re-generate the eos_cli_config_gen schema with any modifications. This command should be executed every time the schema is changed, even if only a description is updated. +Run `pre-commit run schemas --all` to re-generate the eos_cli_config_gen schema with any modifications. This command should be executed every time the schema is changed, even if only a description is updated. It also updates the documentation with new options. ### Add Molecule Tests From a3036f1acb21e1dd0fe5698fe0a8273c4de0ac8c Mon Sep 17 00:00:00 2001 From: Shivani-gslab Date: Fri, 15 Nov 2024 17:35:34 +0530 Subject: [PATCH 05/16] Add step for env creation --- .../avd/docs/contribution/authoring_eos_cli_config_gen.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md index 3aa2a6cb221..9fcc799f551 100644 --- a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -10,6 +10,10 @@ This document outlines the steps and checklist for contributing to the `eos_cli_ ## Steps to add a new feature to eos_cli_config_gen role +### Prepare development environment + +Follow the [Development Tooling Guide](https://avd.arista.com/5.0/docs/contribution/development-tooling.html). + ### Schema creation Add the schema for new feature as per EOS CLI to the appropriate schema fragments file in the `pyavd/_eos_cli_config_gen/schema/schema_fragments` directory or create a new schema file if adding a top-level feature. From 10722d35b7d268f84369081b30891fb06d8a5b0c Mon Sep 17 00:00:00 2001 From: Shivani-gslab Date: Fri, 15 Nov 2024 18:12:27 +0530 Subject: [PATCH 06/16] Fix pre-commit --- .../authoring_eos_cli_config_gen.md | 58 +++++++++---------- 1 file changed, 26 insertions(+), 32 deletions(-) diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md index 9fcc799f551..d4bf2251295 100644 --- a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -24,17 +24,13 @@ Please refer to the schema documentation for details on the various keys in the 1. **Primary Key Placement:** For list-type data-models, place primary keys at the top, for readability. 2. **Key Naming:** - -- Follow EOS CLI for key names, when creating new schema keys. -- Use plural for keys that represent multiple elements (e.g., sample_policies). - + - Follow EOS CLI for key names, when creating new schema keys. + - Use plural for keys that represent multiple elements (e.g., sample_policies). 3. **Descriptions:** - -- Only add descriptions to the keys when they provide additional context beyond the key name. -- Refer Arista documentation for description content. -- Ensure all descriptions end with punctuation. -- Highlight the key names in description, like - ``. - + - Only add descriptions to the keys when they provide additional context beyond the key name. + - Refer Arista documentation for description content. + - Ensure all descriptions end with punctuation. + - Highlight the key names in description, like - ``. 4. **Type Conversion:** Add `convert_types: [str]` for `type: int` keys. 5. **Defaults:** Avoid using `defaults` in eos_cli_config_gen. @@ -49,19 +45,17 @@ Add new jinja2 template if adding a top-level feature, also modify the `pyavd/_e 1. **Code Indentation:** Keep less indented code to improve readability. 2. **Variable Naming:** Use meaningful variable names. 3. **Use AVD filters:** Use AVD filters for code optimization - [AVD Filters](https://avd.arista.com/5.0/docs/plugins/Filter_plugins/add_md_toc.html). -3. **Natural Sorting:** Use `arista.avd.natural_sort` for sorting the `for loops` after checking on EOS CLI. -4. **Defined Checks:** - -- Avoid `arista.avd.defined` check for parent keys when directly checking for child keys. -- Avoid `arista.avd.defined` check for primary and required keys. -- Avoid`arista.avd.defined` check when using `arista.avd.default()` and `arista.avd.natural_sort` filters. - -5. **Password Security:** Avoid displaying passwords in the documentation template and use the `arista.avd.hide_passwords` filter to hide it. -6. **Config Order:** Ensure the order and indentation of configuration matches EOS CLI. -7. **Exclamation Marks:** Place exclamation marks `!` correctly as per the EOS running-config. -8. Along with EOS config template, update the documentation template as well (if required). -9. Implement only commands visible in running-config of the EOS device. -10. Validate the template using j2lint tool, run `pre-commit run j2lint --all`. +4. **Natural Sorting:** Use `arista.avd.natural_sort` for sorting the `for loops` after checking on EOS CLI. +5. **Defined Checks:** + - Avoid `arista.avd.defined` check for parent keys when directly checking for child keys. + - Avoid `arista.avd.defined` check for primary and required keys. + - Avoid`arista.avd.defined` check when using `arista.avd.default()` and `arista.avd.natural_sort` filters. +6. **Password Security:** Avoid displaying passwords in the documentation template and use the `arista.avd.hide_passwords` filter to hide it. +7. **Config Order:** Ensure the order and indentation of configuration matches EOS CLI. +8. **Exclamation Marks:** Place exclamation marks `!` correctly as per the EOS running-config. +9. Along with EOS config template, update the documentation template as well (if required). +10. Implement only commands visible in running-config of the EOS device. +11. Validate the template using j2lint tool, run `pre-commit run j2lint --all`. ### Build Schemas and Documentation @@ -102,12 +96,12 @@ Confirm that all new features work as intended and that existing features are un 3. Refer to the Arista documentation for a deeper understanding of the proposed feature. 4. Verify that the schema adheres to EOS CLI and all relevant guidelines mentioned above. 5. Ensure that the min/max values are specified in the schema if they are defined in the EOS CLI. -5. Ensure that Jinja2 templates follow all the guidelines mentioned above. -6. Check that the template generates valid configuration and documentation, maintaining the same configuration order and indentation as EOS CLI. -7. Check out the PR in a local IDE and run all tests to ensure functionality. -8. Test the generated configuration through EAPI or CVP in the ATD lab. -9. If providing code suggestions, test them locally to ensure that your proposals work as intended. -10. Check that the molecule tests are added for the new feature. -11. If any keys are marked as deprecated, ensure that the associated tests are moved to the `eos_cli_config_gen_deprecated_vars` scenario. -12. If the proposed feature requires any changes to the documentation, ensure that it is updated accordingly. -13. Approve the PR if everything looks good. +6. Ensure that Jinja2 templates follow all the guidelines mentioned above. +7. Check that the template generates valid configuration and documentation, maintaining the same configuration order and indentation as EOS CLI. +8. Check out the PR in a local IDE and run all tests to ensure functionality. +9. Test the generated configuration through EAPI or CVP in the ATD lab. +10. If providing code suggestions, test them locally to ensure that your proposals work as intended. +11. Check that the molecule tests are added for the new feature. +12. If any keys are marked as deprecated, ensure that the associated tests are moved to the `eos_cli_config_gen_deprecated_vars` scenario. +13. If the proposed feature requires any changes to the documentation, ensure that it is updated accordingly. +14. Approve the PR if everything looks good. From b2e8453554d7f5a8d87c454516fd5c1a2e3f2b6b Mon Sep 17 00:00:00 2001 From: Shivani-gslab Date: Mon, 18 Nov 2024 12:20:16 +0530 Subject: [PATCH 07/16] Update schema guidelines --- .../arista/avd/docs/contribution/authoring_eos_cli_config_gen.md | 1 + 1 file changed, 1 insertion(+) diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md index d4bf2251295..0d49fd9de14 100644 --- a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -33,6 +33,7 @@ Please refer to the schema documentation for details on the various keys in the - Highlight the key names in description, like - ``. 4. **Type Conversion:** Add `convert_types: [str]` for `type: int` keys. 5. **Defaults:** Avoid using `defaults` in eos_cli_config_gen. +6. **Min/Max:** Specify min/max values in the schema if they are defined in the EOS CLI. ### Creating Jinja2 Templates From c92c919505419ae44281afbed58ccf3342c095cf Mon Sep 17 00:00:00 2001 From: Shivani-gslab <145646625+Shivani-gslab@users.noreply.github.com> Date: Tue, 19 Nov 2024 14:46:19 +0530 Subject: [PATCH 08/16] Apply suggestions from code review Co-authored-by: Claus Holbech --- .../contribution/authoring_eos_cli_config_gen.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md index 0d49fd9de14..d65e4db2717 100644 --- a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -4,11 +4,11 @@ ~ that can be found in the LICENSE file. --> -# Contribution Guide for `eos_cli_config_gen` role +# Contribution Guide for the `eos_cli_config_gen` role This document outlines the steps and checklist for contributing to the `eos_cli_config_gen` role under Arista AVD. -## Steps to add a new feature to eos_cli_config_gen role +## Steps to add a new feature to the `eos_cli_config_gen` role ### Prepare development environment @@ -32,19 +32,19 @@ Please refer to the schema documentation for details on the various keys in the - Ensure all descriptions end with punctuation. - Highlight the key names in description, like - ``. 4. **Type Conversion:** Add `convert_types: [str]` for `type: int` keys. -5. **Defaults:** Avoid using `defaults` in eos_cli_config_gen. -6. **Min/Max:** Specify min/max values in the schema if they are defined in the EOS CLI. +5. **Defaults:** Avoid using `default` in eos_cli_config_gen. +6. **Min/Max:** Specify min/max values in the schema if they are defined in the EOS CLI. Make sure to check on different hardware platforms. ### Creating Jinja2 Templates Edit the appropriate jinja2 templates in `pyavd/_eos_cli_config_gen/j2templates/eos` and `pyavd/_eos_cli_config_gen/j2templates/documentation` to generate the desired configuration and documentation. -Add new jinja2 template if adding a top-level feature, also modify the `pyavd/_eos_cli_config_gen/j2templates/eos-intended-config.j2` and `pyavd/_eos_cli_config_gen/j2templates/eos-device-documentation.j2` to add these new templates, trying to respect the order in the EOS CLI. +Add a new jinja2 template if adding a top-level feature, also modify the `pyavd/_eos_cli_config_gen/j2templates/eos-intended-config.j2` and `pyavd/_eos_cli_config_gen/j2templates/eos-device-documentation.j2` to add these new templates, trying to respect the order in the EOS CLI. #### Jinja2 Templates Guidelines 1. **Code Indentation:** Keep less indented code to improve readability. -2. **Variable Naming:** Use meaningful variable names. +2. **Variable Naming:** Use meaningful variable names. Avoid short variables like `ei` for `ethernet_interface` 3. **Use AVD filters:** Use AVD filters for code optimization - [AVD Filters](https://avd.arista.com/5.0/docs/plugins/Filter_plugins/add_md_toc.html). 4. **Natural Sorting:** Use `arista.avd.natural_sort` for sorting the `for loops` after checking on EOS CLI. 5. **Defined Checks:** @@ -55,7 +55,7 @@ Add new jinja2 template if adding a top-level feature, also modify the `pyavd/_e 7. **Config Order:** Ensure the order and indentation of configuration matches EOS CLI. 8. **Exclamation Marks:** Place exclamation marks `!` correctly as per the EOS running-config. 9. Along with EOS config template, update the documentation template as well (if required). -10. Implement only commands visible in running-config of the EOS device. +10. Implement only commands visible in `show running-config all` of the EOS device. We should not hide config if given by the user. 11. Validate the template using j2lint tool, run `pre-commit run j2lint --all`. ### Build Schemas and Documentation @@ -67,7 +67,7 @@ It also updates the documentation with new options. Add some molecule tests in the `ansible_collections/arista/avd/molecule/eos_cli_config_gen` scenario exercising the new knob configuration. -When marking any key as "deprecated," move the related tests to the `eos_cli_config_gen_deprecated_vars` molecule scenario and add any missing tests if necessary. +When marking any key as "deprecated", move the related tests to the `eos_cli_config_gen_deprecated_vars` molecule scenario and add any missing tests if necessary. ### Run Molecule Tests From 49d0f1327054db81cf534677dce0215b978f7499 Mon Sep 17 00:00:00 2001 From: Shivani-gslab Date: Tue, 19 Nov 2024 15:03:09 +0530 Subject: [PATCH 09/16] Fix comments --- .../avd/docs/contribution/authoring_eos_cli_config_gen.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md index d65e4db2717..62067c5e0cc 100644 --- a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -31,9 +31,12 @@ Please refer to the schema documentation for details on the various keys in the - Refer Arista documentation for description content. - Ensure all descriptions end with punctuation. - Highlight the key names in description, like - ``. -4. **Type Conversion:** Add `convert_types: [str]` for `type: int` keys. +4. **Type Conversion:** + - Add `convert_types: [str]` for `type: int` keys. + - Add `convert_types: [int]` for `type: str` if it can be numeric. 5. **Defaults:** Avoid using `default` in eos_cli_config_gen. 6. **Min/Max:** Specify min/max values in the schema if they are defined in the EOS CLI. Make sure to check on different hardware platforms. +7. **Valid_Values:** Specify valid options in the schema as per the EOS CLI and ensure compatibility across different hardware platforms. ### Creating Jinja2 Templates From a47f4986c8f3936d59240f20980e3e7b9d538b60 Mon Sep 17 00:00:00 2001 From: Shivani-gslab Date: Thu, 21 Nov 2024 12:15:50 +0530 Subject: [PATCH 10/16] Fix comments --- .../authoring_eos_cli_config_gen.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md index 62067c5e0cc..e6b507bca48 100644 --- a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -37,6 +37,7 @@ Please refer to the schema documentation for details on the various keys in the 5. **Defaults:** Avoid using `default` in eos_cli_config_gen. 6. **Min/Max:** Specify min/max values in the schema if they are defined in the EOS CLI. Make sure to check on different hardware platforms. 7. **Valid_Values:** Specify valid options in the schema as per the EOS CLI and ensure compatibility across different hardware platforms. +8. **Required key:** Mark the key as required with `required: true`, if it is mandatory to generate the configuration. ### Creating Jinja2 Templates @@ -99,13 +100,14 @@ Confirm that all new features work as intended and that existing features are un 2. If the PR addresses an issue raised in the repository, confirm that the issue is fully resolved by the PR. 3. Refer to the Arista documentation for a deeper understanding of the proposed feature. 4. Verify that the schema adheres to EOS CLI and all relevant guidelines mentioned above. -5. Ensure that the min/max values are specified in the schema if they are defined in the EOS CLI. -6. Ensure that Jinja2 templates follow all the guidelines mentioned above. -7. Check that the template generates valid configuration and documentation, maintaining the same configuration order and indentation as EOS CLI. -8. Check out the PR in a local IDE and run all tests to ensure functionality. -9. Test the generated configuration through EAPI or CVP in the ATD lab. -10. If providing code suggestions, test them locally to ensure that your proposals work as intended. -11. Check that the molecule tests are added for the new feature. -12. If any keys are marked as deprecated, ensure that the associated tests are moved to the `eos_cli_config_gen_deprecated_vars` scenario. -13. If the proposed feature requires any changes to the documentation, ensure that it is updated accordingly. -14. Approve the PR if everything looks good. +5. Ensure that the min/max and valid-values are specified in the schema if they are defined in the EOS CLI. +6. Ensure the key is marked as required, if it is mandatory for generating the configuration. +7. Ensure that Jinja2 templates follow all the guidelines mentioned above. +8. Check that the template generates valid configuration and documentation, maintaining the same configuration order and indentation as EOS CLI. +9. Check out the PR in a local IDE and run all tests to ensure functionality. +10. Test the generated configuration through EAPI or CVP in the ATD lab. +11. If providing code suggestions, test them locally to ensure that your proposals work as intended. +12. Check that the molecule tests are added for the new feature. +13. If any keys are marked as deprecated, ensure that the associated tests are moved to the `eos_cli_config_gen_deprecated_vars` scenario. +14. If the proposed feature requires any changes to the documentation, ensure that it is updated accordingly. +15. Approve the PR if everything looks good. From b89cdc0a97dd16937c6fc1d186f4df5a1fb02a7f Mon Sep 17 00:00:00 2001 From: Shivani-gslab Date: Thu, 21 Nov 2024 13:09:52 +0530 Subject: [PATCH 11/16] Remove required key guide --- .../authoring_eos_cli_config_gen.md | 20 +++++++++---------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md index e6b507bca48..ca030b87e97 100644 --- a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -37,7 +37,6 @@ Please refer to the schema documentation for details on the various keys in the 5. **Defaults:** Avoid using `default` in eos_cli_config_gen. 6. **Min/Max:** Specify min/max values in the schema if they are defined in the EOS CLI. Make sure to check on different hardware platforms. 7. **Valid_Values:** Specify valid options in the schema as per the EOS CLI and ensure compatibility across different hardware platforms. -8. **Required key:** Mark the key as required with `required: true`, if it is mandatory to generate the configuration. ### Creating Jinja2 Templates @@ -101,13 +100,12 @@ Confirm that all new features work as intended and that existing features are un 3. Refer to the Arista documentation for a deeper understanding of the proposed feature. 4. Verify that the schema adheres to EOS CLI and all relevant guidelines mentioned above. 5. Ensure that the min/max and valid-values are specified in the schema if they are defined in the EOS CLI. -6. Ensure the key is marked as required, if it is mandatory for generating the configuration. -7. Ensure that Jinja2 templates follow all the guidelines mentioned above. -8. Check that the template generates valid configuration and documentation, maintaining the same configuration order and indentation as EOS CLI. -9. Check out the PR in a local IDE and run all tests to ensure functionality. -10. Test the generated configuration through EAPI or CVP in the ATD lab. -11. If providing code suggestions, test them locally to ensure that your proposals work as intended. -12. Check that the molecule tests are added for the new feature. -13. If any keys are marked as deprecated, ensure that the associated tests are moved to the `eos_cli_config_gen_deprecated_vars` scenario. -14. If the proposed feature requires any changes to the documentation, ensure that it is updated accordingly. -15. Approve the PR if everything looks good. +6. Ensure that Jinja2 templates follow all the guidelines mentioned above. +7. Check that the template generates valid configuration and documentation, maintaining the same configuration order and indentation as EOS CLI. +8. Check out the PR in a local IDE and run all tests to ensure functionality. +9. Test the generated configuration through EAPI or CVP in the ATD lab. +10. If providing code suggestions, test them locally to ensure that your proposals work as intended. +11. Check that the molecule tests are added for the new feature. +12. If any keys are marked as deprecated, ensure that the associated tests are moved to the `eos_cli_config_gen_deprecated_vars` scenario. +13. If the proposed feature requires any changes to the documentation, ensure that it is updated accordingly. +14. Approve the PR if everything looks good. From 44b11d6d0b41a60b5c83bb4aaa8255829eff50ec Mon Sep 17 00:00:00 2001 From: Shivani-gslab <145646625+Shivani-gslab@users.noreply.github.com> Date: Tue, 26 Nov 2024 11:33:44 +0530 Subject: [PATCH 12/16] Apply suggestions from code review Co-authored-by: Guillaume Mulocher --- .../docs/contribution/authoring_eos_cli_config_gen.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md index ca030b87e97..2881e55e083 100644 --- a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -12,11 +12,11 @@ This document outlines the steps and checklist for contributing to the `eos_cli_ ### Prepare development environment -Follow the [Development Tooling Guide](https://avd.arista.com/5.0/docs/contribution/development-tooling.html). +Follow the [Development Tooling Guide](https://avd.arista.com/stable/docs/contribution/development-tooling.html). ### Schema creation -Add the schema for new feature as per EOS CLI to the appropriate schema fragments file in the `pyavd/_eos_cli_config_gen/schema/schema_fragments` directory or create a new schema file if adding a top-level feature. +Add the schema for new feature as per EOS CLI to the appropriate schema fragments file in the `python-avd/pyavd/_eos_cli_config_gen/schema/schema_fragments` directory or create a new schema file if adding a top-level feature. Please refer to the schema documentation for details on the various keys in the schema: [Schema Documentation](https://avd.arista.com/5.0/docs/contribution/input-variable-validation.html#schema-details). @@ -40,9 +40,9 @@ Please refer to the schema documentation for details on the various keys in the ### Creating Jinja2 Templates -Edit the appropriate jinja2 templates in `pyavd/_eos_cli_config_gen/j2templates/eos` and `pyavd/_eos_cli_config_gen/j2templates/documentation` to generate the desired configuration and documentation. +Edit the appropriate Jinja2 templates in `pyavd/_eos_cli_config_gen/j2templates/eos` and `pyavd/_eos_cli_config_gen/j2templates/documentation` to generate the desired configuration and documentation. -Add a new jinja2 template if adding a top-level feature, also modify the `pyavd/_eos_cli_config_gen/j2templates/eos-intended-config.j2` and `pyavd/_eos_cli_config_gen/j2templates/eos-device-documentation.j2` to add these new templates, trying to respect the order in the EOS CLI. +When adding a top-level feature, add a new jinja2 template following the naming convention and modify the `pyavd/_eos_cli_config_gen/j2templates/eos-intended-config.j2` and `pyavd/_eos_cli_config_gen/j2templates/eos-device-documentation.j2` to add these new templates where relevant, in particular to respect EOS CLI order. #### Jinja2 Templates Guidelines @@ -102,7 +102,7 @@ Confirm that all new features work as intended and that existing features are un 5. Ensure that the min/max and valid-values are specified in the schema if they are defined in the EOS CLI. 6. Ensure that Jinja2 templates follow all the guidelines mentioned above. 7. Check that the template generates valid configuration and documentation, maintaining the same configuration order and indentation as EOS CLI. -8. Check out the PR in a local IDE and run all tests to ensure functionality. +8. Check out the PR in a local IDE using the instructions in the PR comment and run all tests to ensure functionality. 9. Test the generated configuration through EAPI or CVP in the ATD lab. 10. If providing code suggestions, test them locally to ensure that your proposals work as intended. 11. Check that the molecule tests are added for the new feature. From f2dd5a52fec37eb68426093fa6bb06df3b7166bf Mon Sep 17 00:00:00 2001 From: Shivani-gslab Date: Tue, 26 Nov 2024 13:08:48 +0530 Subject: [PATCH 13/16] Fixing review comments --- .../authoring_eos_cli_config_gen.md | 82 +++++++++++-------- mkdocs.yml | 1 + 2 files changed, 51 insertions(+), 32 deletions(-) diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md index 2881e55e083..8a2326d877e 100644 --- a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -10,15 +10,25 @@ This document outlines the steps and checklist for contributing to the `eos_cli_ ## Steps to add a new feature to the `eos_cli_config_gen` role +1. Prepare development environment. +2. Create the schema. +3. Develop Jinja2 templates (eos and documentation). +4. Build schemas and generate documentation. +5. Validate With Molecule Tests +6. Update documentation as needed. +7. Run pre-commit checks to ensure compliance. +8. Review all changes before submission. +9. Raise a PR to the Arista AVD GitHub repository + ### Prepare development environment -Follow the [Development Tooling Guide](https://avd.arista.com/stable/docs/contribution/development-tooling.html). +Follow the [Development Tooling Guide](development-tooling.md). ### Schema creation Add the schema for new feature as per EOS CLI to the appropriate schema fragments file in the `python-avd/pyavd/_eos_cli_config_gen/schema/schema_fragments` directory or create a new schema file if adding a top-level feature. -Please refer to the schema documentation for details on the various keys in the schema: [Schema Documentation](https://avd.arista.com/5.0/docs/contribution/input-variable-validation.html#schema-details). +Please refer to the schema documentation for details on the various keys in the schema: [Schema Documentation](input-variable-validation.md). #### Schema Guidelines @@ -40,15 +50,15 @@ Please refer to the schema documentation for details on the various keys in the ### Creating Jinja2 Templates -Edit the appropriate Jinja2 templates in `pyavd/_eos_cli_config_gen/j2templates/eos` and `pyavd/_eos_cli_config_gen/j2templates/documentation` to generate the desired configuration and documentation. +Edit the appropriate Jinja2 templates in `python-avd/pyavd/_eos_cli_config_gen/j2templates/eos` and `python-avd/pyavd/_eos_cli_config_gen/j2templates/documentation` to generate the desired configuration and documentation. -When adding a top-level feature, add a new jinja2 template following the naming convention and modify the `pyavd/_eos_cli_config_gen/j2templates/eos-intended-config.j2` and `pyavd/_eos_cli_config_gen/j2templates/eos-device-documentation.j2` to add these new templates where relevant, in particular to respect EOS CLI order. +When adding a top-level feature, add a new Jinja2 template following the naming convention and modify the `python-avd/pyavd/_eos_cli_config_gen/j2templates/eos-intended-config.j2` and `python-avd/pyavd/_eos_cli_config_gen/j2templates/eos-device-documentation.j2` to add these new templates where relevant, in particular to respect EOS CLI order. #### Jinja2 Templates Guidelines 1. **Code Indentation:** Keep less indented code to improve readability. 2. **Variable Naming:** Use meaningful variable names. Avoid short variables like `ei` for `ethernet_interface` -3. **Use AVD filters:** Use AVD filters for code optimization - [AVD Filters](https://avd.arista.com/5.0/docs/plugins/Filter_plugins/add_md_toc.html). +3. **Use AVD filters:** Use AVD filters for code optimization - [AVD Filters](../plugins/Filter_plugins/). 4. **Natural Sorting:** Use `arista.avd.natural_sort` for sorting the `for loops` after checking on EOS CLI. 5. **Defined Checks:** - Avoid `arista.avd.defined` check for parent keys when directly checking for child keys. @@ -66,46 +76,54 @@ When adding a top-level feature, add a new jinja2 template following the naming Run `pre-commit run schemas --all` to re-generate the eos_cli_config_gen schema with any modifications. This command should be executed every time the schema is changed, even if only a description is updated. It also updates the documentation with new options. -### Add Molecule Tests - -Add some molecule tests in the `ansible_collections/arista/avd/molecule/eos_cli_config_gen` scenario exercising the new knob configuration. - -When marking any key as "deprecated", move the related tests to the `eos_cli_config_gen_deprecated_vars` molecule scenario and add any missing tests if necessary. - -### Run Molecule Tests +### Validate With Molecule Tests -Run `molecule converge -s eos_cli_config_gen` from the path `ansible_collections/arista/avd/` to execute the molecule tests locally and generate the new expected configuration and documentation for newly added test-cases. - -Check the PyAVD test coverage report by running `tox -e coverage,report` and work on improving the coverage where possible. +1. Add some molecule tests in the `ansible_collections/arista/avd/molecule/eos_cli_config_gen` scenario exercising the new knob configuration. +2. Update the `host_vars` files: + - Modify or add the `molecule/eos_cli_config_gen/host_vars/hostX/xxx.yml` file to include the new configuration knobs. + - If multiple files are required to cover all the test cases: + - Add the additional test cases to the next host directory, e.g., `host_vars/host2/xxx.yml`, `host_vars/host3/xxx.yml`, etc. + - Ensure each file represents unique scenarios or configurations to validate different combinations. + - Ensure that the new keys are thoroughly tested with various valid values and edge cases. +3. When marking any key as "deprecated", move the related tests to the `eos_cli_config_gen_deprecated_vars` molecule scenario and add any missing tests if necessary. +4. Run `molecule converge -s eos_cli_config_gen` from the path `ansible_collections/arista/avd/` to execute the molecule tests locally and generate the new expected configuration and documentation for newly added test-cases. +5. Check the PyAVD test coverage report by running `tox -e coverage,report` and work on improving the coverage where possible. ### Update Documentation -If the proposed feature requires any changes to the documentation, make sure to update it accordingly. -If there are any breaking changes introduced, document them in the porting guide. +1. If the proposed feature requires any changes to the documentation, make sure to update it accordingly. +2. If there are any breaking changes introduced, document them in the porting guide. ### Run Pre-commit Checks -Run all pre-commit checks `pre-commit run --all` to ensure that all files added or modified are correctly following the coding standards and formatting rules. -Running these checks also ensures that the changes pass CI checks. +Run all pre-commit checks `pre-commit run --all` to ensure that all files added or modified are correctly following the coding standards and formatting rules. Running these checks also ensures that the changes pass CI checks. ### Self Review The Changes -Before pushing the changes to GitHub, carefully review all the modifications. -Confirm that all new features work as intended and that existing features are unaffected. Once satisfied, proceed to push the changes to the repository. +1. Before pushing the changes to GitHub, carefully review all the modifications. +2. Confirm that all new features work as intended and that existing features are unaffected. +3. Once satisfied, proceed to push the changes to the repository. + +### Raise a PR to the Arista AVD GitHub repository + +1. After completing the self-review, raise a pull request (PR) to the Arista AVD GitHub repository for further review and integration. +2. Use draft PRs when the changes are not ready for review. +3. Tag maintainers with questions, even after pushing changes, for clarity and guidance, or discuss in the related issue if needed. ## Checklist to review an eos_cli_config_gen PR 1. Check that all the CI checks are passing. 2. If the PR addresses an issue raised in the repository, confirm that the issue is fully resolved by the PR. 3. Refer to the Arista documentation for a deeper understanding of the proposed feature. -4. Verify that the schema adheres to EOS CLI and all relevant guidelines mentioned above. -5. Ensure that the min/max and valid-values are specified in the schema if they are defined in the EOS CLI. -6. Ensure that Jinja2 templates follow all the guidelines mentioned above. -7. Check that the template generates valid configuration and documentation, maintaining the same configuration order and indentation as EOS CLI. -8. Check out the PR in a local IDE using the instructions in the PR comment and run all tests to ensure functionality. -9. Test the generated configuration through EAPI or CVP in the ATD lab. -10. If providing code suggestions, test them locally to ensure that your proposals work as intended. -11. Check that the molecule tests are added for the new feature. -12. If any keys are marked as deprecated, ensure that the associated tests are moved to the `eos_cli_config_gen_deprecated_vars` scenario. -13. If the proposed feature requires any changes to the documentation, ensure that it is updated accordingly. -14. Approve the PR if everything looks good. +4. Tag maintainers with questions or concerns regarding the proposed changes. +5. Verify that the schema adheres to EOS CLI and all relevant guidelines mentioned above. +6. Ensure that the min/max and valid-values are specified in the schema if they are defined in the EOS CLI. +7. Ensure that Jinja2 templates follow all the guidelines mentioned above. +8. Check that the template generates valid configuration and documentation, maintaining the same configuration order and indentation as EOS CLI. +9. Check out the PR in a local IDE using the instructions in the PR comment and run all tests to ensure functionality. +10. Test the generated configuration via EAPI or CVP in a relevant lab, if available. Otherwise, mention in your review comment that lab verification was not possible. +11. Add inline suggestions whenever possible, and if providing code suggestions, test them locally to ensure they work as intended. +12. Check that the molecule tests are added for the new feature. +13. If any keys are marked as deprecated, ensure that the associated tests are moved to the `eos_cli_config_gen_deprecated_vars` scenario. +14. If the proposed feature requires any changes to the documentation, ensure that it is updated accordingly. +15. Approve the PR if everything looks good. diff --git a/mkdocs.yml b/mkdocs.yml index 7e9cf520181..920dbae8b4d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -192,6 +192,7 @@ nav: - External Resources: - Ansible Collection User Guide: https://docs.ansible.com/ansible/latest/user_guide/collections_using.html - Ansible User Guide: https://docs.ansible.com/ansible/latest/user_guide/index.html + - Authoring eos_cli_config_gen Role Guide: docs/contribution/authoring_eos_cli_config_gen.md - Release Notes: docs/release-notes/5.x.x.md - Porting Guide: docs/porting-guides/5.x.x.md - PyAVD: docs/pyavd.md From 28b91f8fd13ac6e2f466ac2a5fdf0843d1dcd49f Mon Sep 17 00:00:00 2001 From: Shivani-gslab Date: Tue, 26 Nov 2024 15:13:13 +0530 Subject: [PATCH 14/16] updating build schema and documentation step --- .../docs/contribution/authoring_eos_cli_config_gen.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md index 8a2326d877e..a39d7e2286d 100644 --- a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -73,8 +73,14 @@ When adding a top-level feature, add a new Jinja2 template following the naming ### Build Schemas and Documentation -Run `pre-commit run schemas --all` to re-generate the eos_cli_config_gen schema with any modifications. This command should be executed every time the schema is changed, even if only a description is updated. -It also updates the documentation with new options. +When developing a feature, it is recommended to run from source using Ansible (either through molecule or from a test repo). This ensures that schemas and templates are automatically recompiled during the "Verify Requirements" step, as outlined in the [Development Tooling Guide](development-tooling.md). + +However, if you are using pyavd or need to manually recompile the schemas and templates for any other reason, you can run the following commands: + +`pre-commit run schemas --all` to regenerate the eos_cli_config_gen schema. +`pre-commit run templates --all` to regenerate the templates. + +These commands should be executed whenever the schema or templates are modified, even if only a description is updated. ### Validate With Molecule Tests From eb32596298801ae1083820461812dddb61f01752 Mon Sep 17 00:00:00 2001 From: Shivani-gslab <145646625+Shivani-gslab@users.noreply.github.com> Date: Tue, 26 Nov 2024 20:20:59 +0530 Subject: [PATCH 15/16] updating mkdocs.yml --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 920dbae8b4d..5956d09e32a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -189,10 +189,10 @@ nav: - Code Style: docs/contribution/style-guide.md - Validation of Input Variables: docs/contribution/input-variable-validation.md - EOS Designs internal notes: docs/contribution/eos_designs_internal_notes.md + - Authoring eos_cli_config_gen Role Guide: docs/contribution/authoring_eos_cli_config_gen.md - External Resources: - Ansible Collection User Guide: https://docs.ansible.com/ansible/latest/user_guide/collections_using.html - Ansible User Guide: https://docs.ansible.com/ansible/latest/user_guide/index.html - - Authoring eos_cli_config_gen Role Guide: docs/contribution/authoring_eos_cli_config_gen.md - Release Notes: docs/release-notes/5.x.x.md - Porting Guide: docs/porting-guides/5.x.x.md - PyAVD: docs/pyavd.md From 9c96f08d2cdbdab4c6cc2ad0c0b59f8bdc0bb7b0 Mon Sep 17 00:00:00 2001 From: Shivani-gslab Date: Thu, 28 Nov 2024 15:47:24 +0530 Subject: [PATCH 16/16] fix links and validation point --- .../docs/contribution/authoring_eos_cli_config_gen.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md index a39d7e2286d..f5f212aedde 100644 --- a/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md +++ b/ansible_collections/arista/avd/docs/contribution/authoring_eos_cli_config_gen.md @@ -22,13 +22,13 @@ This document outlines the steps and checklist for contributing to the `eos_cli_ ### Prepare development environment -Follow the [Development Tooling Guide](development-tooling.md). +Follow the [Development Tooling Guide](https://avd.arista.com/stable/docs/contribution/development-tooling.html). ### Schema creation Add the schema for new feature as per EOS CLI to the appropriate schema fragments file in the `python-avd/pyavd/_eos_cli_config_gen/schema/schema_fragments` directory or create a new schema file if adding a top-level feature. -Please refer to the schema documentation for details on the various keys in the schema: [Schema Documentation](input-variable-validation.md). +Please refer to the schema documentation for details on the various keys in the schema: [Schema Documentation](https://avd.arista.com/stable/docs/contribution/input-variable-validation.html). #### Schema Guidelines @@ -58,7 +58,7 @@ When adding a top-level feature, add a new Jinja2 template following the naming 1. **Code Indentation:** Keep less indented code to improve readability. 2. **Variable Naming:** Use meaningful variable names. Avoid short variables like `ei` for `ethernet_interface` -3. **Use AVD filters:** Use AVD filters for code optimization - [AVD Filters](../plugins/Filter_plugins/). +3. **Use AVD filters:** Use AVD filters for code optimization - [AVD Filters](https://avd.arista.com/5.1/docs/plugins/Filter_plugins/add_md_toc.html). 4. **Natural Sorting:** Use `arista.avd.natural_sort` for sorting the `for loops` after checking on EOS CLI. 5. **Defined Checks:** - Avoid `arista.avd.defined` check for parent keys when directly checking for child keys. @@ -73,7 +73,7 @@ When adding a top-level feature, add a new Jinja2 template following the naming ### Build Schemas and Documentation -When developing a feature, it is recommended to run from source using Ansible (either through molecule or from a test repo). This ensures that schemas and templates are automatically recompiled during the "Verify Requirements" step, as outlined in the [Development Tooling Guide](development-tooling.md). +When developing a feature, it is recommended to run from source using Ansible (either through molecule or from a test repo). This ensures that schemas and templates are automatically recompiled during the "Verify Requirements" step, as outlined in the [Development Tooling Guide](https://avd.arista.com/stable/docs/contribution/development-tooling.html). However, if you are using pyavd or need to manually recompile the schemas and templates for any other reason, you can run the following commands: @@ -82,7 +82,7 @@ However, if you are using pyavd or need to manually recompile the schemas and te These commands should be executed whenever the schema or templates are modified, even if only a description is updated. -### Validate With Molecule Tests +### Validate Changes and Test Configurations 1. Add some molecule tests in the `ansible_collections/arista/avd/molecule/eos_cli_config_gen` scenario exercising the new knob configuration. 2. Update the `host_vars` files: @@ -94,6 +94,7 @@ These commands should be executed whenever the schema or templates are modified, 3. When marking any key as "deprecated", move the related tests to the `eos_cli_config_gen_deprecated_vars` molecule scenario and add any missing tests if necessary. 4. Run `molecule converge -s eos_cli_config_gen` from the path `ansible_collections/arista/avd/` to execute the molecule tests locally and generate the new expected configuration and documentation for newly added test-cases. 5. Check the PyAVD test coverage report by running `tox -e coverage,report` and work on improving the coverage where possible. +6. Test the generated configuration using EAPI or CVP in a relevant lab, if available, to ensure it works as intended. ### Update Documentation