Doc: Improve contribution guide

[gmuloc]

Improve the contribution guide with details like below. Taken from a discussion, so reword to fit as a document:

---

So in general we try to avoid introducing some new knobs in eos_cli_config_gen and eos_designs in one go to make things clearer. Usually, we just recommend one PR to add the low-level CLI in eos_cli_config_gen and then a new one on top to do the eos_designs bit. Thus I will structure a list of tasks based on this assumed separation and tick the steps you have followed already.

Make sure to install the requirements-dev.txt to be able to complete the process (I believe you have already but mentioning it just in case)

eos_cli_config_gen

This part of the change is aimed at adding some new knobs. The following tasks are required:

• [x] Adding the knob to the appropriate schema fragments file in the roles/eos_cli_config_gen/schema/schema_fragments directory (or create a new file if adding a top-level feature)
• [ ] Editing the Jinja2 templates in roles/eos_cli_config_gen/templates/eos and roles/eos_cli_config_gen/templates/documentation (or adding new template if adding a top-level feature, in that case, you should also modify the roles/eos_cli_config_gen/templates/eos-device-documentation.j2 and ``roles/eos_cli_config_gen/templates/eos-intended-config.j2 to add these new templates, trying to respect the order in the EOS CLI)
  • NOTE: This one is partially done in your PR as you have modified only the ethernet-interface.j2 template for config and not the port-channel.j2 one where you have added the l2mru knob in the schema. Also for now you have not added anything to the documentation templates (it may or may not be necessary)
• [x] Run pre-commit run schemas --all to re-generate the eos_cli_config_gen schema with your modifications (you need to do this every time you change the schema, even if this is just a description changed). This is also used to add the new options to our documentation.
• [ ] Add some molecule test in n the molecule/eos_cli_config_gen scenario exercising your new knob configuration
  • NOTE: In your case you would need to add to both molecule/eos_cli_config_gen/inventory/host_vars/ethernet-interfaces.yml and molecule/eos_cli_config_gen/inventory/host_vars/port-channel-interfaces.yml (re-using existing interfaces is fine as this is only for testing purposes)
  • [ ] Run the molecule test locally to generate the new expected configuration and documentation for these two hosts (we recommend running the full scenario using from ansible_collections/arista/avd/molecule folder the command make converge MOLECULE=eos_cli_config_gen
  • [ ] Run all pre-commit checks pre-commit run --all to make sure that all files you have added are correct and won't be rejected by CI (this command will take ~1min)
  • [ ] Review that everything added looks correct and push to Github!

eos_designs

Is there anything to do in "ansible_collections/arista/avd/roles/eos_designs"... as l2_mru` is not part of a design I suppose not?

I just would like to point out that if you don't need the l2_mru in eos_designs you should remove the changes you have made to the python code there. Otherwise, there is a bit more work to do indeed. This can be done only after the eos_cli_config_gen part has been completed (hence why we usually recommend 2 PRs)

The process is very similar (for simple changes like yours) except for the jinja2 template part where you need to edit some Python code

• [ ] Adding the knob to the appropriate schema fragments file in the roles/eos_designs/schema/schema_fragments directory
  • NOTE: For you it would be eos_designs/schemas/schema_fragments/defs_adapter_config.schema.yml - something like https://github.com/aristanetworks/ansible-avd/blob/devel/ansible_collections/arista/avd/roles/eos_designs/schemas/schema_fragments/defs_adapter_config.schema.yml#L44 .
• [x] Editing the relevant python_modules
  • NOTE: This has been done for you but you now need to add the knob to the eos_designs schema for adapters or it will never be possible to use it
• [ ] Run pre-commit run schemas --all to re-generate the eos_designs schema with your modifications (you need to do this every time you change the schema, even if this is just a description changed). This is also used to add the new options to our documentation.
• [ ] Add some molecule test in n the molecule/eos_designs_unit_tests scenario exercising your new knob configuration
  • NOTE: In your case you would need to add the l2mru knob to some adapters, one for port-channel and one for ethertnet-interfaces. It may be simpler in your case to add to the molecule/eos_designs_unit_tests/inventory/host_vars/connected_endpoints.yml file
  • [ ] Run the molecule test locally to generate the new expected configuration and documentation for this two hosts (we recommend running the full scenario using from ansible_collections/arista/avd/molecule folder the command make converge MOLECULE=eos_designs_unit_tests
  • [ ] Run all pre-commit checks pre-commit run --all to make sure that all files you have added are correct and won't be rejected by CI (this command will take ~1min)
  • [ ] Review that everything added looks correct and push to Github!

Let us know if you need further help

Originally posted by @gmuloc in https://github.com/aristanetworks/ansible-avd/issues/3164#issuecomment-1735054320

[github-actions[bot]]

This issue is stale because it has been open 90 days with no activity. The issue will be reviewed by a maintainer and may be closed