[minor_changes]Adding guidelines for Ansible ACI module developement (DCNE-80)

docs/aci_collection_git_contribution_workflow.md

@@ -0,0 +1,77 @@
+# Git contribution workflow for ACI collection
+
+To contribute to the Cisco ACI Ansible Collection, follow the standard Git workflow: Fork → Clone → Branch. This ensures clean code isolation, proper tracking of changes, and allows seamless contributions via pull requests. Fork and clone tasks are carried out just once.
+The collection code is located in a git repository (https://github.com/CiscoDevNet/ansible-aci).
+
+**Step1: Fork the repository**
+
+A Fork is a personal copy of the repository under your GitHub account, allowing you to make changes without affecting the upstream project.
+
+Steps to create a fork of the repository:
+* Navigate to: https://github.com/CiscoDevNet/ansible-aci
+* Click the *Fork* button in the upper-right corner to create your fork of the CiscoDevNet's **ansible-aci** repo
+
+  Refer to GitHub's official guide of [How to fork a repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo)
+
+**Step2: Clone the forked repository**
+
+Clone allows to copy a repository to the local machine.
+
+* Clone the forked repository in the terminal using the following command:
+
+```text
+git clone https://github.com/<Forked Organization>/ansible-aci.git
+```
+
+Verify the name of the Git remote of your forked repository by running the following commands in the terminal:
+
+```text
+cd ansible-aci
+git remote -v
+```
+
+Expected output:
+
+```text
+origin        https://github.com/<Forked Organization>/ansible-aci.git (fetch)
+origin        https://github.com/<Forked Organization>/ansible-aci.git (push)
+```
+
+**Naming Convention**
+"origin" is the default name for the first Git remote of a cloned repository. In this case, it represents your forked repo where you are going to make changes, commit, and push your code to GitHub.
+
+* Add the upstream repo as a new Git remote:
+
+To be able to retrieve the latest changes made to the upstream project repo (CiscoDevNet/ansible-aci), we need to add it as a second Git remote. We recommend calling this second remote "upstream" and we will keep referring to it as upstream in the rest of the document.
+Add the original CiscoDevNet repository (CiscoDevNet/ansible-aci) as a second remote named `upstream`, which will allow the fetch, and sync the latest changes:
+
+```text
+git remote add upstream https://github.com/CiscoDevNet/ansible-aci.git
+```
+
+Adding the remote branch "upstream" is a one-time operation.
+After adding the upstream remote, update the local repository with the latest changes from the upstream repository:
+
+* Fetch and update the local `master` branch from upstream:
+
+```text
+git checkout master
+git pull upstream master
+```
+
+**Step 3: Create a Feature Branch**
+
+Branch facilitates bug fixes, addition of new features, and the integration of new versions after isolated testing. Master is the default branch of the local repository.
+Each time changes are required for a module or a new module is to be created, it is recommended that a new dedicated branch be created from master. This provides a clean branch of the latest master, enabling all necessary modifications to be made.
+
+* Create a branch from master by using the following commands on the terminal:
+
+```text
+git checkout master
+git checkout -b <new-branch-name>
+```
+
+Maintaining changes in a dedicated branch allows the master branch to remain clean and synchronized with the upstream master. This simplifies keeping the local master branch updated without the need to merge code or rebase the master branch.
+
+> [!CAUTION]
+> Never commit directly to `master`. Use feature branches for all development work to simplify merging, testing, and collaboration.

docs/aci_collection_structure.md

@@ -0,0 +1,79 @@
+# Structure of the cisco.aci collection
+
+The **ansible-aci** repository consists of directories and files as listed below:
+
+```
+ansible-aci/
+├─ plugins/
+│  ├─ modules/
+│  │  ├─ aci_l2out.py
+│  │  ├─ ...
+│  ├─ module_utils/
+│  │  ├─ aci.py
+│  │  ├─ constants.py
+│  ├─ doc_fragments/
+│  │  ├─ aci.py
+│  │  ├─ annotation.py
+│  │  ├─ owner.py
+│  ├─ httpapi/
+│  │  ├─ aci.py
+│  ├─ .../
+│  │  ├─...
+├─ tests/
+│  ├─ integration/
+│  │  ├─ inventory.networking
+│  │  ├─ targets/
+│  │  │  ├─ aci_l2out/
+│  │  │  │  ├─ tasks/
+│  │  │  │  │  ├─ main.yml
+│  │  │  ├─ .../
+│  ├─ sanity/
+│  │  ├─ requirements.txt
+│  ├─ .../
+├─ changelogs/
+│  ├─ changelog.yml
+│  ├─ config.yml
+├─ meta/
+│  ├─ runtime.yml
+├─ license
+├─ galaxy.yml
+├─ README.md
+├─ requirements.txt
+```
+
+Let's briefly go through each file and its context.
+
+## plugins
+Consists of Python code that defines different functions and capabilities of the collection.
+
+### modules
+The **modules** directory in plugins consists of Cisco ACI modules, and each module covers the functionality of an object in ACI. Any new module developed to manage an ACI object goes in this directory.
+
+### module_utils
+
+The **module_utils** directory has the aci.py file and constants.py file, which serves as a library for the modules. Most modules in the collection borrow functions from this library. These functions help a module to reduce redundancy of the code by availing code reusability. This is where one would add any function to use across multiple modules.
+
+* `constants.py`: The constants.py typically contains constant values used throughout the collection modules and utilities. These constants may include fixed strings, default values, API endpoint paths, or other static configuration parameters that support consistent and maintainable code within the collection.
+
+* `aci.py`: The aci.py file is a comprehensive utility module that facilitates interaction with the Cisco ACI APIC REST API. It provides the ACIModule class, which encapsulates the core logic for managing API communication, authentication, configuration management, and response processing.
+
+### doc_fragments
+
+The **doc_fragments** directory has the aci.py file, which serves as a plugin and is used in each module's documentation. Every module has its own documentation section, but all the modules also share some common documentation elements, such as authentication details, notes: or seealso: entries. To avoid duplication of that information in each module's documentation block, it can be saved once in doc_fragments and used by all modules.
+
+## tests
+This is where the different tests are defined. We run all sanity, unit, and integration tests on every code submission to the repository.
+
+The **integration** directory in **tests** consists of the **targets** directory, which has test directories for most of the modules present in our collection. Each module has its own test directory, and each directory is similar to an ansible role and contains a tasks directory, which contains a main.yml file. The main.yml file consists of tasks covering every functionality that a module provides. If the main.yml becomes too big, it can be split into multiple .yml files, and each of those can be imported into the main.yml file. Integration tests are run on every code submission to the repository. Every new module submission, bug fix or enhancement requires a test file or a change to an existing test file. This ensures that the code in our module is usable and robust.
+
+The **integration** directory also consists of the **inventory.networking** file, which defines the hosts, groups of hosts, and variables used by the integration tests role defined in the integration's targets directory.
+
+## changelogs
+This directory consists of a record of all the changes made to the project.
+
+The **changelog.yml** file contains a chronologically ordered list of collection versions and the changes included in those versions. This file is used to generate the changelog.rst file. The changes are categorized into major changes, minor changes and bugfixes.
+
+The **config.yml** file contains configuration options used by the ansible-changelog tool to generate the **changelog.rst** file.
+
+## galaxy.yml
+The **galaxy.yml** file is placed in the root directory of the collection. This file contains the metadata of the collection that is used to generate an ansible-aci collection object. It is also used for information in Ansible Galaxy.