Skip to content

Commit 03a9eb5

Browse files
anvitha-jainanvitha-jain
committed
[minor_change] Change the format from reStructuredText file type to Markdown type.
1 parent 149b348 commit 03a9eb5

13 files changed

+1376
-1437
lines changed

‎docs/docsite/rst/fork_clone_branch_collection.rst renamed to ‎docs/aci_collection_git_contribution_workflow.md

Lines changed: 31 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
1-
Fork, Clone and Branch
2-
======================
1+
# Git contribution workflow for ACI collection
32

4-
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.
3+
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.
54
The collection code is located in a git repository (https://github.com/CiscoDevNet/ansible-aci).
65

76
**Step1: Fork the repository**
@@ -12,68 +11,67 @@ Steps to create a fork of the repository:
1211
* Navigate to: https://github.com/CiscoDevNet/ansible-aci
1312
* Click the *Fork* button in the upper-right corner to create your fork of the CiscoDevNet's **ansible-aci** repo
1413

15-
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>`_
14+
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)
1615

17-
**Step2: Clone the forked repository**
16+
**Step2: Clone the forked repository**
1817

1918
Clone allows to copy a repository to the local machine.
2019

2120
* Clone the forked repository in the terminal using the following command:
2221

23-
.. code-block:: Blocks
24-
25-
git clone https://github.com/<Forked Organization>/ansible-aci.git
22+
```text
23+
git clone https://github.com/<Forked Organization>/ansible-aci.git
24+
```
2625

2726
Verify the name of the Git remote of your forked repository by running the following commands in the terminal:
2827

29-
.. code-block:: Blocks
30-
31-
cd ansible-aci
32-
git remote -v
28+
```text
29+
cd ansible-aci
30+
git remote -v
31+
```
3332

3433
Expected output:
3534

36-
.. code-block:: Blocks
37-
35+
```text
3836
origin https://github.com/<Forked Organization>/ansible-aci.git (fetch)
3937
origin https://github.com/<Forked Organization>/ansible-aci.git (push)
38+
```
4039

4140
**Naming Convention**
42-
"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.
41+
"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.
4342

4443
* Add the upstream repo as a new Git remote:
4544

46-
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.
47-
Add the original CiscoDevNet repository (CiscoDevNet/ansible-aci) as a second remote named `upstream`, which will allow the fetch, and sync the latest changes:
48-
49-
.. code-block:: Blocks
45+
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.
46+
Add the original CiscoDevNet repository (CiscoDevNet/ansible-aci) as a second remote named `upstream`, which will allow the fetch, and sync the latest changes:
5047

51-
git remote add upstream https://github.com/CiscoDevNet/ansible-aci.git
48+
```text
49+
git remote add upstream https://github.com/CiscoDevNet/ansible-aci.git
50+
```
5251

5352
Adding the remote branch "upstream" is a one-time operation.
54-
After adding the upstream remote, update the local repository with the latest changes from the upstream repository:
53+
After adding the upstream remote, update the local repository with the latest changes from the upstream repository:
5554

5655
* Fetch and update the local `master` branch from upstream:
5756

58-
.. code-block:: Blocks
59-
60-
git checkout master
61-
git pull upstream master
57+
```text
58+
git checkout master
59+
git pull upstream master
60+
```
6261

6362
**Step 3: Create a Feature Branch**
6463

6564
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.
66-
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.
65+
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.
6766

6867
* Create a branch from master by using the following commands on the terminal:
6968

70-
.. code-block:: Blocks
71-
72-
git checkout master
73-
git checkout -b <new-branch-name>
69+
```text
70+
git checkout master
71+
git checkout -b <new-branch-name>
72+
```
7473

7574
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.
7675

77-
**Best Practice:** Never commit directly to `master`. Use feature branches for all development work to simplify merging, testing, and collaboration.
78-
79-
.. _fork_clone_branch_collection:
76+
> [!CAUTION]
77+
> Never commit directly to `master`. Use feature branches for all development work to simplify merging, testing, and collaboration.

‎docs/aci_collection_structure.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Structure of the cisco.aci collection
2+
3+
The **ansible-aci** repository consists of directories and files as listed below:
4+
5+
```
6+
ansible-aci/
7+
├─ plugins/
8+
│ ├─ modules/
9+
│ │ ├─ aci_l2out.py
10+
│ │ ├─ ...
11+
│ ├─ module_utils/
12+
│ │ ├─ aci.py
13+
│ │ ├─ constants.py
14+
│ ├─ doc_fragments/
15+
│ │ ├─ aci.py
16+
│ │ ├─ annotation.py
17+
│ │ ├─ owner.py
18+
│ ├─ httpapi/
19+
│ │ ├─ aci.py
20+
│ ├─ .../
21+
│ │ ├─...
22+
├─ tests/
23+
│ ├─ integration/
24+
│ │ ├─ inventory.networking
25+
│ │ ├─ targets/
26+
│ │ │ ├─ aci_l2out/
27+
│ │ │ │ ├─ tasks/
28+
│ │ │ │ │ ├─ main.yml
29+
│ │ │ ├─ .../
30+
│ ├─ sanity/
31+
│ │ ├─ requirements.txt
32+
│ ├─ .../
33+
├─ changelogs/
34+
│ ├─ changelog.yml
35+
│ ├─ config.yml
36+
├─ meta/
37+
│ ├─ runtime.yml
38+
├─ license
39+
├─ galaxy.yml
40+
├─ README.md
41+
├─ requirements.txt
42+
```
43+
44+
Let's briefly go through each file and its context.
45+
46+
## plugins
47+
Consists of Python code that defines different functions and capabilities of the collection.
48+
49+
### modules
50+
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.
51+
52+
### module_utils
53+
54+
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.
55+
56+
* `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.
57+
58+
* `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.
59+
60+
### doc_fragments
61+
62+
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.
63+
64+
## tests
65+
This is where the different tests are defined. We run all sanity, unit, and integration tests on every code submission to the repository.
66+
67+
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.
68+
69+
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.
70+
71+
## changelogs
72+
This directory consists of a record of all the changes made to the project.
73+
74+
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.
75+
76+
The **config.yml** file contains configuration options used by the ansible-changelog tool to generate the **changelog.rst** file.
77+
78+
## galaxy.yml
79+
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.

0 commit comments

Comments
 (0)